Skip to content

CHANGELOG.md

Latest commit

 

History

History
1155 lines (888 loc) · 73.1 KB

CHANGELOG.md

File metadata and controls

1155 lines (888 loc) · 73.1 KB

Changelog

All notable changes to Construct CLI will be documented in this file.

[1.7.1] - 2026-04-20

Added

  • Daemon Restart Command: New construct sys daemon restart command that stops and starts the daemon container in one operation. Handles all container states: missing (starts), stopped (cleans up and starts), and running (stops then starts).

[1.7.0] - 2026-04-16

Added

  • Host Service Bridge: New [bridge] configuration section that allows sandboxed containers to access services running on the host machine. This enables AI agents to connect to local databases, APIs, and development servers without leaving the isolated environment.
  • Cross-Platform Gateway Detection: Automatic host gateway IP detection supporting Docker (host-gateway, host.docker.internal), Podman (host.containers.internal), and network interface inspection across macOS, Linux, and WSL.
  • Service Environment Variables: For each configured host service, automatically injects CONSTRUCT_<SERVICE>_HOST, CONSTRUCT_<SERVICE>_PORT, and CONSTRUCT_<SERVICE>_URL environment variables, plus CONSTRUCT_HOST_IP for the detected gateway.
  • Configurable Failure Behavior: on_failure option in [bridge] section allows users to choose behavior when gateway detection fails: "warn" (default, continue with warning), "fail" (stop container startup), or "silent" (continue silently).
  • Manual Host IP Override: Advanced manual_host_ip option for users who need to specify a custom host IP when automatic detection fails or for non-standard network setups.
  • AgentMemory Integration: Out-of-the-box support for AgentMemory persistent memory server. Configure services = ["agentmemory:3111"] to enable AI agents to remember context across sessions while running in complete isolation.

Changed

  • Docker Compose Override: Enhanced docker-compose.override.yml generation to dynamically inject extra_hosts configuration based on [bridge] settings and detected host gateway.
  • Container Environment Injection: Extended environment variable assembly to include host service connection details when bridge is enabled.

Security

  • Opt-In Security Model: Host service bridge is disabled by default (enabled = false) and must be explicitly enabled by users. This maintains construct-cli's security-first approach while providing flexibility for development workflows.
  • Gateway Validation: Host gateway detection includes multiple validation methods and fallback mechanisms to ensure reliability while preventing accidental host exposure.

Documentation

  • Configuration Reference: Added comprehensive [bridge] section documentation in default config.toml template with usage examples and security considerations.
  • Cross-Platform Support: Documented platform-specific detection methods and troubleshooting steps for each container runtime.

[1.6.4] - 2026-04-11

Added

  • Hide Secrets Allowlist: Added hide_secrets_allow_paths configuration option to exclude specific files from redaction. This allows tools that must read files directly (like AWS CLI with ~/.aws/credentials) to bypass secret redaction while keeping the security model intact.
  • Content-Based Scanning: Enhanced secret detection with ripgrep integration for fast pattern-based scanning across all project files.
  • Stream-Time Output Masking: Added regex-based secret pattern matching in stdout/stderr to catch API keys, tokens, and credentials in agent output.

Changed

  • Help Text Simplified: Removed verbose Network Management and Agent Examples sections from main help output for better scannability. Users can access detailed help via namespace-specific commands (construct network --help).
  • Help Text Alignment: Fixed column alignment in help text - all descriptions and continuation lines now align properly for improved readability.
  • CLI Command Syntax: Corrected documentation to use construct <agent> instead of non-existent construct run <agent> syntax across all documentation files.

Fixed

  • Hide Secrets Experiment Notice: Suppressed "hide_secrets=off" message for users who haven't enabled the experimental feature, preventing unnecessary noise.
  • Code Lint Issues: Fixed ineffassign lint error in scanner.go by removing unused args assignment.

Documentation

  • Comprehensive Documentation Restructure: Created 8 new user-facing documentation files organized by topic:
    • docs/HIDE-SECRETS.md - Complete secret redaction user guide
    • docs/INSTALLATION.md - Platform-specific installation instructions
    • docs/CONFIGURATION.md - Complete configuration reference
    • docs/SECURITY.md - Security features and best practices
    • docs/PROVIDERS.md - Custom Claude API endpoint configuration
    • docs/PACKAGES.md - Package management guide
    • docs/AGENTS.md - Complete agent reference
    • docs/INDEX.md - Documentation navigation hub
  • README Streamlining: Reduced README from ~500 lines to ~100 lines with links to detailed documentation.

[1.6.3] - 2026-04-08

Fixed

  • Codex Image Paste Reliability (Non-Daemon): Added a dedicated Codex Python PTY wrapper (construct-codex-wrapper-v1) that intercepts paste keystrokes, fetches PNG data from the host clipboard bridge, saves it in .construct-clipboard/, and injects the file path directly into Codex input. This removes dependence on fragile terminal/X11 clipboard internals.
  • Copilot PTY Recursion / PTY Exhaustion: Fixed wrapper installation logic to avoid overwriting or self-targeting the real npm-global copilot binary, preventing recursive wrapper launches and OSError: out of pty devices.
  • Copilot Wrapper Install Robustness: Hardened wrapper path selection to install at the active PATH-resolved binary while preserving the true npm-global target for execution.
  • Clipboard Debug Coverage: Expanded construct sys clipboard-debug with Codex wrapper diagnostics (which codex, wrapper marker/version, _REAL target, wrapper log tail) to make Codex paste failures directly actionable.

Changed

  • CI Lint Toolchain Pin: Updated CI golangci-lint pin from v2.10.1 to v2.11.4 in build and release workflows; aligned local Makefile CI pin message to 2.11.4.
  • Codex Clipboard Architecture: Retired the legacy Codex WSL/powershell clipboard fallback path in favor of PTY-wrapper-first handling.
  • Entrypoint Clipboard Behavior: Clarified runtime behavior so Codex is excluded from optional X11 sync startup because Codex paste now routes through PTY interception.

Removed

  • Legacy Codex WSL Clipboard Fallback: Removed WSL env injection (WSL_DISTRO_NAME, WSL_INTEROP, forced DISPLAY) from run/exec/daemon env assembly for Codex.
  • powershell.exe Shim Path: Removed the fake powershell.exe template and all associated embedding/init/migration/runtime references.
  • Legacy Codex WSL Docs/Diagnostics: Removed stale WSL/powershell references from clipboard diagnostics and architecture documentation.

Documentation

  • Clipboard & Architecture Docs Refresh: Updated docs/CLIPBOARD.md and docs/ARCHITECTURE-DESIGN.md to reflect the new PTY-wrapper model for Codex, Copilot wrapper v9, and removal of the WSL/powershell fallback path.

[1.6.2] - 2026-04-06

Fixed

  • Claude Code Update False Failure: claude update exits non-zero when already up-to-date, causing topgrade to report Claude Code: FAILED in the summary even though no update was needed. Fixed by appending || true to the command in both the embedded topgrade.toml template and the dynamically generated topgrade config (GenerateTopgradeConfig).

[1.6.0] - 2026-04-02

Added

  • Crush CLI Agent Support: Added Charmbracelet Crush (crush) as a first-class agent, installed via npm (@charmland/crush), with agent mount registration, AGENTS.md global rules path wiring, help/docs updates, and post-install/post-update verification checks.

Changed

  • Yolo Agent Coverage: Added crush to yolo flag handling (--yolo) and updated supported-agent documentation comments.
  • Agent Install Detection: Included crush in initial agent-installed detection checks used after image build/setup.
  • Alias UX Messaging: Updated shell alias onboarding copy to include crush among example sandboxed commands.

Fixed

  • Yolo Supported List Accuracy: Corrected README yolo-supported slug list to match runtime behavior.
  • Agent Additions Log Completeness: Updated AGENTS.md entry for Crush to include all touched integration files.

[1.5.2] - 2026-03-22

Fixed

  • Copilot Image Paste via PTY Wrapper: Replaced the non-functional JS clipboard bridge approach with a Python PTY wrapper that intercepts paste keystrokes at the outer Docker PTY layer, fetches the image from the host clipboard bridge, saves it to .construct-clipboard/, and injects @path as typed text into Copilot's input. The JS bridge never fired in headless environments because Copilot's internal clipboard module had no display to read from.
  • Kitty Keyboard Protocol (KKP) Support: Modern terminals (Ghostty and others using KKP) send Ctrl+V and Cmd+V as CSI-u escape sequences (\x1b[118;5u and \x1b[118;9u) rather than the legacy \x16 control byte. The wrapper now intercepts all three variants via _handle_paste().
  • PTY Wrapper PATH Shadowing: The wrapper is installed at /home/linuxbrew/.linuxbrew/bin/copilot (the Homebrew bin, which takes PATH priority) rather than ~/.local/bin/copilot which was silently bypassed. The real copilot binary path (~/.npm-global/bin/copilot) is resolved via npm-global candidates and injected at install time so Node's relative module imports resolve correctly.
  • Clipboard Diagnostic Improvements: sys clipboard-debug now shows the resolved which copilot path, the wrapper version, the _REAL binary path, and the full wrapper log tail for Copilot sessions.

[1.5.1] - 2026-03-20

Fixed

  • SSH Agent Access in Daemon Sessions (Linux): Fixed a regression where agents running via exec into a warm daemon container on Linux could not see the forwarded SSH agent. Injected SSH_AUTH_SOCK=/ssh-agent into the environment for all daemon and attachment exec flows.
  • Claude & Copilot Image Pasting (Headless/Linux): Enabled reliable image pasting for Claude Code and GitHub Copilot in headless environments by forcing XDG_SESSION_TYPE=wayland, routing clipboard requests through the clipper bridge.
  • Multimodal Paste Routing: Added claude and copilot to the file-based paste agent list so they correctly receive @path references for pasted images instead of raw binary data.

Added

  • Regression Coverage for Headless Clipboard: Added unit tests ensuring claude, pi, and copilot receive required environment variables for headless clipboard routing.
  • Regression Coverage for Daemon SSH Agent: Added verification for SSH_AUTH_SOCK injection in daemon execution environments on Linux.

[1.5.0] - 2026-03-19

Added

  • Generic Environment Variable Passthrough: Added first-class [sandbox].env_passthrough support so users can forward arbitrary host environment variables into Construct without editing compose overrides.
  • Prefix-Based Env Auto-Pass: Added [sandbox].env_passthrough_prefixes with default ["CNSTR_"], allowing host vars like CNSTR_CONTEXT7_API_KEY to appear inside Construct as CONTEXT7_API_KEY.
  • Default Auth Passthroughs: Fresh configs now include GITHUB_TOKEN and CONTEXT7_API_KEY in sandbox.env_passthrough by default.
  • Regression Coverage for Env Forwarding: Added tests covering explicit env passthrough, CNSTR_ prefix stripping, precedence rules, fresh-run flag injection, daemon exec env assembly, and template/default-config drift.

Changed

  • Env Precedence Rules: Explicit sandbox.env_passthrough keys now win over prefix-derived CNSTR_ passthrough when both target the same inside variable name.
  • Documentation: Updated README and architecture docs to document generic env passthrough, default forwarded keys, and the new CNSTR_ auto-pass behavior.

[1.4.6] - 2026-03-18

Fixed

  • NPM Global Package Updates: sys update now upgrades npm global packages to their latest versions. Previously, topgrade's npm update -g respected caret semver ranges and would not cross minor/major version boundaries (e.g., 0.58.4 would never reach 0.60.0). Disabled topgrade's npm step and replaced it with explicit npm install -g <pkg>@latest for each globally installed package.

Added

  • Oh My Pi Agent: Added Oh My Pi (omp) as a supported agent — a fork of Pi Coding Agent with Python/IPython integration, LSP support, and extended tooling. Installed via Bun (@oh-my-pi/pi-coding-agent).

Changed

  • Agent Addition/Removal Docs: Updated AGENTS.md with complete checklist for adding or removing agents, covering all files that need changes.

[1.4.5] - 2026-03-17

Removed

  • Linux Brew Self-Heal: Removed heal_linux_brew_conflicts() from update-all.sh and its associated tests. The summarize formula conflict has been resolved at the image level and this code path was dead.

[1.4.4] - 2026-03-16

Fixed

  • Pi Image Paste Routing: Pi agent sessions now force the clipboard path through the clipper shim instead of native X11 bindings, avoiding Linux image-paste failures in the container.
  • Copilot Clipboard Bridge Reliability: Added a direct patch for @teddyzhu/clipboard so Copilot can fetch clipboard images from the host bridge even when native clipboard access is unavailable in the container.
  • Headless Clipboard Sync Timing: Tightened the X11 clipboard sync loop and improved argument handling/debug logging in the clipboard bridge scripts to reduce races when agents read pasted images.
  • Linux Brew Update Self-Healing: construct sys update now maintains a Linux self-heal list for unsupported Homebrew formulas, currently replacing summarize with the supported npm package @steipete/summarize before brew upgrades run.

Added

  • Clipboard Debug Command: Added construct sys clipboard-debug to show clipboard bridge logs, patch state, temporary files, and running sync processes for Copilot debugging.
  • Clipboard Debug Documentation: Added docs/CLIPBOARD.md with patching details, debug workflow, and expected log locations for clipboard bridge issues.
  • Updater Regression Guards: Added template coverage for Linux brew self-heal entries and to ensure unsupported fallback packages like summarize are not shipped as default packages.toml installs.

Changed

  • Debug Environment Propagation: CONSTRUCT_DEBUG=1 is now forwarded consistently into run, exec, and daemon flows so clipboard diagnostics work across agent entry paths.
  • Default Package Template: Added lftp, tmux, and btop to the default Homebrew package template.
  • CLI Help: Updated help output to expose the new construct sys clipboard-debug command.

[1.4.3] - 2026-03-11

Fixed

  • Beta Channel Stable Release Detection: Beta-channel update checks now compare both VERSION and VERSION-BETA, so beta users receive newer stable releases such as 1.4.2 even when the beta marker is still on an older prerelease like 1.4.0-beta.11.

Added

  • Update Channel Regression Coverage: Added tests covering beta users receiving newer stable releases, preferring newer prereleases when beta is ahead, and fallback behavior when one remote marker fetch fails.

[1.4.2] - 2026-03-11

Added

  • Bun Package Manager Support in packages.toml: Added a first-class [bun] section so default and user-defined Bun global packages can be managed alongside apt, brew, npm, and pip.
  • Doctor Packages Template Drift Detection: construct sys doctor now warns when packages.toml is missing default template sections, keys, or default list entries such as bun.packages = ["@tobilu/qmd"].
  • Doctor Drift Coverage: Added test coverage for missing package sections, missing template list entries, and user override cases that should not be flagged.

Changed

  • Bun Availability: Bun is now installed unconditionally during setup and exposed on PATH, instead of being treated as an opt-in [tools] entry.
  • Default Package Template: Moved @tobilu/qmd into the default [bun] package list in packages.toml.
  • Local Lint Version Handling: Local make lint and make check no longer fail on patch-level golangci-lint drift; CI remains pinned to the repo version.
  • CLI Help and README: Updated documentation and help text to reflect Bun support, default Bun installation, and packages.toml drift checks in construct sys doctor.

Fixed

  • Clipboard Test Lint Failure: Adjusted PNG test fixture allocation to satisfy prealloc linting and keep make check green.

[1.4.1] - 2026-03-03

Fixed

  • Embedded Gum Confirm Option Styling: Restored proper selected/unselected option spacing and styling in embedded gum confirm prompts so interactive confirmations no longer render collapsed labels like YesNo.

Added

  • Confirm Style Regression Coverage: Added UI test coverage to ensure embedded confirm defaults retain required prompt and option style spacing.

[1.4.0] - 2026-02-25

Changed

  • Linux Userns/Rootless Runtime Detection: Added runtime-level user namespace remap detection and propagation (CONSTRUCT_USERNS_REMAP) across compose startup, setup, daemon, and update flows.
  • Linux Identity Strategy for Rootless Modes: Updated Linux startup behavior to avoid forcing host UID:GID mappings when userns remap/rootless mode is active, while preserving existing non-root-strict behavior where applicable.
  • Entrypoint User Drop Logic (Linux): Entrypoint now keeps namespace-root execution in remapped-userns mode to prevent bind-mount ownership drift during startup bootstrap.
  • Exec User Mapping Guardrails: exec_as_host_user Linux Docker exec mapping is now skipped automatically when userns remap is detected.
  • Host Alias Targeting: construct sys aliases now resolves aliases through the managed ct shim (with executable fallback) instead of bare construct, preventing PATH-driven version drift when Homebrew stable and local beta coexist.
  • Installer Version Normalization: scripts/install.sh now normalizes incoming versions (strips optional v prefix) and preserves prerelease identifiers in installed-version detection.
  • Linux Permission Recovery Flow (Runtime): Replaced the legacy best-effort auto-fix behavior with a strict, interactive repair flow that detects non-writable config paths, prompts for confirmation, and blocks agent execution until ownership is repaired.
  • Linux Permission Recovery Flow (Migration): Migration permission recovery now follows the same explicit yes/no prompt model and surfaces exact manual remediation commands when the user declines or repair fails.
  • Ownership Remediation Guidance: Runtime and migration flows now present runtime-aware manual commands (podman unshare chown for rootless/userns scenarios plus sudo chown) instead of a single static hint.
  • SSH Confirmation UX Fallback: Interactive confirmations now automatically fall back to a plain [Y/n] prompt in SSH sessions to avoid unreadable remote TUI selection rendering.

Fixed

  • Docker Compose Variable Warnings on Non-Linux Hosts: Fixed spurious WARN: "CONSTRUCT_HOST_UID/GID/USERNS_REMAP" variable is not set warnings from Docker Compose when running outside the daemon on macOS. These variables are Linux-only; the compose file now uses ${VAR:-} default-value syntax to silently substitute empty/zero defaults instead of warning.
  • Recurring Config Home Ownership Drift: Fixed repeated ownership drift on ~/.config/construct-cli/home in Linux rootless/userns-remapped Docker/Podman scenarios that caused recurring permission warnings and repair loops.
  • Doctor Runtime-Aware Remediation: construct sys doctor --fix now applies Linux runtime-aware ownership repair paths, including podman unshare first for Podman rootless and sudo fallback (with prompt when needed).
  • Doctor Compose Override Reconciliation: construct sys doctor --fix now regenerates docker-compose.override.yml from current runtime/template settings and validates stale/unsafe user mappings.
  • Doctor Guidance Accuracy: Linux doctor permission diagnostics now report userns-remap context and show runtime-appropriate manual remediation commands.
  • Podman Userns Ownership Re-Drift: Entrypoint startup now skips recursive bind-mount chown -R in remapped-userns mode, preventing fixed ownership from being re-corrupted after startup.
  • Template Path Type Collisions: Migration/init/runtime now self-heal template targets that accidentally exist as directories (for example entrypoint-hash.sh/, agent-patch.sh/) by replacing them with proper files.
  • Home Volume Helper Mount Target Collisions (Linux Docker/Podman): Runtime preparation now also normalizes helper mount targets under ~/.config/construct-cli/home/.config/construct-cli/container (install_user_packages.sh, entrypoint-hash.sh, update-all.sh, agent-patch.sh) so stale directory/file-type collisions are repaired before container setup runs.
  • Fail-Fast Runtime Prep for Mounted Helpers: Runtime now aborts immediately when mounted-helper template preparation fails, instead of continuing into late OCI mount errors during setup.
  • False Rebuild Loop on macOS: Agent startup now auto-clears stale .rebuild_required markers when the container image entrypoint hash is already current, while still blocking when a rebuild is truly required.
  • Release/Tag Consistency: Release workflow now rejects v-prefixed tags and dispatches tap updates with normalized non-prefixed versions.
  • Legacy Linux 1.3.x → 1.4.x Upgrade Safety: Prevented continuation after unresolved ownership drift in config mount paths by failing early with actionable commands, avoiding partial startup/migration behavior.
  • Setup/Spinner Log Peek UX: Pressing Enter to peek logs now shows a clear message when no output has been flushed yet, instead of an empty snapshot.
  • Doctor Daemon Recreate Identity Drift (Linux Rootless/Podman): construct sys doctor --fix daemon recreation now propagates runtime userns identity context (CONSTRUCT_USERNS_REMAP) so recreated daemon runs don’t trigger immediate post-fix ownership drift warnings.
  • Migration Side Effects on Invalid Commands: Startup migration checks now run only for recognized commands/subcommands, preventing typos like construct sys rebuilt from triggering migrations before returning an unknown-command error.

Added

  • Regression Coverage for Rootless Ownership Fixes: Added/updated unit coverage for userns-aware runtime decisions, Podman rootless fix paths, and sudo fallback behavior.
  • Custom Compose Override Opt-In Flag: Added [sandbox].allow_custom_compose_override (default false) for advanced users who intentionally manage docker-compose.override.yml behavior.
  • Regression Tests for Marker/Template Edge Cases: Added tests for stale rebuild-marker auto-clear behavior and directory-collision recovery on mounted template helper paths.
  • Regression Coverage for Home Helper Mount Collisions: Added runtime tests validating repair of file-vs-directory collisions for home/.config/construct-cli/container helper targets.
  • Regression Coverage for Command Gating and Doctor Runtime Env: Added tests for migration gating on unknown subcommands and doctor compose env runtime identity propagation.
  • Dynamic Custom Provider Aliases: construct sys aliases --install now discovers all custom [claude.cc.*] sections from the user's config.toml and automatically installs the corresponding cc-* shell aliases alongside the built-in providers (e.g. [claude.cc.lmstudio] → cc-lmstudio).

[1.3.9] - 2026-02-24

Fixed

  • Podman Non-Interactive Setup Runs: Added -T to non-interactive compose run flows used by rebuild/setup/update/package install paths to avoid Podman TTY/conmon startup failures on Linux.
  • SELinux Home-Directory Rebuilds: When SELinux labels are active and Construct is launched from the home directory, compose override generation now falls back container working_dir to /projects to prevent Linux startup failures while preserving the project mount.
  • Broken Gum Binary Fallback: UI now validates that gum is executable (not only present in PATH) before using it, ensuring clean fallback output and readable setup error logs on Linux.

Added

  • Regression Coverage for SELinux Home Fallback: Added Linux runtime test coverage validating /projects fallback working_dir behavior when home-directory SELinux relabeling is skipped.

Changed

  • Linux Startup Identity Propagation: Linux compose runs now propagate host UID:GID into startup env for setup, interactive runs, daemon startup, doctor compose actions, and package/update operations.
  • Entrypoint Ownership Strategy (Linux): Entrypoint now supports host numeric UID:GID ownership/runtime mapping (when provided) while preserving HOME=/home/construct semantics.

Fixed

  • Recurring Linux Home Ownership Drift: Prevented repeated ownership drift on ~/.config/construct-cli/home caused by container startup user/ownership mismatch across Docker and Podman flows.
  • Config Permissions Doctor Coverage: construct sys doctor now reports ownership mismatch (not only writability) for Linux config directories.
  • Codex Startup Permission Loop: Resolved repeated permission-fix prompts triggered by home mount ownership mismatch before ct codex startup.

Added

  • Comprehensive Linux doctor --fix Remediation: Added Linux --fix flow that repairs config ownership/permissions, rebuilds stale/missing image for startup fixes, recycles stale session container, and recreates daemon container.
  • Regression Coverage for Linux Ownership Fixes: Added unit tests for ownership-state detection, linux fix flow, host identity env injection, daemon recreation/session cleanup fix paths, and template guards for host identity propagation.
  • Release Channels (stable / beta): Added runtime.update_channel to config, beta version marker support (VERSION-BETA), and installer channel selection (CHANNEL=beta) for selective prerelease adoption.
  • Semver Prerelease Comparison: Added shared semantic version comparison logic with prerelease support for update checks and migration gating.

[1.3.7] - 2026-02-22

Added

  • Unified Test Summary (make test): Added a combined end-of-run summary that reports unit pass/fail/skip counts, unit package pass/fail counts, integration totals, and overall status.
  • Codex Regression Tests: Added targeted tests for Codex env injection and fallback behavior, including CODEX_HOME presence for Codex runs, WSL fallback env injection when clipboard patching is enabled, and guard checks ensuring non-Codex agents do not inherit Codex-only env vars.
  • Attach Execution Regression Tests: Added focused tests covering attach-session env injection (HOME, PATH, clipboard vars, Codex vars), shell fallback behavior, and Linux host-UID exec mapping.
  • Podman Compose Selection Tests: Added unit coverage to verify command selection prefers podman-compose when present and falls back to podman compose when it is not.

Changed

  • Test Runner Consolidation: make test and make test-ci now run through a shared scripts/test-all.sh flow for consistent unit+integration reporting.
  • Color Controls for Test Summaries: Added status-aware summary coloring (green/yellow/red) with NO_COLOR to disable and FORCE_COLOR=1 to force output coloring.
  • Codex Config Home Resolution: Force Codex runs (standard + daemon) to use CODEX_HOME=/home/construct/.codex so config is loaded from /home/construct/.codex/config.toml instead of project-relative .codex paths under /projects/....
  • Codex Agent Env Injection Refactor: Centralized Codex-specific run/daemon environment injection into dedicated helper functions to reduce drift across execution paths.
  • Attach Execution Path Parity: Attach-to-running-container flows now use interactive exec with the same env protections as normal/daemon runs (construct PATH, HOME=/home/construct, clipboard vars, and agent-specific env injection).
  • Linux Non-Daemon Host UID Mapping: Non-daemon Linux Docker agent runs now apply host UID:GID mapping when exec_as_host_user=true and force HOME=/home/construct.
  • Podman Compose Invocation Strategy: Compose command resolution now uses podman-compose when available and otherwise falls back to podman compose.
  • Strict Network Naming Consistency: Strict mode now uses a consistent construct-net network name across network precreate checks and compose override generation.
  • Ownership Repair Mapping: Runtime and migration ownership repair commands now use numeric uid:gid mapping for broader Linux compatibility.

Fixed

  • Entrypoint HOME/Permissions Regression (Linux Docker): Resolved a regression where entrypoint privilege drop could run as a raw host uid:gid without a passwd entry, causing HOME=/ and repeated permission errors writing ~/.ssh, ~/.bashrc, and setup files.
  • Daemon Session Startup Reliability: Restored reliable startup behavior for daemon-backed runs (construct <agent>) when host UID does not exist inside the container.
  • Linux Config Ownership Auto-Recovery: Hardened migration/runtime permission recovery to attempt non-interactive sudo ownership repair first, with clearer remediation when elevation is unavailable.
  • Host UID Exec Fallback Messaging: Ensured fallback warnings are visible when host UID mapping cannot be used inside the container.
  • Docker Override Host UID Injection: Removed runtime host UID/GID env injection from generated Docker overrides to avoid reintroducing raw-UID startup regressions.
  • Codex Attach Permission Path Drift (Linux): Fixed attach sessions that could miss home/config env injection and fall back to project-relative .codex resolution.
  • Podman Runtime/Compose Mismatch: Fixed runtime detection success followed by compose invocation failure on hosts without podman-compose.
  • Linux Exec Documentation Drift: Updated docs/comments to match current behavior when host UID is missing in container /etc/passwd (keep host mapping and force HOME=/home/construct).

[1.3.2] - 2026-02-20

Added

  • Compose Network Health Check: construct sys doctor now detects stale Docker Compose networks that require recreation (for example after Docker daemon/network default changes such as IPv4/IPv6 toggles).

Fixed

  • One-Step Compose Network Recovery: construct sys doctor --fix now automatically applies targeted compose network recovery by bringing down the compose stack with orphan cleanup and removing the stale compose network(s) when needed.
  • Doctor Fix Regression Safety: Added unit coverage for compose-network fix flow (success, no-op, and failure cases) to prevent regressions.

[1.3.1] - 2026-02-19

Added

  • Issue Template Diagnostics: Added GitHub bug report template fields requiring construct sys doctor output and setup/update logs.
  • Doctor Environment Visibility: construct sys doctor now reports host UID/GID, container user mapping, daemon mode details, daemon mount paths, and latest update log path.
  • Setup/Update Diagnostics: Added richer setup and update diagnostics (UID/GID, PATH, brew/npm/topgrade presence, Homebrew writability checks) plus post-run agent command verification summaries.
  • exec_as_host_user Mode: Added [sandbox].exec_as_host_user (default true) to run Linux Docker exec sessions as host UID:GID for better host file ownership.

Changed

  • Docker Linux User Mapping Strategy: Docker overrides no longer force user: by default on Linux; root-bootstrap remains default and user mapping is now podman-only unless strict mode is explicitly enabled.
  • Strict Non-Root Mode Documentation: Added explicit warnings and limitations for [sandbox].non_root_strict in config template, doctor output, and README.
  • NPM Global Prefix Flow: Setup/update now configure npm global prefix earlier to reduce EACCES failures.

Fixed

  • Agent Installation Continuation: Hardened package install script generation so Homebrew failures do not abort later NPM agent installs.
  • Manual user: Override Recovery (Docker/Linux): Detects unsafe manual user: mappings in docker-compose.override.yml, warns users, and regenerates override safely (except when non_root_strict=true).
  • Entrypoint Shell Setup Noise: Ensured .bashrc is created before alias-source checks to avoid missing-file warnings.
  • Daemon Exec UX: Added targeted hinting when daemon exec exits with command-not-found.
  • Exec User Fallback Safety: When exec_as_host_user=true, Construct now verifies host UID exists in container /etc/passwd; if not, it warns and falls back to the container default user.
  • Stable ns-* Alias Paths: sys aliases --install now preserves stable shim paths (for example /opt/homebrew/bin/...) instead of resolving to versioned Cellar/Caskroom paths.

[1.2.10] - 2026-02-06

Changed

  • Design Docs Mount Model: Updated ARCHITECTURE-DESIGN.md to document the active dual mount behavior: /projects/<folder> for ephemeral runs and /workspaces/<hash>/... for daemon multi-root runs.

Fixed

  • Clipboard Host Command Timeouts (macOS): Added a timeout for osascript image reads in the host clipboard bridge to prevent hangs when reading image clipboard data.
  • Clipboard HTTP Server Timeouts: Added read/write/idle timeouts to the clipboard HTTP server to avoid stuck connections.
  • Codex WSL Fallback Request Timeout: Added curl connection and overall time limits in powershell.exe to avoid indefinite waits when fetching clipboard images.
  • Codex Daemon Workspace Path Mapping: Added /mnt/c/workspaces -> /workspaces aliasing and expanded shim path handling so WSL-style fallback paths resolve correctly in daemon sessions.

[1.2.8] - 2026-02-05

Added

  • Config Defaults Check: construct sys doctor now reports missing default config keys and can append them with --fix (with backup).
  • Construct PATH Export: Entry point now writes a construct-managed PATH profile to stabilize login shells.
  • Non-Daemon PATH Injection: Inject full Construct PATH for setup, container runs, and daemon exec sessions via CONSTRUCT_PATH.
  • PATH Sync Test: Added a unit test to verify PATH parity across Go and template files.
  • Clipboard Patch Flag: Added agents.clipboard_image_patch to enable/disable clipboard image patching and codex WSL clipboard workaround.
  • Brew Package: Added nano to default Homebrew packages.

Changed

  • Safe Defaults Overlay: Defaults are now applied in code when config values are missing.
  • No Config Auto-Merge: Removed automatic config.toml merges and config template hash tracking.

Fixed

  • Agent PATH Parity: Hardcoded PATH across env, entrypoint, compose, and Dockerfile to keep agent binaries available everywhere.
  • Setup + Daemon PATH Injection: Ensure full Construct PATH is injected for setup runs and daemon exec sessions so tools are available everywhere.

[1.2.3] - 2026-02-03

Added

  • Provider Key Passthrough: Always forward common provider API keys into containers, preferring CNSTR_ values and falling back to unprefixed names when empty or missing. Keys: ANTHROPIC_API_KEY, OPENAI_API_KEY, GEMINI_API_KEY, OPENROUTER_API_KEY, ZAI_API_KEY, OPENCODE_API_KEY, HF_TOKEN, KIMI_API_KEY, MINIMAX_API_KEY, MINIMAX_CN_API_KEY.

Fixed

  • Daemon SSH Agent Bridge: Ensure daemon execs initialize the SSH agent proxy and expose SSH_AUTH_SOCK on macOS so agents can access forwarded keys.

[1.2.1] - 2026-01-28

Fixed

  • Daemon Yolo Flag: Avoid injecting --dangerously-skip-permissions when execing into a root-running daemon to prevent permission errors.
  • Daemon User Enforcement (macOS): Run all agent execs inside the daemon as the construct user to avoid root exec on macOS.

Changed

  • Run User (macOS): Force non-daemon agent runs to use the construct user to avoid root exec on macOS.

[1.2.0] - 2026-01-27

Added

  • Daemon Control Commands: Added construct sys daemon subcommands to start, stop, attach, and check status of the background daemon.
  • Multi-Root Daemon Mounts: Support for multiple host root mounts for the daemon with validation, overlap warnings, and deterministic mount hashing.

Changed

  • Workspace Mount Path: Removed the legacy /workspace fallback; project mounts now always use /projects/<folder> via CONSTRUCT_PROJECT_PATH.
  • Compose Env Injection: CONSTRUCT_PROJECT_PATH is now injected automatically for all compose-based commands to keep mount paths consistent.

Fixed

  • Daemon Workdir Mapping: Improved daemon working directory mapping to resolve host paths against validated daemon mounts.

[1.1.3] - 2026-01-26

Added

  • Shared Entrypoint Hash Helper: Introduced a shared script for computing and writing entrypoint hashes, used by both setup and update flows.
  • Agent Patch Script: Centralized clipboard and agent patching into a reusable script.

Changed

  • Update Flow Patching: sys update now runs agent patching and writes the entrypoint hash immediately to avoid redundant setup on next run.
  • Mounted Update Scripts: Update and patch scripts are mounted from the host into the container for faster iteration without rebuilds.
  • Update Fallback Warning: Warns when falling back to /usr/local/bin/update-all.sh and suggests running construct sys refresh.

Fixed

  • Post-Update Double Setup: Avoids re-running full setup after updates when only patching is needed.
  • Rebuild Template Duplication: construct sys rebuild no longer copies container templates twice during automatic migration + refresh.
  • Daemon Mount Working Dir: Agent exec in the daemon now maps the host working directory to the correct mounted path.

[1.1.0] - 2026-01-25

Improved

  • Multiple performance optimizations where implemented to make the CLI faster and more efficient. Now it's fast. Really fast.

Added

  • Daemon Auto-Start Service: Added sys daemon install, sys daemon uninstall, and sys daemon status for managing a background daemon service (systemd) that can auto-start on login/boot.
  • Daemon Auto-Start Config: New [daemon] auto_start setting to start the daemon on first agent run for faster subsequent startups.

Changed

  • Faster Runtime Detection: Runtime detection now checks container, podman, and docker in parallel to reduce startup latency on multi-runtime systems.
  • Daemon Exec Fast Path: When a daemon container is running, agents run via exec instead of compose run for much faster startup.
  • Compose Override Caching: Docker compose override generation is cached to avoid unnecessary regeneration on repeated runs.
  • Parallel Runtime Detection: Checks container, podman, and docker concurrently to cut detection latency by 0.5-1s.
  • Daemon Exec Path: Agent runs reuse the warm daemon container for 2.5-7s faster startup.
  • Entrypoint Caching: Skips expensive clipboard and agent patching when entrypoint hash is unchanged (200-800ms saved).
  • Preemptive Services: Clipboard server and SSH bridge already start asynchronously; no added latency from sequential startup.

Fixed

  • Daemon Staleness Guard: Detect stale daemon containers (old image) and fall back to normal startup with clear guidance to restart the daemon.
  • Daemon Shell Exec: construct sys shell now execs a default shell when attaching to a running daemon, preventing empty exec calls.
  • Post-Update Entrypoint Patching: Clearing the entrypoint hash after updates ensures new agents get patched correctly.

[1.0.1] - 2026-01-21

Fixed

  • OrbStack/Podman Sudo Compatibility: Fixed package install/update flows (sys packages --install and sys update) failing with "PAM account management error" in environments where sudo is unavailable or misconfigured (OrbStack, rootless Podman, minimal containers). Thanks @KingMob for the bug report.
    • Install scripts now detect if running as root (no sudo needed) or test sudo availability before use
    • Gracefully skips privileged apt operations when sudo unavailable instead of failing
    • Applies to both install_user_packages.sh (generated) and update-all.sh (template)

[1.0.0] - 2026-01-20

Added

  • Production Ready: Marked Construct CLI as production ready.

[0.15.11] - 2026-01-18

Added

  • SELinux Label Control: Added sandbox.selinux_labels config to enable, disable, or auto-detect SELinux mount labels.
  • Doctor Ownership Check: Added a Linux/WSL config permissions check with a chown fix suggestion for ~/.config/construct-cli.
  • Automatic Config Permission Fix: On Linux/WSL, automatically detect and fix config directory ownership issues before runtime preparation, with clear messaging and user confirmation before running sudo.
  • Simple Progress Mode: Added dot-based progress output for non-TTY environments and when CONSTRUCT_SIMPLE_PROGRESS=1 is set.
  • Podman Rootless Support: On Linux, container now runs as user (not root) for proper Podman rootless compatibility. macOS continues to use root with gosu drop.
  • Truecolor Support: Forward host COLORTERM to container, defaulting to truecolor when unset. Fixes washed-out colors over SSH.

Fixed

  • SELinux Home Relabeling: Skip :z labels when running from the home directory to avoid relabel errors.
  • Config Write Guidance: Emit clearer permission warnings when config-generated files cannot be written.

[0.15.2] - 2026-01-15

Added

  • Goose CLI: Added goose agent, with first-run configure guidance.
  • Droid CLI: Added droid agent.
  • Kilo Code CLI: Added kilocode agent.
  • Yolo Mode Config: Added [agents] config to enable yolo flags per-agent or globally in config.toml.
  • Agent Browser: Added agent-browser to default npm packages and configured its post-install dependency setup. Headless browser automation CLI for AI agents. Fast Rust CLI with Node.js fallback. No MCP required.
  • LiteLLM: Added litellm to default pip packages; open-source LLM gateway/SDK with a unified OpenAI-compatible API across 100+ providers, with cost/error handling and failover.
  • Post-Install Hooks: Added [post_install].commands to packages.toml, executed after all package managers finish.

[0.14.3] - 2026-01-13

Added

  • Podman Compose: Added podman-compose to default brew packages in packages.toml.

[0.14.2] - 2026-01-11

Changed

  • Non-Sandboxed Aliases: ns- entries are now shell functions in the RC file, forwarding flags and args without installing extra files.
  • Agent Rules Bulk Replace: sys agents-md now supports replacing all agent rules at once with a single pasted prompt, including Copilot frontmatter.

[0.13.2] - 2026-01-08

Fixed

  • Stale Entrypoint Detection: Detect and prompt rebuild when the container image entrypoint is out of date to avoid repeated setup spinners.

[0.13.1] - 2026-01-07

Added

  • Pi Coding Agent: Added support for Pi Coding Agent (@mariozechner/pi-coding-agent).
    • Config mounted at /home/construct/.pi
    • Added to default npm packages in packages.toml
    • Auto-creates ~/.pi/agent/auth.json (empty object) on first run

[0.12.0] - 2026-01-07

Changed

  • Container User Authentication: Set fixed password "construct" for the construct user to enable sudo access when running commands inside sys shell.
    • All automated operations (init, build, migrate, update, rebuild) remain completely passwordless via NOPASSWD sudoers configuration

[0.11.6] - 2026-01-06

Added

  • Static Site Generators: Added Hugo and Zola to default brew packages in packages.toml.
  • Ruby Gems Support: Added support for installing Ruby gems via a new [gems] section in packages.toml.
    • Includes jekyll as default gem
    • Integrated with package installation scripts and Topgrade updates
  • Host System Info: Added new "Host System" check to sys doctor to display OS, architecture, and version details.
    • Shows macOS version and kernel on Apple/Intel Macs
    • Shows Linux distribution name and kernel version
    • Detects and displays WSL environment on Windows

Fixed

  • Doctor SSH Keys Display: Fixed SSH key listing in sys doctor to exclude non-key files (known_hosts, config, agent.sock, etc.).
    • Renamed check from "Local SSH Keys" to "Construct SSH Keys" for clarity
    • Keys shown are those stored in Construct's SSH directory (whether imported or generated)

[0.11.5] - 2026-01-05

Fixed

  • Agent PATH Visibility: Fixed issue where agents (particularly codex) couldn't see binaries in PATH when running commands via their Bash tools.
    • Root cause: /etc/profile was resetting PATH when bash spawned, wiping out Homebrew paths
    • Patched /etc/profile in entrypoint.sh (idempotent, no image rebuild needed)
    • Centralized PATH definition in internal/env/env.go (DRY principle)
    • Synchronized PATH configuration across docker-compose.yml, entrypoint.sh, and env.go
    • Ensures all agent subprocesses inherit full PATH including Linuxbrew, Cargo, npm-global, etc.
  • CT Symlink Stability: ct now targets the stable Homebrew path on macOS/Linux, and sys doctor self-heals broken Cellar-based symlinks.
  • Agent Detection in Doctor: Agent install check now verifies binaries inside the container so Homebrew/NPM-based installs are detected correctly.
  • Rebuild Help Clarity: sys rebuild help text now explicitly mentions it runs migrate before rebuilding.

[0.11.3] - 2026-01-03

Added

  • md-over-here: Added md-over-here to default brew packages in packages.toml template.
  • Brew Installation Detection: self-update and update notifications now detect if the CLI was installed via Homebrew and provide appropriate instructions (brew upgrade estebanforge/tap/construct-cli) instead of attempting a manual binary overwrite.

Fixed

  • Package Installation Reliability: Improved package install flow (sys packages --install) to use run --rm instead of exec, allowing it to work correctly even if The Construct is not already running.
  • Initialization Consistency: Updated sys init and sys rebuild to always perform a full migration (syncing config and templates) before building the image.
  • Migration Messaging: Clarified migration messages to indicate when an image is "marked for rebuild" versus being actively rebuilt.
  • Container Rebuild Reliability: improved sys rebuild to force fresh container images.
    • Now stops and removes running containers and images before rebuilding (not just marking for rebuild)
    • Added support for macOS 26+ native container runtime management.
  • Container Image Optimization: Updated base image to a more stable version.
    • Leaner base image means faster rebuilds and reduced storage footprint.
  • Template Synchronization: Improved migration flow (sys config --migrate) to ensure binary rebuilds are correctly triggered when embedded templates change.
    • Automatic removal of old Docker image (forces rebuild with new Dockerfile)
    • New hash-based template change detection (more reliable than version checks)

[0.11.2] - 2026-01-03

Fixed

  • Version-Independent Aliases: Fixed Homebrew alias installation to use version-independent paths.
    • Aliases now use construct command instead of hardcoded Cellar paths (e.g., /opt/homebrew/Cellar/construct-cli/0.11.0/bin/construct)
    • Aliases remain functional after Homebrew updates without reinstallation
    • Also improves portability for curl-based installations and local builds
  • Chromium Multi-Arch Support: Fixed Puppeteer-based tools (url-to-markdown, browser automation) on arm64 hosts.
    • Installed system Chromium from Debian repos (automatically matches container architecture)
    • Configured Puppeteer to use system Chromium instead of downloading x86-64 version
    • Prevents "Dynamic loader not found: /lib64/ld-linux-x86-64.so.2" errors on Apple Silicon/arm64
    • Includes all required Chromium dependencies (fonts, GTK, NSS, etc.)

[0.11.1] - 2026-01-02

Added

  • Homebrew Installation: Added support for installing via Homebrew (Linux & macOS) using brew install EstebanForge/tap/construct-cli.
  • Topgrade Integration: Automated package updates inside Construct via Topgrade
    • Ensures all system packages, language tools, and development utilities stay current
    • Seamless integration with Construct's containerized environment
    • Configurable via packages.toml for custom update policies
  • Worktrunk.dev Support: Default installation and usage of Worktrunk for simultaneous agent collaboration
    • Enables multiple AI agents to work on the same codebase without conflicts
    • Provides intelligent workspace isolation and synchronization
    • Configured by default for optimal multi-agent workflows

[0.10.1] - 2025-12-31

Added

  • Cargo Package Support: users can now install Rust-based tools and utilities via a new [cargo] section in packages.toml.
  • Centralized Debugging: unified all debug logging under the CONSTRUCT_DEBUG environment variable.
    • When enabled (CONSTRUCT_DEBUG=1), logs are written to ~/.config/construct-cli/logs/ on the host.
    • Container-side logs (like powershell.exe and clipboard-x11-sync) are redirected to /tmp/ for guaranteed visibility and write access.
    • Replaced legacy CONSTRUCT_CLIPBOARD_LOG with the new unified system.
  • Non-Sandboxed Agent Aliases: sys aliases --install now creates ns-* prefixed aliases for agents found in PATH.
    • Example: ns-claude, ns-gemini, etc. run agents directly without Construct sandbox
    • Useful for running agents with full host access when needed
  • Alias Re-installation: sys aliases --update now supports updating existing installations.
    • Detects existing aliases and offers to re-install with gum confirmation prompt
    • Automatically removes old alias block before installing fresh
    • Adds missing ns-* aliases when updating existing installations
  • Shell Config Backups: automatic timestamped backups before modifying shell config files.
    • Creates .backup-YYYYMMDD-HHMMSS files before any changes
    • Applies to both .zshrc, .bashrc, and .bash_profile
    • Protects users from critical shell configuration errors

Optimized

  • Sandbox Isolation: sanitized the PATH environment variable across all templates to prevent host-side directory leakage into the sandbox.
  • Streamlined Installation:
    • Eliminated redundant package installations by removing duplicates between APT and Homebrew phases.
    • Added DEBIAN_FRONTEND=noninteractive to silence UI dialogs during container setup.
  • Improved Migration Experience: refined version detection messaging to accurately distinguish between binary upgrades, downgrades, and template-only syncs.

Fixed

  • Codex Image Paste: restored full image support for OpenAI Codex CLI agent after its internal mechanism changed from direct binary data to path-based references.
    • Fixed Ctrl+V shortcut by shimming the WSL clipboard fallback with a smart powershell.exe emulator that returns workspace-compatible paths.
    • Implemented /mnt/c/projects and /mnt/c/tmp symlinks within the container to ensure Codex path resolution works seamlessly across all host platforms.
    • Improved "New Flow" paste detection by allowing Codex to receive raw image paths instead of multimodal @path references.
  • Self-Update Reliability: fixed a confusing state where self-update would report an upgrade from 0.3.0 due to intentional version file deletion.
  • Clipboard Image Paste: Centralized file-based paste agent list (gemini, qwen, codex) into a single constant to prevent drift.
  • Container Rebuild Reliability: improved sys rebuild to force fresh container images.
    • Now stops and removes running containers and images before rebuilding (not just marking for rebuild)
    • Added --no-cache flag to build command to bypass Docker layer cache
    • Added support for Apple container runtime (macOS 26+) alongside Docker and Podman
  • SSH Key Prioritization: Enhanced SSH configuration management to ensure correct key selection order for all hosts.
    • Auto-generates ~/.ssh/config with SSH agent support and key prioritization (default and personal keys tried first).
    • Applies to all SSH connections (GitHub, GitLab, private servers, etc.), not just specific hosts.
    • Adds RSA key algorithm support (PubkeyAcceptedAlgorithms +ssh-rsa) for legacy servers.
    • Falls back to physical SSH keys if present after trying agent keys.
    • Automatic updates on CLI upgrade unless user opts out with construct-managed: false flag.
    • Creates backup (~/.ssh/config.backup) before each update.

[0.10.0] - 2025-12-30

Added

  • User-Defined Package Management: Customize your sandbox environment with packages.toml configuration.
    • Install additional APT, Homebrew, NPM, and PIP packages beyond the defaults.
    • Easy activation of specialized version managers: NVM, PHPBrew, Nix, Asdf, Mise, VMR, Volta, and Bun.
    • New construct sys packages command to quickly edit package configuration.
    • New package install command construct sys packages --install to apply package changes to running containers without restart.
    • Package configuration persists across updates and environments.
  • Dynamic Project Mount Paths: Agents now mount the current host directory to /projects/<folder_name> instead of static /workspace.
    • Improves agent contextual awareness and long-term memory.
    • Dynamically calculates mount path based on current directory name.
    • Automatically updates all internal templates (Dockerfile, docker-compose) and helper scripts.
    • Preserves compatibility with non-standard folder names (spaces, special characters).

Optimized

  • Faster Docker Builds: Streamlined base image for significantly faster build times.
    • Reduced Dockerfile to only essential build-time dependencies.
    • Moved most packages to runtime installation during first container start.
    • Critical packages verified at startup to ensure reliability.
    • Leaner base image means faster rebuilds and reduced storage footprint.

Improved

  • Enhanced Code Quality: Internal refactoring and expanded test coverage.
    • Comprehensive clipboard functionality test suite.
    • Updated linter configuration for stricter code quality enforcement.
    • Improved error handling and package naming conventions.
  • Package Management Refinements:
    • PHP extensions (PCOV) now installed via Homebrew tap instead of hardcoded scripts for better maintainability.
    • Node.js version unlocked from node@24 to node for automatic latest stable version.
    • Native Node.js module compilation support with automatic compiler symlinks (g++-11 → g++-14).
    • Removed conflicting bash-completion package to prevent installation failures.

[0.9.1] - 2025-12-27

Changed

  • Clipboard Image Pasting: Fixed image pasting across agents with image-first handling, normalization/resize, and @path only for Gemini and Qwen.

[0.9.0] - 2025-12-26

Optimized

  • Reliable Agent Installation: Overhauled entrypoint.sh to prevent partial installation failures.
    • Split large brew install commands into categorized blocks (Core, Dev, Languages, Linters, Web/Build).
    • Unified npm package installation into a single, efficient command.
    • Implemented hash-based change detection for entrypoint.sh to automatically trigger re-installation when scripts are updated.
  • Smart Runtime Configuration:
    • Optimized Linux runtime detection to avoid unnecessary user ID mapping for UID 1000 users, enabling proper permission fixups.
    • Improved migration flow (sys config --migrate) to ensure binary rebuilds are correctly triggered when embedded templates change.

Fixed

  • Permission Issues: Fixed permission errors during initial setup by allowing the container to start as root for volume ownership fixes before dropping privileges.
  • Missing Tools: Resolved issue where tools like golangci-lint could be missing due to silent installation failures.
  • Build Caching: Fixed an issue where Docker build cache would persist stale entrypoint.sh versions, preventing updates from being applied.

[0.8.0] - 2025-12-25

Added

  • Git Identity Inheritance: Automatically propagates host git identity (user.name and user.email) to the container environment.
    • Solves commit attribution issues inside the container.
    • Enabled by default, configurable via propagate_git_identity in config.toml.
    • Safely injects values as GIT_AUTHOR_NAME, GIT_AUTHOR_EMAIL, etc., without mounting potentially incompatible host git configs.
  • Improved Shell Prompt: Container hostname is now set to sandbox (was random ID) for a cleaner prompt experience: construct@sandbox:/workspace$.
  • Headless Login Bridge: New construct sys login-bridge command to enable local browser login callbacks for headless-unfriendly agents (Codex, OpenCode with OpenAI GPT or Google Gemini).
    • Runs until interrupted and forwards localhost OAuth callbacks into the container.

[0.7.0] - 2025-12-24

Added

  • Global Agent Rules Management: New construct sys agents-md command to manage rules for all supported agents in one place.
    • Interactive selection UI powered by gum.
    • Supports: Gemini, Qwen, OpenCode, Claude, Codex, Copilot, and Cline.
    • Auto-Initialization: Automatically creates missing rules files and parent directories on demand.
    • Open All: "Open all Agent Rules" option to quickly edit all supported agent rules at once.
    • Context-Aware Expansion: Automatically resolves ~ to the Construct persistent home directory (~/.config/construct-cli/home/) so rules are correctly applied within the container environment.
    • Fallback UI: Seamlessly falls back to a numeric menu if gum is not available.

Changed

  • Generic Workspace Path: Renamed the internal container mount point and working directory from /app to /workspace.
    • This reflects the project's evolution into a general-purpose sandbox for any CLI agent, not just those used for "app" development.
    • Automatically updates all embedded templates (Dockerfile, docker-compose) and runtime override generation.
    • Updated design and user documentation to reflect the new path.

Fixed

  • Improved UI grammar and messaging consistency across system commands.
  • Updated .gitignore to prevent tracking of local debug logs while preserving them for development.

[0.6.0] - 2025-12-23

Added

  • Secure SSH Agent Forwarding: Automatic detection and secure mounting of the local SSH agent into the container.
    • Supports Linux and macOS (OrbStack and Docker Desktop).
    • Implements a TCP-to-Unix bridge for robust macOS/OrbStack connectivity, bypassing common permission and socket quirks.
    • Fully configurable via forward_ssh_agent in config.toml (enabled by default).
  • SSH Key Import System: New construct sys ssh-import command to securely bring host keys into Construct.
    • Interactive multi-select UI powered by gum.
    • Automatic permission fixing (0600) and matching .pub/known_hosts support.
    • Smart logic to skip selection if only one key is found.
  • Config Restoration: New construct sys config --restore command to immediately recover from configuration backups.
  • Shell Productivity Enhancements:
    • Automatic management of .bash_aliases inside the container.
    • Standard aliases included: ll, la, l, and color-coded ls/grep.
    • Zsh-like navigation shortcuts: .., ..., .....
  • Improved Diagnostics: construct sys doctor now reports SSH Agent connectivity and lists imported local keys.

Changed

  • Non-Destructive Migration: Redesigned migration flow (sys config --migrate) logic to be strictly additive.
    • Preserves all user comments and formatting.
    • Automatically identifies and preserves custom Claude Code aliases, moving them to a dedicated "User-defined" section.
    • Prevents TOML section duplication.
  • Unified macOS Magic Path: Simplified container orchestration to use industry-standard magic paths for macOS container bridges.
  • Entrypoint Reliability: Container now starts as root to perform critical permission fixes (SSH sockets, home directory ownership) before dropping to the non-privileged construct user via gosu.

Fixed

  • Fixed "Permission denied" errors when accessing mounted SSH sockets on macOS.
  • Fixed "Communication failed" errors by implementing a Go-native TCP bridge for macOS.
  • Full compliance with strict golangci-lint rules, improving overall code robustness and error reporting.
  • Simplified config.toml template to reduce clutter and minimize merge conflicts.

[0.5.0] - 2025-12-22

Added

  • Self-Update Command: construct sys self-update now downloads and installs the latest version directly from GitHub releases
    • Automatic platform detection (darwin/linux, amd64/arm64)
    • Prompts for confirmation when already on latest version
    • Backup and restore on failure
  • Smart Config Migration: Config merging now only runs when template structure actually changes
    • Hash-based detection of config template changes
    • Skips unnecessary backup/merge cycles on patch version updates
    • Container templates still update on every version bump (for bug fixes)

Changed

  • Simplified Update Check: Version checking now uses lightweight VERSION file instead of GitHub API
    • Faster checks, no API rate limits
    • Download URLs constructed directly from version string
  • Install Script Improvements:
    • Checks for existing installation before downloading
    • Prompts user if same version already installed
    • Uses VERSION file for remote version lookup
    • Reads local .version file first, falls back to querying binary
    • New FORCE=1 env var to skip version check

Fixed

  • Version command no longer triggers config initialization
  • Update check now uses proper semver comparison (was treating any version difference as "update available")

[0.4.1] - 2025-12-22

Added

  • make lint now runs golangci-lint for parity with CI checks.

Fixed

  • Migration merge now skips incompatible types and validates TOML, preventing corrupted config files after upgrades.
  • Improved error handling and warnings for clipboard server, daemon UI rendering, log cleanup, and shell alias flows.

[0.4.0] - 2025-12-21

Added

  • Automatic Migration System: Seamless upgrades with zero user intervention
    • Version tracking via .version file in config directory
    • Automatic detection of version changes on startup
    • Smart detection of 0.3.0 → 0.4.0 upgrades (handles missing version file)
    • Improved Config Merging: New template-first merge logic that preserves comments and layout while syncing supported user values.
    • Automatic replacement of container templates with new versions
    • Automatic removal of old Docker image (forces rebuild with new Dockerfile)
    • Persistent volumes preserved (agents, packages, configurations)
    • Backup of old config created during migration (config.toml.backup)
    • Clear migration progress output with success/error reporting
    • New migration command construct sys config --migrate for manual config/template refresh (useful for debugging)
  • Expanded Container Toolchain: Added comprehensive language support to the sandbox:
    • Languages: Rust, Go, Java (OpenJDK), Kotlin, Swift, Zig, Ruby, PHP, Dart, Perl, Erlang, COBOL.
    • Build Tools: Ninja, Gradle, UV, Composer.
    • Utilities: jq, fastmod, tailwindcss CLI.
  • Cross-Boundary Clipboard Bridge: Unified host-container clipboard for seamless text and image pasting
    • Secure Host-Wrapper Bridge: A secure Go HTTP server on the host provides authenticated clipboard access to the container via ephemeral tokens.
    • Universal Image Support: Robust support for pasting images directly into agents across macOS, Linux, and Windows (WSL).
    • Multi-Agent Interception: Automatic shimming of xclip, xsel, and wl-paste inside the container to redirect calls to the bridge.
    • Dependency Patching: entrypoint.sh automatically finds and shims nested clipboard binaries in node_modules (fixes Gemini/Qwen clipboardy issues).
    • Tool Emulation: Fake osascript shim allows agents to use macOS-native "save image" logic while running on Linux.
    • Smart Path Fallback: Automatically saves host images to .gemini-clipboard/ and returns multimodal @path references for agents expecting text.
    • Runtime Code Patching: Automatically bypasses agent-level process.platform checks that would otherwise disable image support on Linux.
    • Zero Config: Transparently handles all platform-specific clipboard complexities with no user setup required.
  • Development Installation Scripts: New tools for local testing and debugging
    • install-local.sh: Full-featured install with automatic backups and verification (defaults to ~/.local/bin)
    • dev-install.sh: Lightning-fast dev install for rapid iteration (no confirmations, no backups)
    • uninstall-local.sh: Safe uninstall with backup restoration options
    • New Makefile targets: install-local, install-dev, uninstall-local
  • Comprehensive Development Documentation
    • New DEVELOPMENT.md with complete development workflow guide
    • Detailed installation methods, testing procedures, and troubleshooting
    • VS Code tasks configuration examples

Changed

  • Help Text Alignment: All CLI help descriptions now properly aligned for better readability
    • Aligned # comments across all help sections (sys, network, daemon, cc)
    • Consistent formatting in main help, network help, daemon help, and provider help
  • Installation Defaults: Local installation scripts now default to ~/.local/bin (no sudo required)
    • Users can override with INSTALL_DIR environment variable
    • Improved user experience for development workflows
  • Clipboard Integration Architecture: Upgraded from manual directory sync to a secure, real-time HTTP bridge.
    • Transparent redirection of all terminal clipboard tools to the host system.
    • Integrated support for multimodal agents (Claude, Gemini, Qwen).

Fixed

  • Runtime Package Conflicts: Resolved naming collision in internal/agent/runner.go
    • Standard library runtime package now imported as runtimepkg
    • All runtime function calls updated to use proper package reference
  • Version Location: Updated version references in documentation to reflect actual location
    • Version now correctly documented as internal/constants/constants.go (not main.go)

Documentation

  • Updated README.md with cross-boundary clipboard bridge instructions
  • Added DEVELOPMENT.md with development workflow and testing guide
  • Updated AGENTS.md with correct file paths and new clipboard features
  • Updated ARCHITECTURE-DESIGN.md with detailed clipboard bridge architecture

[0.3.0] - 2025-12-18

Added

  • Core CLI Framework: Single-binary CLI for running AI agents in isolated containers
    • Runtime auto-detection: macOS container → podman → docker
    • Embedded templates (Dockerfile, docker-compose, entrypoint, configs)
    • Self-building on first run with construct sys init
  • Network Isolation: Three modes for security
    • permissive: Full network access (default)
    • strict: Custom network with domain/IP allowlist/blocklist
    • offline: No network access at all
    • Live UFW rule application while agents are running
  • Agent Support: Pre-configured support for multiple AI agents
    • Claude Code, Gemini CLI, Qwen Code, GitHub Copilot CLI
    • OpenCode, Cline, OpenAI Codex
    • Agent configuration directories mounted from host
  • System Commands (construct sys):
    • init: Initialize environment and install agents
    • update: Update agents to latest versions
    • reset: Delete volumes and reinstall
    • shell: Interactive shell with all agents
    • aliases --install: Install agent aliases to host shell
    • version: Show version
    • config: Open config in editor
    • agents: List supported agents
    • doctor: System health checks
    • self-update: Update construct binary
    • check-update: Check for available updates
  • Network Commands (construct network):
    • allow <domain|ip>: Add to allowlist
    • block <domain|ip>: Add to blocklist
    • remove <domain|ip>: Remove rule
    • list: Show all rules
    • status: Show active UFW status
    • clear: Clear all rules
  • Daemon Mode (construct sys daemon):
    • start: Start background container
    • stop: Stop background container
    • attach: Attach to running daemon
    • status: Show daemon status
  • Claude Provider Aliases (construct cc):
    • Support for alternative Claude-compatible API endpoints
    • Providers: Z.AI, MiniMax, Kimi, Qwen, Mimo
    • Environment variable expansion and automatic reset
    • Configuration in config.toml under [claude.cc.*]
  • Persistent Volumes: Agent installs persist across runs
    • construct-agents: Agent binaries and configs
    • construct-packages: Homebrew packages
    • Ephemeral containers (--rm) for clean host system
  • Auto-Update System:
    • Passive background update checks (configurable interval)
    • Desktop notifications for available updates
    • Self-update command for binary upgrades
    • Version checking against GitHub releases
  • Platform Support:
    • macOS (Intel and Apple Silicon)
    • Linux (amd64 and arm64)
    • SELinux support with automatic :z labels
    • Linux UID/GID mapping in generated override files
    • WSL2 compatibility

Configuration

  • Main config at ~/.config/construct-cli/config.toml
  • Runtime engine selection (auto, container, podman, docker)
  • Network mode configuration with domain/IP lists
  • Provider-specific environment variables
  • Auto-update check settings

Infrastructure

  • Makefile with comprehensive build targets
  • Cross-compilation support for all platforms
  • Unit and integration test suites
  • CI-ready lint and test commands
  • GitHub Actions integration ready
  • Install/uninstall scripts

Documentation

  • Comprehensive README.md with examples
  • ARCHITECTURE-DESIGN.md with architecture details
  • AGENTS.md for code agents working on the project
  • CONTRIBUTING.md for contributors
  • LICENSE.md (MIT)