ReverbCode

The orchestration layer for parallel AI coding agents. ReverbCode is a Go-backed daemon that supervises many coding-agent sessions at once, each in its own git worktree, and routes the feedback they need (CI failures, review comments, merge conflicts) back to the right agent automatically. It ships with an ao CLI and an Electron supervisor that both drive the same daemon over loopback.

The Go module and packages remain agent-orchestrator; "ReverbCode" is the public name.

See docs/architecture.md for the backend mental model and AGENTS.md for the contributor / worker contract. For current progress (what's shipped vs. in flight) see docs/STATUS.md.

What it does

• Agent-agnostic. A 23-adapter platform under backend/internal/adapters/agent/ (claude-code, codex, cursor, opencode, aider, amp, goose, copilot, grok, qwen, kimi, crush, cline, droid, devin, auggie, continue, kiro, kilocode, and more), registered through a shared registry with common activity-dispatch / hook utilities. The default is set by AO_AGENT.
• Isolated workspaces. Worker and orchestrator sessions spawn into their own git worktree (backend/internal/adapters/workspace/gitworktree/), launched inside a zellij runtime adapter (backend/internal/adapters/runtime/) so every session has its own attachable terminal.
• Live PR observation. The provider-neutral SCM observer (backend/internal/observe/scm/) polls each session's PR with ETag guards and semantic diffing, tracking CI/check runs and review threads, and feeds those facts into the lifecycle manager, which sends the owning agent nudges for CI failures, review feedback, and merge conflicts. GitHub is the implemented provider today.
• Durable facts, derived status. The SQLite store (backend/internal/storage/sqlite/) persists a small set of session facts plus PR/check/comment rows; display status is computed at read time, never stored. DB triggers append every user-visible change to change_log, and a CDC poller/broadcaster (backend/internal/cdc/) feeds in-process subscribers and an SSE replay endpoint.
• Loopback-only daemon. The HTTP daemon (backend/internal/httpd) controls projects, sessions, orchestrators, and hook callbacks over 127.0.0.1 with no auth, CORS, or TLS by design.
• Lifecycle manager + reaper (backend/internal/lifecycle/, backend/internal/observe/reaper/) reduce runtime/activity/PR observations into the durable session state and reclaim dead sessions.

How it works

1. Register a local git repo as a project (ao project add).
2. Spawn a worker session (ao spawn), or an orchestrator that fans work out across sessions. Each session gets its own git worktree and a zellij pane.
3. The agent develops, tests, and opens a PR from inside its worktree.
4. The SCM observer watches that PR and routes feedback back to the agent: a CI failure, a requested change, or a merge conflict becomes a nudge to the agent that owns the PR.
5. You inspect, attach a terminal, and merge from the CLI or the Electron app; human attention is needed only where the loop can't resolve on its own.

Extensibility

The backend is organized around inbound/outbound port contracts (backend/internal/ports/) with swappable adapters under backend/internal/adapters/:

Port	Implemented adapters
Agent	23 harnesses (see above)
Runtime	zellij
Workspace	git worktree
SCM	GitHub
Tracker	GitHub (adapter present; no runtime loop yet)
Reviewer	claude-code
Notifier	port defined; no shipped adapter yet

See docs/STATUS.md for which lanes are live at runtime.

Quick start

Requirements: Go 1.25+, zellij on PATH for the runtime adapter, and gh (or GITHUB_TOKEN) if you want the SCM observer to authenticate against GitHub. The SQLite driver is the pure-Go modernc.org/sqlite — no system SQLite library is required.

cd backend
go build -o /tmp/ao ./cmd/ao

# Start the daemon and wait for /readyz.
/tmp/ao start

# Register a local git repo as a project. The id defaults to the lowercased
# base of --path; pass --id explicitly when the directory name doesn't match.
/tmp/ao project add --path /path/to/your/repo --id your-repo --name your-repo

# Spawn a worker session running the default agent.
/tmp/ao spawn --project your-repo --prompt "Refactor the auth module"

# Inspect what's running.
/tmp/ao status
/tmp/ao session ls

Electron app (dev)

The desktop supervisor lives under frontend/ and is started separately:

cd frontend
npm install
npm run dev   # electron-forge start

Heads-up: npm run dev does not start the daemon for you. Start it first (ao start, see above) — the renderer attaches to the running daemon over loopback (127.0.0.1:3001 by default, the AO_PORT from the table below). Without a daemon the app opens but shows its daemon-not-ready state.

For renderer-only UI work without the Electron shell, use npm run dev:web (Vite in a regular browser).

CLI surface

The CLI is intentionally thin: every product command resolves to a daemon HTTP route. Run ao <command> --help for the authoritative flag shape; the table below groups what's on main today.

Lane	Command	Purpose
Daemon	ao start	Start the daemon in the background and wait for /readyz.
Daemon	ao stop	Graceful shutdown via loopback POST /shutdown.
Daemon	ao status	Report PID/port/health/readiness from running.json.
Daemon	ao daemon	Hidden internal entrypoint used by ao start.
Project	ao project add	Register a local git repo as a project.
Project	ao project ls	List registered projects.
Project	ao project get <id>	Fetch one project.
Project	ao project set-config <id>	Update per-project config.
Project	ao project rm <id>	Remove a project.
Session	ao spawn	Spawn a worker session in a registered project.
Session	ao session ls	List sessions (filter by project, include terminated).
Session	ao session get <id>	Fetch one session.
Session	ao session kill <id>	Terminate a session.
Session	ao session rename <id> <name>	Rename a session.
Session	ao session restore <id>	Relaunch a terminated session.
Session	ao session cleanup	Reclaim eligible workspaces for terminated sessions.
Session	ao session claim-pr <session> <pr>	Attach an existing PR to a session.
Orchestrator	ao orchestrator ls	List orchestrator sessions.
Messaging	ao send	Send a message to a running agent session.
Utility	ao doctor	Local health checks (config, data dir, DB, git, zellij).
Utility	ao completion <shell>	Generate bash/zsh/fish/powershell completions.
Utility	ao version	Print build metadata.
Internal	ao hooks <agent> <event>	Hidden adapter hook callback.

See docs/cli/ for the daemon-control intent and command shape.

Configuration

All configuration is env-driven; the daemon takes no config file. The bind host is hard-coded to 127.0.0.1 — the daemon has no auth, CORS, or TLS, and exposing it beyond loopback would be a security regression.

Var	Default	Purpose
AO_PORT	3001	Bind port; daemon fails fast if taken.
AO_REQUEST_TIMEOUT	60s	Per-request timeout (Go duration).
AO_SHUTDOWN_TIMEOUT	10s	Graceful-shutdown hard cap.
AO_RUN_FILE	<UserConfigDir>/agent-orchestrator/running.json	PID + port handshake path.
AO_DATA_DIR	<UserConfigDir>/agent-orchestrator/data	SQLite DB, WAL files, managed state.
AO_AGENT	claude-code	Default agent adapter id used by ao spawn.
AO_SESSION_ID	(unset)	Set inside spawned sessions; read by ao send and ao hooks.
GITHUB_TOKEN	(unset)	Used by the GitHub SCM and tracker adapters. Falls back to gh auth token.

Health check:

curl localhost:3001/healthz
curl localhost:3001/readyz

Architecture

The daemon is a long-running supervisor. Adapters observe external facts (PR state, agent activity, runtime liveness); the lifecycle manager reduces those into a small set of durable session facts (activity_state, is_terminated, PR rows). Display status is derived from those facts at read time — it is never stored. SQLite triggers append every user-visible change to change_log, and the CDC poller broadcasts those events to in-process subscribers and an SSE stream.

Full mental model and load-bearing rules: docs/architecture.md. Package-by-package ownership: docs/backend-code-structure.md.

Testing

The local gate is the backend Go build and race-enabled test suite:

cd backend && go build ./... && go test -race ./...

GitHub Actions is the authoritative pre-merge gate; mirror its commands here when in doubt. See AGENTS.md for the regen workflow when touching the daemon API surface (npm run sqlc, npm run api).

Status and roadmap

Progress tracking lives in docs/STATUS.md: what is shipped on main today, what is still in flight, and the linked rewrite milestone on GitHub.

Contributing

Repo layout and the worker contract live in AGENTS.md. Keep changes surgical, follow the package boundaries documented in docs/backend-code-structure.md, and prefer adding daemon HTTP routes over leaking storage / runtime into the CLI.