ReverbCode

A Go-backed agent orchestration daemon for supervising parallel coding-agent
sessions, with an ao CLI today and an Electron supervisor planned. 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.

What's shipped today

• Loopback-only HTTP daemon (backend/internal/httpd) controlling projects,
  sessions, orchestrators, and hook callbacks over 127.0.0.1.
• ao Cobra CLI (backend/cmd/ao) — a thin client over the daemon for daemon
  control, project/session/orchestrator management, and worker spawning.
• Worker/orchestrator spawn into isolated git worktree workspaces, launched
  inside a zellij runtime adapter.
• Live per-PR observation via the provider-neutral SCM observer
  (backend/internal/observe/scm/): polling loop, ETag guards, semantic
  diffing, CI/check/review-thread tracking, and lifecycle nudges for CI
  failures, review feedback, and merge conflicts.
• Agent adapters under backend/internal/adapters/agent/: claude-code,
  codex, opencode, grok, cursor, qwen, copilot, kimi, plus
  shared activity-dispatch / hook utilities.
• SQLite store (backend/internal/storage/sqlite/) with sqlc-generated
  queries, DB-triggered change-data-capture into change_log, and a CDC
  poller/broadcaster (backend/internal/cdc/) feeding in-process subscribers
  and an SSE replay endpoint.
• Session lifecycle manager + reaper (backend/internal/lifecycle/,
  backend/internal/observe/reaper/): runtime/activity/PR facts reduced into
  the small durable session state, display status derived at read time.

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

Current main ships the CLI surface above, the SCM observer end-to-end
(issues #75,
#108,
#109), the agent
adapter platform, and the CDC pipeline with SSE replay. The Tracker observer
(#112) and live
pr_* event consumers (#110)
are in flight. The Electron supervisor under frontend/ is still a placeholder
shell — daemon logic stays in the Go backend.

Tracking milestone:
rewrite 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.