Skip to content

CLI Internals

Technical reference for understanding CLI internals.

packages/cli/
β”œβ”€β”€ src/
β”‚ β”œβ”€β”€ cli.ts # Entry point, argument parsing, routing
β”‚ β”œβ”€β”€ commands/
β”‚ β”‚ β”œβ”€β”€ workflow.ts # workflow route module: re-exports every subcommand; reset-sessions/cleanup/event
β”‚ β”‚ β”œβ”€β”€ workflow-control.ts # workflow resume/abandon/cancel/answer/approve/reject/respond (delegate to @archon/core/operations)
β”‚ β”‚ β”œβ”€β”€ workflow-query.ts # workflow list/test/status/get/runs/logs/wait
β”‚ β”‚ β”œβ”€β”€ workflow-run-*.ts # workflow run: select, admit, launch, execute
β”‚ β”‚ β”œβ”€β”€ isolation.ts # isolation list/cleanup (list/merged-cleanup delegate to @archon/core/operations)
β”‚ β”‚ β”œβ”€β”€ setup.ts # setup command implementation
β”‚ β”‚ β”œβ”€β”€ chat.ts # chat command implementation
β”‚ β”‚ β”œβ”€β”€ validate.ts # validate command implementation
β”‚ β”‚ └── version.ts # version command
β”‚ └── adapters/
β”‚ └── cli-adapter.ts # IPlatformAdapter for stdout
└── package.json # Defines "archon" binary
β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
β”‚ archon <command> [subcommand] [options] [arguments] β”‚
β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜
β”‚
β–Ό
β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
β”‚ strip-cwd-env-boot (first import, side-effect) β”‚
β”‚ stripCwdEnv(): deletes Bun-auto-loaded <cwd>/.env* keys from β”‚
β”‚ process.env + CLAUDE_CODE_* session markers. Emits β”‚
β”‚ [archon] stripped N keys from <cwd> (...) when N > 0. β”‚
β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜
β”‚
β–Ό
β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
β”‚ loadCliEnv(cwd) β€” wraps loadArchonEnv with identity protection β”‚
β”‚ 1. ~/.archon/.env (home scope) β”‚
β”‚ 2. <cwd>/.archon/.env (repo scope, exceptions below) β”‚
β”‚ Emits one [archon] loaded N keys from <path> line per file β”‚
β”‚ when N > 0 and ARCHON_VERBOSE_BOOT=1 or LOG_LEVEL=debug/trace.β”‚
β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜
β”‚
β–Ό
β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
β”‚ cli.ts Parse arguments β”‚
β”‚ --cwd, --branch, --no-worktree, --help β”‚
β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜
β”‚
β–Ό
β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
β”‚ cli.ts Project resolution β”‚
β”‚ Honor folder selection and registered folders; β”‚
β”‚ otherwise resolve the nearest Git checkout β”‚
β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜
β”‚
β–Ό
β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
β”‚ cli.ts Route to command handler β”‚
β”‚ switch(command) β†’ workflow | isolation | versionβ”‚
β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜
β”‚
β–Ό
β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
β”‚ cli.ts Exit with code, always closeDatabase() β”‚
β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜

Code: packages/cli/src/cli.ts

Repository env normally overrides home env. The CLI preserves the user-scope GH_CONFIG_DIR (including its absence), so repository env cannot redirect the stored gh login. Inside a workflow, inherited GitHub identity values take precedence over both env files, including empty values that disable host credentials. See forge plugin configuration.

Project resolution:

  • workflow run --folder uses the supplied canonical directory, even inside Git, and explicitly registers it as a folder project.
  • A registered folder and its ordinary descendants resolve to the folder directory. Archon runs folder workflows in place without managing a worktree, branch or PR.
  • A Git repository nested inside a registered folder retains its own repository identity. Other Git paths resolve to the nearest repository root, preserving linked-checkout ownership.
  • Unregistered non-Git execution requires folder registration; first-use CLI execution uses workflow run --folder. Without registration or that flag, execution exits with code 1.
  • File-only dry runs and fixture tests can inspect local files without registration. On a readable registry they honor folder ownership; if lookup fails they use the proven Git root or supplied directory. workflow list and validate retain their Git-root fallback when the registry cannot open.
  • version, help, setup, and chat bypass project resolution.

β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
β”‚ archon workflow list [name] [--full] [--json] β”‚
β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜
β”‚
β–Ό
β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
β”‚ workflow-query.ts workflowListCommand(cwd, { name, full, json })β”‚
β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜
β”‚
β–Ό
β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
β”‚ @archon/workflows/workflow-discovery β”‚
β”‚ discoverWorkflowsWithConfig(cwd, loadConfig, providerRegistry) β”‚
β”‚ - Loads bundled defaults β”‚
β”‚ - Searches .archon/workflows/ recursively β”‚
β”‚ - Merges (repo overrides defaults by name) β”‚
β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜
β”‚
β–Ό
β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
β”‚ Optional name resolution; project errors remain in the result β”‚
β”‚ full=false: bounded description + structured truncation state β”‚
β”‚ full=true: exact authored description β”‚
β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜
β”‚
β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”΄β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
β”‚ json=true β”‚ json=false
β–Ό β–Ό
β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
β”‚ JSON output to stdout β”‚ β”‚ Human-readable list to stdout β”‚
β”‚ descriptionTruncated β”‚ β”‚ shortened descriptions carry β”‚
β”‚ { workflows, errors } β”‚ β”‚ the ` [truncated]` marker β”‚
β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜

Code: packages/cli/src/commands/workflow-query.ts


β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
β”‚ archon workflow run <name> [message] [--branch X] [--detach] … β”‚
β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜
β”‚
β–Ό
β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
β”‚ selectRunWorkflow() β”‚
β”‚ - Locate the run a continuation resumes β”‚
β”‚ - Capture the workflow source, then discover from the capture β”‚
β”‚ - Find the workflow by name (error lists available) β”‚
β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜
β”‚
β–Ό
β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
β”‚ admitRunExecution() (--dry-run stops before this) β”‚
β”‚ - Flag, worktree policy, input and capability gates β”‚
β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜
β”‚
β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”΄β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
β”‚ β”‚
--detach (default)
β”‚ β”‚
β–Ό β–Ό
β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
β”‚ launchDetachedOwnedRun() β”‚ β”‚ prepareForegroundLaunch() β”‚
β”‚ Pre-flight, write the run β”‚ β”‚ Destination, project, adoption β”‚
β”‚ row, fork the child β”‚ β”‚ lane, --resume binding, AI config β”‚
β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜
β”‚
β–Ό
β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
β”‚ provisionWorkspace() β”‚
β”‚ Folder seam, reused --branch β”‚
β”‚ worktree, or a new worktree β”‚
β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜
β”‚
β–Ό
β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
β”‚ executeOwnedRun() β”‚
β”‚ Signal guard, progress, engine β”‚
β”‚ submit or resume, wait, teardown, β”‚
β”‚ result β”‚
β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜

Code: workflowRunCommand in packages/cli/src/commands/workflow-run-owned.ts, which owns the captured source and the durable-wait loop. The phases live in workflow-run-admission.ts, workflow-run-launch.ts and workflow-run-execution.ts beside it.

Worktree Provider: packages/isolation/src/providers/worktree.ts


β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
β”‚ archon workflow event emit --run-id <run-id> --type <type> [...] β”‚
β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜
β”‚
β–Ό
β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
β”‚ cli.ts Validate --run-id, --type (required) β”‚
β”‚ Validate --type against WORKFLOW_EVENT_TYPES β”‚
β”‚ Parse --data as JSON (warn + skip if invalid) β”‚
β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜
β”‚
β–Ό
β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
β”‚ workflow.ts workflowEventEmitCommand(..., cwd) β”‚
β”‚ Resolve an unambiguous run-id prefix β”‚
β”‚ Node state: persistWorkflowEvent(...) β”‚
β”‚ Observability: createWorkflowEvent(...) β”‚
β”‚ Run-ID resolution may fail β”‚
β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜

Code: packages/cli/src/cli.ts (case β€˜event’), packages/cli/src/commands/workflow.ts:workflowEventEmitCommand

Contract: The shared isNodeStateEventType predicate routes node-state events through persistWorkflowEvent, which propagates storage failures. The CLI prints Event persisted only after that write succeeds. Other events use createWorkflowEvent and retain best-effort persistence: Event submitted (best-effort) does not guarantee storage. Run-ID resolution can fail before either write.


archon isolation list β†’ isolationListCommand()
β”‚
β”œβ”€ @archon/core listEnvironments()
β”‚ β”œβ”€ isolationDb.listAllActiveWithCodebase()
β”‚ β”œβ”€ For each codebase: isolationDb.listByCodebaseWithAge()
β”‚ β”‚ └─ Reconcile missing worktrees, preserving live-run ownership
β”‚ └─ Return environments grouped by codebase and reconciliation totals
β”‚
β”œβ”€ Print worktree details and totals (return early if no codebases)
β”‚
β”œβ”€ @archon/core listContainerEnvironments()
β”‚ β”œβ”€ isolationDb.listActiveContainerEnvironments()
β”‚ β”œβ”€ getRunByIsolationEnvId() for each container
β”‚ β”‚ └─ Return matched run or null; throw on query/status errors
β”‚ └─ Build summaries; catch lookup errors and set runStatus: lookup-failed
β”‚
└─ Print container details and totals: run status, no run (orphan),
or run lookup failed

Code: packages/cli/src/commands/isolation.ts (isolationListCommand), packages/core/src/operations/isolation-operations.ts (listEnvironments), packages/core/src/services/cleanup/containers.ts (listContainerEnvironments), packages/core/src/db/workflow-run-reads.ts (getRunByIsolationEnvId).

The container listing matches metadata.isolation_env_id; no match does not establish that cleanup can remove the container. Cleanup checks wider live ownership. A failed lookup is logged and displayed as run lookup failed.


archon isolation cleanup [days] (default: 7)
β”‚
β”œβ”€ Reconcile missing worktrees (preserve container rows)
β”‚
β”œβ”€ findStaleEnvironments(days)
β”‚ └─ Filter provider = 'worktree'
β”‚ └─ For each stale worktree:
β”‚ β”œβ”€ Skip environments owned by resumable runs
β”‚ β”œβ”€ Skip any with a commit on no remote (getCleanupRunLock)
β”‚ └─ provider.destroy(path, options)
β”‚ └─ Mark destroyed only after complete removal
β”‚
└─ cleanupContainerEnvironments(days), even when no worktrees are stale
β”œβ”€ Skip containers owned by resumable runs
└─ Container backend removes container and volume
└─ Mark destroyed only after successful removal

Code: isolationCleanupCommand in packages/cli/src/commands/isolation.ts


β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
β”‚ archon isolation cleanup --merged [--include-closed] β”‚
β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜
β”‚
β–Ό
β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
β”‚ isolation.ts isolationCleanupMergedCommand({ includeClosed }) β”‚
β”‚ For each codebase β†’ cleanupMergedWorktrees(codebaseId, path) β”‚
β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜
β”‚
For each active environment
β”‚
β–Ό
β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
β”‚ judgeBranchForRemoval() β€” three-signal union β”‚
β”‚ localBranchExists() gate: (a) and (b) need the local ref β”‚
β”‚ (a) isBranchMerged() git ancestry (fast-forward/merge) β”‚
β”‚ (b) isPatchEquivalent() git cherry (1-commit squash-merge) β”‚
β”‚ (c) getPrState() gh CLI (MERGED/CLOSED/OPEN/NONE/ β”‚
β”‚ UNAVAILABLE) β”‚
β”‚ β”‚
β”‚ any git signal β†’ 'merged' if the worktree HEAD β”‚
β”‚ also passes `git cherry <base> HEAD` β”‚
β”‚ MERGED β†’ 'merged' if the worktree HEAD β”‚
β”‚ and the branch ref (where each β”‚
β”‚ exists) are at or behind the PR head β”‚
β”‚ CLOSED β†’ 'pr-closed' the same way, only if β”‚
β”‚ includeClosed β”‚
β”‚ OPEN β†’ 'open-pr', always kept β”‚
β”‚ UNAVAILABLE β†’ 'pr-unavailable', kept and reported β”‚
β”‚ NONE and ref present β†’ 'unmerged', not reclaimed β”‚
β”‚ NONE and ref gone β†’ 'unjudgeable', kept and reported β”‚
β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜
β”‚ 'merged' or 'pr-closed'
β–Ό
β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
β”‚ Guard checks: no uncommitted changes, no run lock (checkRemoval β”‚
β”‚ β†’ getCleanupRunLock; a failed run's lock is released by the β”‚
β”‚ verdict, running/pending/paused runs always lock) β”‚
β”‚ provider.destroy() β†’ remove worktree and local branch β”‚
β”‚ β†’ commit registration retirement; retain remote branch β”‚
β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜

Completion and merged cleanup retain remote branches, including with force, because registration ownership cannot be proved after retirement. Retention is logged as a warning and displayed in both completion and merged-cleanup reports. Enable GitHub’s Automatically delete head branches setting for merged pull requests, or follow manual remote branch recovery.

Signals are evaluated in order β€” the first positive match short-circuits to avoid unnecessary gh API calls. The gh CLI is a soft dependency: when it is not installed or the remote is not GitHub, only git signals are used (NONE). When gh is there but fails (auth, rate limit, unreadable output) the result is UNAVAILABLE, and the environment is kept and reported rather than passed to the staleness sweep.

A multi-commit squash merge is invisible to both git signals, so PR state is the only one that sees it. Both git signals also need the local branch ref: once it is gone, the PR is the only judge, and a branch with no PR is reported as unverifiable instead of failing the check. A MERGED or CLOSED PR only covers the commits it carried. Run branch names are reused, and removal deletes both the worktree and the branch, so each local tip that still exists, the worktree’s HEAD and the branch ref, must be the PR’s head commit or an ancestor of it (isRevCoveredBy). A detached HEAD or a reused branch with commits past the PR head is unmerged work. The same holds when git proves the merge: the worktree’s HEAD must also pass git cherry <base> HEAD, which answers for both git signals (an ancestor of the base lists nothing, a squash-merged commit lists as -). A HEAD it cannot answer for is reported as a failed merge check. A PR head pushed from elsewhere and never fetched here is fetched by SHA from the branch’s remote first; if that fetch fails, the check fails and the worktree is kept, with the fetch error in the reason. The scheduled sweep (runScheduledCleanup) makes the same call, so both paths agree on what counts as merged.

Code: packages/core/src/services/cleanup/ β€” judgeBranchForRemoval() in merge-verdict.ts, cleanupMergedWorktrees() in merged-sweep.ts, getCleanupRunLock() in run-lock.ts; runScheduledCleanup() in packages/core/src/services/cleanup-service.ts Code: packages/isolation/src/pr-state.ts β€” getPrState() Code: packages/git/src/branch.ts β€” isPatchEquivalent(), localBranchExists()


Implements IPlatformAdapter for terminal output.

β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
β”‚ CLIAdapter β”‚
β”œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€
β”‚ sendMessage(convId, msg) β†’ Output to stdout β”‚
β”‚ getStreamingMode() β†’ 'batch' β”‚
β”‚ getPlatformType() β†’ 'cli' β”‚
β”‚ ensureThread() β†’ passthrough β”‚
β”‚ start() / stop() β†’ no-op β”‚
β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜

Code: packages/cli/src/adapters/cli-adapter.ts:13-47


FunctionPackageLocationPurpose
discoverWorkflowsWithConfig(cwd, loadConfig, providerRegistry)@archon/workflows/workflow-discoveryworkflows/src/workflow-discovery.tsFind and parse workflow YAML
executeWorkflow(...)@archon/workflows/executorworkflows/src/executor.tsRun workflow steps
getIsolationProvider()@archon/isolationisolation/src/factory.tsGet WorktreeProvider singleton
conversationDb.*@archon/corecore/src/db/conversations.tsConversation CRUD
codebaseDb.*@archon/corecore/src/db/codebases.tsCodebase CRUD
isolationDb.*@archon/corecore/src/db/isolation-environments.tsWorktree tracking
git.*@archon/gitpackages/git/src/Git operations
closeDatabase()@archon/corecore/src/db/connection.tsClean shutdown

CLI conversations use ID format: cli-{timestamp}-{random}

The random suffix contains 16 cryptographically random bytes encoded as 32 hex characters.

Generated at: packages/cli/src/utils/conversation-id.ts


When --branch is provided:

  1. Lookup: isolationDb.findActiveByWorkflow(codebaseId, 'task', branchName)
  2. Health check: provider.healthCheck(path) on existing
  3. Reuse: If found and healthy (warns if --from was specified but not applied)
  4. Create: If not found or unhealthy β€” passes a taskBranch: { kind: 'new', fromBranch } selection to the provider when --from is specified. Adoption instead passes taskBranch: { kind: 'existing', branch }, which checks out that exact local branch without creating a child branch or syncing it to a remote.

Worktrees stored at: ~/.archon/workspaces/<owner>/<repo>/worktrees/<branch-slug>/

Code: provisionWorktree in packages/cli/src/commands/workflow-run-launch.ts


CodeMeaning
0Success, except for the JSON control refusals noted below.
1Error. Answer commands (answer, respond, approve, reject) and resume --detach also return 1 on refusal. Human-mode diagnostics go to stderr; JSON refusals emit ok: false with the reason on stdout.

Non-detached JSON resume, abandon, and cancel can return 0 with ok: false. Check ok when consuming those acknowledgments.


  • Connection opened on first database call
  • Always closed in finally block after command completes
  • Default: SQLite at ~/.archon/archon.db (zero setup, auto-initialized)
  • Optional: PostgreSQL when DATABASE_URL is set (for cloud/advanced deployments)

Code: packages/cli/src/cli.ts