Skip to content

ADR-022 — AI coding-agent orchestration & terminal dev environment

Date: 2026-05-22 Status: Accepted

Context

I want to develop software (starting with the Ready app) using two AI coding agents together — Claude Code as planner/reviewer and Codex as the primary implementer — without being locked into either tool's VS Code extension.

Priorities driving this decision: - Privacy and self-hosting (Forgejo; avoid third-party clouds where practical). - Reproducibility, future-proofing, and best practices. - Ability to run agents autonomously in a controlled, sandboxed environment. - Works over SSH into the homelab.

Options considered

  • Each tool's VS Code extension. Convenient inline editing, but ties me to the editor, is hard to automate or parallelize, and the Claude Code extension has had bugs ignoring .claude/settings.json permissions — undermining hands-off autonomy. Kept only for quick setup/edits.
  • Codex as an MCP server inside Claude Code (one driver + tool). Light setup, excellent for cross-provider review, but makes Codex subordinate — it fits "Claude codes, Codex reviews," the inverse of my desired "Codex codes, Claude reviews." Noted as a possible later complement for an extra review pass.
  • Hermes Agent (orchestration layer). Powerful for long-running autonomous goals, but heavyweight and aimed at problems I don't have yet.
  • Conductor (GUI orchestrator). Best-of-both visual diff + CLI engine, runs both agents, but: Mac-only, requires a proprietary account, runs agents unsandboxed with full user permissions, and was GitHub-coupled (since improved). Too much proprietary surface for my privacy posture.
  • Terminal-native multi-agent manager over tmux + git worktrees. Local, no proprietary account, honors CLI permission settings, scriptable, works over SSH. Candidates: Claude Squad (more mature) and Agent of Empires / AoE (MIT, Docker sandboxing, web/mobile access, agent status detection, multi-repo).

Decision

Adopt a terminal-native stack: - Agent orchestration: Agent of Empires (AoE) — manages Claude Code + Codex in isolated git worktrees on tmux, with Docker sandboxing and optional web/mobile access. Fallback: Claude Squad if AoE's youth becomes a problem. - Multiplexer: tmux (required by AoE; standardize on it rather than adding a second multiplexer such as Zellij). - Terminal emulator: Ghostty (fastest on macOS, native feel, inline images; multiplexing handled by tmux). - Diff / review: lazygit + git-delta (difftastic optional for structural diffs). - VS Code Claude Code extension: retained only for quick setup and in-editor edits — not the primary autonomous workflow. - VCS: Forgejo (self-hosted) as canonical remote; GitHub later if/when production-ready.

Consequences

  • Fully local; no proprietary orchestration account; agents sandboxed via Docker; reproducible and IaC-friendly; works over SSH into the homelab; honors per-tool permission configs.
  • More manual than a polished GUI (I dispatch and review), and AoE is young — mitigated by the tmux-based fallback to Claude Squad and by revisiting later.
  • Claude and Codex autonomy are configured separately (Claude via .claude/settings.json; Codex via its approval/sandbox mode).
  • The Ready app's own ADRs/RFCs live in the Ready repo; this environment/tooling decision is recorded here in homelab-docs.
  • Setup is captured in a redeployable runbook: workstation/ai-agent-dev-environment.md.