Agent Chorus

Let your AI agents talk about each other.

Ask one agent what another is doing, and get an evidence-backed answer. No copy-pasting, no tab-switching, no guessing.

If you use 2+ AI coding agents (Codex, Claude, Gemini, Cursor CLI, Cursor IDE), Chorus gives them shared visibility — no orchestrator required.

chorus read --agent claude --include-user --json

Two problems, one tool:

• Silo Tax — multi-agent workflows break when agents cannot verify each other's work. Chorus gives every agent read access to every other agent's session evidence.
• Cold-Start Tax — every new session re-reads the same repo from zero. A Context Pack gives agents instant repo understanding in 5 ordered docs.

See It In Action

The Handoff

Switch from Gemini to Claude mid-task. Claude picks up where Gemini left off.

The Status Check

Three agents working on checkout. You ask Codex what the others are doing.

From Zero to a Working Query

chorus setup wires every agent on the box in under a minute.

Quick Start

# 1. Install
npm install -g agent-chorus      # requires Node >= 18
# or
cargo install agent-chorus       # requires Rust >= 1.74

# 2. Wire your agents
chorus setup                     # patches CLAUDE.md / GEMINI.md / AGENTS.md, adds .gitignore entries
chorus doctor                    # verify session paths, provider wiring, updates

# 3. Ask any agent in natural language
#    "What is Claude doing?"  /  "Compare Codex and Gemini outputs."  /  "Pick up where Gemini left off."

Or call chorus directly:

chorus read --agent codex --include-user --json

Every response is structured, source-tracked, and redacted:

{
  "agent": "codex",
  "session_id": "session-abc123",
  "content": "USER:\nInvestigate the auth regression...\n---\nASSISTANT:\nI am tracing the auth middleware...",
  "timestamp": "2026-06-02T10:30:00Z",
  "message_count": 12,
  "source": "/home/user/.codex/sessions/2026/06/02/session-abc123.jsonl"
}

Source file, session ID, and timestamp on every response. Secrets auto-redacted before output. Prefer --format markdown for human review.

To reverse everything setup did: chorus teardown (add --global to also drop ~/.cache/agent-chorus/).

What's New in v0.16.0

• Cursor IDE adapter. Chorus now reads both the cursor-agent CLI transcripts and Cursor IDE app sessions through one adapter. If you use the Cursor app, your sessions are now first-class.
• --history=on-demand default. chorus read now returns just the latest session for the current cwd. Closes the 2.5x token-inflation issue measured in the v0.15 field study. Provider snippets carry the contract so consumer agents inherit it automatically.
• cwd_mismatch is now explicit. When --cwd matches no session, the output says so. No more silent fallbacks that read like real data.
• Doctor honesty pass. New info severity, env-var dangling-path detection, git-aware hooks checks, stale-snippet detection. Doctor tells the truth or stays quiet.
• Codex search parity fix. chorus search --agent codex no longer silently returns empty. The read ⊆ search invariant is now enforced for every adapter.
• --help overhaul. Per-subcommand help leads with that subcommand. chorus report --help ships a copy-pasteable handoff JSON schema.

Full changelog and upgrade notes: RELEASE_NOTES.md.

How It Works

1. Ask naturally — "What is Claude doing?" / "Did Gemini finish the API?"
2. Your agent runs chorus — chorus summary, read, timeline, compare, search, diff, send, messages, checkpoint, etc.
3. Evidence-backed answer — sources cited, divergences flagged, no hallucination.

Tenets:

• Local-first — reads agent session logs directly on your machine. No data leaves.
• Evidence-based — every claim tracks to a specific source session file.
• Privacy-focused — auto-redacts API keys, tokens, and passwords.
• Dual parity — Node.js + Rust CLIs ship identical output contracts, conformance-tested against shared fixtures.

How It Compares

	agent-chorus	CrewAI / AutoGen / LangGraph	ccswarm / claude-squad
Approach	Read-only evidence layer	Full orchestration framework	Parallel agent spawning
Install	npm i -g agent-chorus or cargo install	pip + ecosystem	git clone
Agents covered	Codex, Claude, Gemini, Cursor CLI + IDE	Provider-specific	Usually Claude-only
Runtime deps shipped	Zero	Heavy Python/TS stack	Moderate
Privacy	Local-first, auto-redaction	Cloud-optional	Varies
Built-ins unique to chorus	session summary (no LLM), cross-agent timeline, session diff, handoff protocol, agent-to-agent messages, context pack	none	none
Implementation	Node.js + Rust, conformance-tested	Single language	Single language
Philosophy	Visibility first, orchestration optional	Orchestration first	Task spawning

Chorus is the evidence layer underneath whatever orchestrator you use — not a replacement. If you want a router/scheduler/work-queue, pair chorus with one of the frameworks above. If you just want agents to see each other's work, chorus alone is enough.

Key Capabilities

A taste — see docs/CLI_REFERENCE.md for the full surface.

# Structured digest — files, tools, duration. No LLM calls.
chorus summary --agent claude --cwd . --json

# Chronological view across every agent on the project
chorus timeline --cwd . --format markdown

# What an agent actually touched (Read/Edit/Bash/Write)
chorus read --agent codex --tool-calls --json

# Verify one agent's claim against another
chorus compare --source codex --source claude --cwd . --json

# Audit what got redacted, and why
chorus read --agent claude --audit-redactions --json

# Coordinate without switching tabs
chorus send --from claude --to codex --message "auth module ready" --cwd .
chorus messages --agent codex --cwd . --json

# Broadcast where you left off before ending a session
chorus checkpoint --from claude --cwd .

Supported Agents

Every adapter supports read / list / search / summary / timeline / send / messages / checkpoint. The differences are where each agent stores sessions and which adapters render tool-call content vs. emit a uniform NOT_AVAILABLE warning.

Agent	Session source	--tool-calls
Codex	~/.codex/sessions/**/*.jsonl	renders
Claude	~/.claude/projects/**/*.jsonl	renders
Cursor CLI	~/.cursor/projects/*/agent-transcripts/**/*.jsonl	renders
Cursor IDE (app) (new in v0.16.0)	~/.cursor/chats/*/*/store.db (SQLite; requires Node ≥ 22.5 for the IDE surface)	renders
Gemini	~/.gemini/tmp/*/chats/*.json[l]	uniform NOT_AVAILABLE warning (gemini transcripts don't carry tool calls)
Hermes (provisional scaffold)	~/.hermes/sessions/**/*.jsonl	uniform NOT_AVAILABLE warning

Node and Rust runtimes ship identical output for every agent above; the read(text) ⊆ search(text-tokens) invariant is CI-enforced for each adapter. Full per-flag reference: docs/CLI_REFERENCE.md.

Context Pack

A context pack is an agent-first, token-efficient repo briefing for end-to-end understanding tasks. Instead of re-reading the full repository on every request, agents start from .agent-context/current/ and open project files only when needed. Local-first, no need to make your repo public.

chorus agent-context init    # creates .agent-context/current/ with templates
# ...agent fills in the <!-- AGENT: ... --> sections...
chorus agent-context seal    # validates and locks the pack

Ask your agent: "Understand this repo end-to-end using the context pack first, then deep dive only where needed."

CI gate: chorus agent-context verify --ci exits non-zero if the pack is stale or corrupt. Internals, sync policy, enforcement: AGENT_CONTEXT.md.

Architecture, in one diagram

Chorus sits between your agent and other agents' session logs. Read-only, evidence-first, no central control plane.

Boundaries: no task router, no scheduler, no autonomous chaining, no live sync stream. Snapshot-based reads from local logs, by design.

Roadmap

What's queued. Direction over dates; specifics confirmed in RELEASE_NOTES.md as each ships.

Next (v0.16.1) — patch release covering UAT findings from the v0.16.0 review week: Gemini latest-read selection on empty-assistant sessions, chorus checkpoint silent-no-op invariant in non-chorus cwds, chorus report missing-mode error path, cursor timeline source field, and read ⊆ search invariant edge cases on Codex + Claude. Hermes added to the read-output schema enum.

Soon

• Agent-context as a separate library — moving pack format, templates, and verify/seal algorithm into cote-star/agent-context as the single source of truth; chorus consumes a versioned dependency. Closes the two-truth state that produced the schema-drift incidents in v0.14.x.
• Agy CLI adapter — Google's successor to the deprecated gemini CLI. Same parity bar as the other adapters: list/read/search/timeline/send/messages/checkpoint/doctor/setup.
• Hermes promotion — from provisional scaffold to full adapter once the OSS agent-lab integration lands.

Later

• Formal checkpoint schema — JSON Schema for chorus checkpoint payloads, validated in conformance.
• Project-local session-log mirror — repo-local fallback session source for agents whose native storage is partial or ephemeral.
• Gemini legacy deprecation — once upstream Gemini CLI is formally retired by Google.

Explicitly NOT planned

• Orchestration / task router / scheduler — chorus is the evidence layer underneath an orchestrator, not a replacement.
• Cloud sync of session data — local-first is a tenet, not a default we plan to flip.
• Live streaming of session updates — snapshot-based reads by design.

Easter Egg

chorus trash-talk roasts your agents based on their session content.

Go Deeper

If you need...	Go here
Full command syntax and JSON outputs	docs/CLI_REFERENCE.md
Adapter formats, schema contracts, redaction rules	PROTOCOL.md
Session handoff protocol, hooks, Gemini .pb fallback	docs/session-handoff-guide.md
Agent-context internals and policy	AGENT_CONTEXT.md
Release-level changes and upgrade notes	RELEASE_NOTES.md
Contributing or extending the codebase	docs/DEVELOPMENT.md / CONTRIBUTING.md

---

Every agent session is evidence. Chorus makes it readable.

Found a bug or have a feature idea? Open an issue. Ready to contribute? See CONTRIBUTING.md.