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.

chorus read --agent claude --json

Why It Exists

• Silo Tax: multi-agent workflows break when agents cannot verify each other's work.
• Cold-Start Tax: every new session re-reads the same repo from zero.
• Visibility-first architecture: give agents evidence + context first; add orchestration only when needed.

How It Works

1. Ask naturally - "What is Claude doing?" / "Did Gemini finish the API?"
2. Agent runs chorus - Your agent calls chorus read, chorus compare, chorus diff, chorus send, 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.

Demo

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.

Quick Start

1. Install

npm install -g agent-chorus
# or
cargo install agent-chorus

2. Setup

chorus setup
chorus doctor # Checks health, context pack state, and updates

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.

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.

Session Selection Defaults

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.

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.

At a glance:

• 5 ordered docs + manifest.json (compact index, not a repo rewrite).
• Deterministic read order: 00 -> 10 -> 20 -> 30 -> 40.
• Main-only smart sync: updates only when context-relevant files change.
• Local recovery snapshots with rollback support.

Recommended Workflow

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

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

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

Ask your agent explicitly:

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

Context Pack Demo

Create and wire a context pack for token-efficient repo understanding:

Main Push Sync Policy

• Pushes that do not target main: skipped.
• Pushes to main with no context-relevant changes: skipped.
• Pushes to main with context-relevant changes: advisory warning printed (no auto-build).

Optional pre-PR guard:

chorus context-pack check-freshness --base origin/main

Usage Boundaries

• Do not treat context pack as a substitute for source-of-truth when changing behavior-critical code.
• Do not expect automatic updates from commits alone or non-main branch pushes.
• Do not put secrets in context-pack content; .agent-context/current/ is tracked in git.

Layered Model

• Layer 0 (Evidence): cross-agent session reads with citations.
• Layer 1 (Context): context-pack index for deterministic repo onboarding.
• Layer 2 (Coordination, optional): explicit orchestration only when layers 0-1 are insufficient.

Recovery matrix:

• .agent-context/current/ -> git checkout <commit> -- .agent-context/current
• .agent-context/snapshots/ -> chorus context-pack rollback

Supported Agents

How It Compares

Visibility Without Orchestration

The default workflow is evidence-first: one agent reads another agent's session evidence and continues with a local decision, without a central control plane.

v0.7.0 Innovations

Relevance Introspection

Inspect and test the context-pack 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
chorus relevance --suggest --cwd .           # Suggest patterns for this project

Redaction Audit Trail

See exactly what was redacted and why in any chorus read output.

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

The JSON response includes a redactions array with pattern names and counts.

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

Agent-to-Agent Messaging

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

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

Messages are stored in .agent-chorus/messages/ and never leave your machine.

Current Boundaries (v0.7.0)

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

Architecture

Chorus sits between your agent and other agents' session logs. You talk to your agent - your agent talks to chorus.

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

Easter Egg

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

Roadmap

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

Update Notifications

Chorus checks for updates once per version.

• Privacy: Only contacts registry.npmjs.org.
• Fail-silent: If the check fails, it says nothing.
• Opt-out: Set CHORUS_SKIP_UPDATE_CHECK=1.

Choose Your Path

• I need full command syntax and JSON outputs: docs/CLI_REFERENCE.md
• I need context-pack internals and policy details: CONTEXT_PACK.md
• I am contributing or extending the codebase: docs/DEVELOPMENT.md
• I need protocol and schema contract details: PROTOCOL.md
• I need contribution process and PR expectations: CONTRIBUTING.md
• I need release-level changes and upgrade notes: RELEASE_NOTES.md

Contributions and issue reports are welcome.