The Construct CLI 0.12.0 - 2026-01-07

Release Notes

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

The Construct CLI 0.11.6 - 2026-01-06

Release Notes

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)

The Construct CLI 0.11.5 - 2026-01-05

Release Notes

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.

The Construct CLI 0.11.4 - 2026-01-05

Release Notes

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.

The Construct CLI 0.11.3 - 2026-01-03

Release Notes

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 sys install-packages 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 sys 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)

The Construct CLI 0.11.2

Release Notes

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

The Construct CLI 0.11.1

Release Notes

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

The Construct CLI 0.10.1 - 2025-12-31

Release Notes

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.

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.
• 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.

The Construct CLI 0.10.0 - 2025-12-30

Release Notes

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 construct sys install-packages command 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.

The Construct CLI 0.9.1 - 2025-12-27

Release Notes

Changed

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