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), 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.

What You Get Back

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

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

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

Source file, session ID, and timestamp on every response. Secrets auto-redacted before output.

Prefer markdown over JSON for human-facing output:

chorus read --agent codex --include-user --format markdown

Full JSON schema and field reference: docs/CLI_REFERENCE.md

Quick Start

1. Install

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

2. Setup

chorus setup
chorus doctor # Check session paths, provider wiring, and updates

setup also appends .agent-chorus/ to .gitignore automatically and, if the claude CLI is present, installs the Agent Chorus Claude Code plugin.

From zero to a working skill query in under a minute:

This wires skill triggers into your agent configs (CLAUDE.md, GEMINI.md, AGENTS.md) so agents know how to use chorus.

To cleanly reverse everything setup does (managed blocks, scaffolding, hooks):

chorus teardown           # reverse setup for this project
chorus teardown --global  # also remove ~/.cache/agent-chorus/

Claude Code integration (optional hook)

Wire a SessionEnd hook so Claude Code automatically broadcasts its
state to every other agent's inbox when a session ends — even on crash
or force-close. Add to ~/.claude/settings.json:

{
  "hooks": {
    "SessionEnd": [{
      "hooks": [
        {
          "type": "command",
          "command": "bash /absolute/path/to/agent-chorus/scripts/hooks/chorus-session-end.sh",
          "timeout": 10
        }
      ]
    }]
  }
}

The script delegates to chorus checkpoint --from claude and no-ops
silently on projects without .agent-chorus/, so it is safe to install
globally. Full wiring details:
docs/session-handoff-guide.md.

3. Ask

Tell any agent:

"What is Claude doing?"
"Compare Codex and Gemini outputs."
"Pick up where Gemini left off."

The agent runs chorus commands behind the scenes and gives you an evidence-backed answer.

After chorus setup, provider instructions follow this behavior:

• If no session is specified, read the latest session in the current project.
• "past session" / "previous session" means one session before latest.
• "last N sessions" includes latest.
• "past N sessions" excludes latest (older N sessions).
• Ask for a session ID only if initial fetch fails or exact ID is explicitly requested.

How It Works

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

Tenets:

• Local-first - reads directly from agent session logs on your machine. No data leaves.
• Evidence-based - every claim tracks to a specific source session file.
• Privacy-focused - automatically redacts API keys, tokens, and passwords.
• Dual parity - ships Node.js + Rust CLIs with identical output contracts.

Real-World Recipes

Quick Status Check

What is Claude working on right now? Get a structured digest — files touched, tools used, duration — without reading the full session. No LLM calls.

chorus summary --agent claude --cwd . --json

Cross-Agent Timeline

See what every agent did across your project, in chronological order.

chorus timeline --cwd . --format markdown

Tool Call Forensics

See exactly which files an agent read and edited — not just what it said.

chorus read --agent codex --tool-calls --json

Handoff Recovery

Gemini crashed mid-task. Claude picks up where it left off, with full context.

chorus read --agent gemini --cwd . --include-user --json

Cross-Agent Verification

Codex says it fixed the payment bug. Verify against Claude's analysis before deploying.

chorus compare --source codex --source claude --cwd . --json

Security Audit

Check what secrets appeared in agent sessions and were redacted.

chorus read --agent claude --audit-redactions --json

Agent Coordination

Tell Codex the auth module is ready — without switching tabs.

chorus send --from claude --to codex --message "auth module ready for review" --cwd .
chorus messages --agent codex --cwd . --json

Session Handoff

Broadcast where you left off to every other agent before ending a
session. Auto-composes branch, uncommitted-file count, and last commit;
override with --message when you want custom text.

chorus checkpoint --from claude --cwd .
chorus checkpoint --from codex --message "auth refactor half-done; types still broken" --cwd .

Pair with chorus messages --agent <self> --clear at standup to read
and drain the inbox other agents left you. Full protocol:
docs/session-handoff-guide.md.

Supported Agents

Full multi-agent coverage. No other tool matches this breadth across 4 agents and 12 capabilities.

*New in v0.11.0. These four features are Node-only; Rust parity is still pending (tracked on the roadmap).

Both Node.js and Rust implementations pass identical conformance tests against shared fixtures for core commands.

Key Capabilities

Session Summary

Structured session digest — files touched, tools used, duration — without reading the full content. No LLM calls required.

chorus summary --agent claude --cwd . --json

Cross-Agent Timeline

Chronological view interleaving sessions from multiple agents. See what happened across your entire project.

chorus timeline --cwd . --agent claude --agent codex --limit 5 --json

Tool Call Visibility

Surface every Read, Edit, Bash, and Write call an agent made — not just the text it produced.

chorus read --agent codex --tool-calls --json

Markdown Output

Render any read, summary, or timeline as formatted markdown instead of JSON. Useful for demos, docs, and human review.

chorus summary --agent claude --format markdown

Session Diff

Compare two sessions from the same agent with line-level precision.

chorus diff --agent codex --from session-abc --to session-def --cwd . --json

Redaction Audit Trail

See exactly what was redacted and why in any session read.

chorus read --agent claude --audit-redactions --json

Agent-to-Agent Messaging

Agents leave messages for each other through a local JSONL queue.

chorus send --from claude --to codex --message "auth module ready for review" --cwd .

Session Handoff Protocol

Standup + conclude rituals so cross-agent messaging actually gets used.
At standup, drain the inbox. At conclude, either chorus send a
targeted note or chorus checkpoint a state broadcast to every other
agent.

# At standup — read and drain
chorus messages --agent claude --clear --cwd .

# At conclude — broadcast state
chorus checkpoint --from claude --cwd .

chorus checkpoint is idempotent and no-ops silently when
.agent-chorus/ is absent. For Claude Code, wire
scripts/hooks/chorus-session-end.sh into ~/.claude/settings.json so
an abrupt session end still leaves a checkpoint. Gemini sessions stored
as protobuf (.pb) fall back via --chats-dir — see
docs/session-handoff-guide.md for
the full recipe.

Relevance Introspection

Inspect and test the agent-context filtering patterns that decide which files matter.

chorus relevance --list --cwd .              # Show current include/exclude patterns
chorus relevance --test src/main.rs --cwd .  # Test if a file matches

Full flag reference and JSON output schemas: docs/CLI_REFERENCE.md

How It Compares

Architecture

Chorus sits between your agent and other agents' session logs. The workflow is evidence-first: one agent reads another agent's session evidence and continues with a local decision, without a central control plane.

sequenceDiagram
    participant User
    participant Agent as Your Agent (Codex, Claude, etc.)
    participant Chorus as chorus CLI
    participant Sessions as Other Agent Sessions

    User->>Agent: "What is Claude doing?"
    Agent->>Chorus: chorus read --agent claude --include-user --json
    Chorus->>Sessions: Scan ~/.claude/projects/*.jsonl
    Sessions-->>Chorus: Raw session data
    Chorus->>Chorus: Redact secrets, format
    Chorus-->>Agent: Structured JSON
    Agent-->>User: Evidence-backed natural language answer

Current Boundaries

• No orchestration control plane: no task router, scheduler, or work queues.
• No autonomous agent chaining by default; handoffs are human-directed.
• No live synchronization stream; reads are snapshot-based from local session logs.

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.
This works the same for private repositories: the pack is local-first and does not require making your code public.

• 5 ordered docs + manifest.json (compact index, not a repo rewrite).
• Deterministic read order: 00 -> 10 -> 20 -> 30 -> 40.
• Agent-maintained in the intended workflow; verify with chorus agent-context verify.
• CI gate available: chorus agent-context verify --ci for PR freshness checks.
• Local recovery snapshots with rollback support.

# Recommended workflow:
chorus agent-context init    # Creates .agent-context/current/ with templates
# ...agent fills in <!-- AGENT: ... --> sections...
chorus agent-context seal    # Validates content and locks the pack

# Manual rebuild (backward-compatible wrapper)
chorus agent-context build

# Install pre-push hook (advisory-only check on main push)
chorus agent-context install-hooks

Ask your agent explicitly:

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

CI gate available: chorus agent-context verify --ci exits non-zero if the pack is stale or corrupt — wire it into your PR checks.

Full agent-context internals, sync policy, layered model, and enforcement details: AGENT_CONTEXT.md

Easter Egg

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

Roadmap

• Rust parity for v0.11.0 - summary, timeline, tool-calls, and markdown output in the Rust CLI (still pending).
• Context Pack customization - user-defined doc structure, custom sections, team templates.
• Windows installation - native Windows support (currently macOS/Linux).
• Cross-agent context sharing - agents share context snippets (still read-only, still local).

Go Deeper

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.