Archon: Harness for Repeatable AI Coding Workflows

Git Worktree Isolation: Foundation for Deterministic AI Coding

Archon structures AI coding as isolated git worktrees, preventing branch switches and cross-contamination that plague non-deterministic agent runs. Each workflow runs in its own worktree branched from $BASE_BRANCH (e.g., main), with strict verification of ownership and parent repo matching. This eliminates flaky behaviors like AI adopting wrong branches or stale orphans.

Key techniques:

WorktreeProvider.findExisting: Verifies worktree's gitdir matches request; throws on cross-checkout, submodules, or malformed states instead of silent nulls.
WorktreeProvider.createNewBranch: Resets stale orphans to exact start-point, avoiding inherited commits.
Prompt decision trees in .archon files (e.g., archon-implement.md): "IN WORKTREE?" first, then explicit $BASE_BRANCH usage, banning branch switches.

Recent fixes (e.g., #1198) addressed bypasses via prompts or git adoption: normalized paths with resolve(), classified isolation errors for user-friendly messages, and propagated failures without retries. Result: AI operates solely within its sandbox, reporting true success only on clean worktrees.

"fix: prevent worktree isolation bypass via prompt and git-level adoption... Three fixes for workflows operating on wrong branches: - archon-implement prompt: replace ambiguous branch table with decision tree that trusts the worktree isolation system..."

This pattern scales to production: no global state leaks, easy parallel runs, git-native cleanup.

Claude Code Provider: Binary-First Reliability Over SDK Embeds

Archon prioritizes Anthropic's native Claude Code binary (curl installer at /.local/bin/claude) for cross-platform stability, ditching flaky @anthropic-ai/claude-agent-sdk/embed. Resolution cascade: CLAUDE_BIN_PATH env > config.claude.claudeBinaryPath > setup wizard probes (/.local/bin, npm global, PATH) > actionable error.

Security-focused spawning:

Strip parent env to block leaks (#1067).
--no-env-file only for Bun/Node-spawned cli.js (not native binaries, which reject it).
Helpers like shouldPassNoEnvFile(cliPath) and probe tiers (probeFileExists, probeNpmRoot, probeWhichClaude) for auditable decisions.

Tests cover edge cases: Windows backslashes, Homebrew symlinks, stale PATH entries, quota errors. Setup wizard writes ~/.archon/.env atomically; Dockerfiles preset paths. Docs updated for curl-first story, troubleshooting platform snippets.

Codex symmetry: Matching resolvers (resolveClaudeBinaryPath, codexFileExists). Retires macOS/Windows silent fails (#1210, #1087).

"Drop @anthropic-ai/claude-agent-sdk/embed and resolve Claude Code via CLAUDE_BIN_PATH env → assistants.claude.claudeBinaryPath config → throw with install instructions. The embed's silent failure modes on macOS (#1210) and Windows (#1087) become actionable errors..."

Trade-off: Native binary skips JS env quirks but needs install; dev mode auto-resolves node_modules.

Visual Workflow Builder: Composable Nodes Without Flakiness

Web UI (auth-service, likely React/TS) lets you drag nodes into DAGs for multi-step coding: plan-setup, implement, fix-issue. Node Library panel resizable (160-400px, localStorage-persisted, ARIA drag handle), with lazy state and try-catch for private browsing.

Recent: #837 fixed lint/format, obsolete mocks (current_step_index gone), Docker interference in tests. Co-authored by Claude Sonnet 4.6, showing self-dogfooding.

Extensible via .archon/.claude prompts; supports 1M context Opus. Backend likely Node, with workflow runs updating via mocks-turned-real APIs.

"feat(web): make workflow builder Node Library panel resizable... Width persists in localStorage across sessions. Closes #834. Co-Authored-By: Claude Sonnet 4.6"

Developer Experience: Hooks, Tests, and Cloud-Ready Deploys

Husky + lint-staged enforce Prettier on ts/js/json/md pre-commit (#226), killing format drift. 1,211 commits on dev branch, kagura-agent contributor.

Deploy: cloud-init creates 'archon' user (sudo/docker groups, passwordless), 2GB swap for low-RAM VPS, docker pulls as non-root. Hardens SSH key copy, OOM prevention.

Workflows: E2E smoke tests, Windows-compatible paths, isolation classifies errors. Badges/logo polish README.

"chore: Add pre-commit hook to prevent formatting drift (#226)... husky + lint-staged to run Prettier on staged files before each commit."

Stats signal traction: 17.9k stars, 2.8k forks, 28 branches, 9 tags. Active Apr 2026 commits despite future dates (likely placeholder).

"The first open-source harness builder for AI coding. Make AI coding deterministic and repeatable."

Key Takeaways

Clone https://github.com/coleam00/Archon, bun install, run setup wizard—it auto-detects Claude Code and sets CLAUDE_BIN_PATH.
Use archon implement in a repo: AI plans/creates in isolated worktree from main, no branch jumps.
Customize workflows visually: Resize Node Library, drag plan/implement/fix nodes, persist locally.
For prod: Extend Dockerfile with CLAUDE_BIN_PATH; deploy via cloud-init for VPS (adds swap/user hardening).
Debug isolation: Watch logs for gitdir mismatches; prompts now enforce worktree-only ops.
Test Claude native: curl https://claude.ai/install, verify ~/.local/bin/claude, rerun setup.
Enforce DX: Add husky/lint-staged to your AI projects—prevents format CI fails.
Scale agents: Parallel worktrees beat monorepo hacks; verify with WorktreeProvider tests.
Avoid SDK embeds: Always resolve binaries explicitly for macOS/Windows reliability.