Skip to content

CHANGELOG.md

Latest commit

 

History

History
1120 lines (862 loc) · 70.2 KB

CHANGELOG.md

File metadata and controls

1120 lines (862 loc) · 70.2 KB

Changelog

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

[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)
⚡