How it works

The Mermaid diagram above shows the loop end-to-end. Here's the per-step definition:

Both types participate equally in consensus, cross-review, and skill development. Native subagents get skill files injected into their system prompts and can call gossip_remember for memory recall. Relay workers call the equivalent memory_query tool and get file_read + file_grep during cross-review so their verification parity matches natives.

Requirements: Node.js 22+ and Claude Code.

npm install -g gossipcat && claude mcp add gossipcat -s user -- gossipcat

Restart Claude Code. Then in any project, ask:

"Set up a gossipcat team for this project"

{
  "mcpServers": {
    "gossipcat": {
      "command": "gossipcat"
    }
  }
}

{
  "mcpServers": {
    "gossipcat": {
      "command": "npx",
      "args": ["gossipcat"]
    }
  }
}

Claude Code will call gossip_setup() to scaffold .gossip/config.json and your agent team. First-run bootstrap also writes the dispatch rules and tool catalog so Claude Code knows how to use gossipcat — no manual config needed.

Gossipcat is on npm and GitHub Releases — both carry the same bundle. npm install -g gossipcat pulls from the registry and is the shortest path; the GitHub release URL is useful when you want to pin to a specific tarball (see Alternative install paths below). Either way, npm drops a gossipcat binary on your PATH.

Pin to a specific npm version:

npm install -g gossipcat@0.4.14

Pin to a specific GitHub release tarball (version-locked, bypasses npm registry):

npm install -g https://github.com/gossipcat-ai/gossipcat-ai/releases/download/v0.4.14/gossipcat-0.4.14.tgz

Project-local install (each project gets its own gossipcat):

cd your-project
npm install --save-dev gossipcat

The postinstall writes .mcp.json to your project root. Open Claude Code in that directory and gossipcat connects automatically — no claude mcp add needed.

From source (contributors):

git clone https://github.com/gossipcat-ai/gossipcat-ai.git
cd gossipcat-ai
npm install
npm run build:mcp
claude mcp add gossipcat -s user -- node "$PWD/dist-mcp/mcp-server.js"

Re-run the install — npm will fetch the latest version and replace the installed binary:

npm install -g gossipcat@latest

Or in-session, ask Claude Code: "Check for gossipcat updates" — the gossip_update tool fetches the latest release notes and applies the upgrade with your confirmation.

Add env vars for the providers you want to use. Pass them with -e when registering, or set them in your shell environment.

Native only (zero API keys — everything runs through Claude Code):

claude mcp add gossipcat -s user -- gossipcat

Then in session ask for a team built from sonnet-reviewer / haiku-researcher / opus-implementer. Native agents dispatch through Agent() and relay back. Good zero-config starting point.

Anthropic API (direct, bypasses Claude Code):

claude mcp add gossipcat -s user \
  -e ANTHROPIC_API_KEY=sk-ant-... \
  -- gossipcat

Use this if you want relay agents running Claude models without going through the Claude Code subscription path — e.g. for parallelism beyond Claude Code's concurrency cap, or for running long background reviews while you keep working.

Google Gemini:

claude mcp add gossipcat -s user \
  -e GOOGLE_API_KEY=AIza... \
  -- gossipcat

Enables gemini-reviewer, gemini-tester, gemini-implementer on the relay. Watch the quota — gossipcat has a built-in 429 watcher that falls back to native agents when Gemini is cooling down.

OpenAI (and OpenAI-compatible gateways):

claude mcp add gossipcat -s user \
  -e OPENAI_API_KEY=sk-... \
  -- gossipcat

For Azure / Together / Groq / OpenRouter, add OPENAI_BASE_URL:

claude mcp add gossipcat -s user \
  -e OPENAI_API_KEY=your-key \
  -e OPENAI_BASE_URL=https://api.groq.com/openai/v1 \
  -- gossipcat

OpenClaw (local gateway):

# Start the OpenClaw daemon first (see openclaw docs), default port 18789
claude mcp add gossipcat -s user -- gossipcat

No env vars. Configure an agent with provider: "openclaw" in .gossip/config.json and gossipcat talks to the local gateway automatically. Override the port with base_url in the agent config if your daemon runs elsewhere.

Ollama (fully local, no API):

# Pull a model once
ollama pull llama3.1:8b
# Then register gossipcat
claude mcp add gossipcat -s user -- gossipcat

Configure the agent with provider: "local" and model: "llama3.1:8b" in .gossip/config.json. Good for airgapped dev, offline work, and burning-down-test-debt sessions where you don't want to spend API credits.

Mixed setup (common production shape — Gemini cheap reviewers + Anthropic heavy implementers):

claude mcp add gossipcat -s user \
  -e GOOGLE_API_KEY=AIza... \
  -e ANTHROPIC_API_KEY=sk-ant-... \
  -- gossipcat

Then set up a team with gemini-reviewer + haiku-researcher (native) + opus-implementer (native) + sonnet-reviewer (native). Gossipcat dispatches by category strength from the signal pipeline.

Keys are stored persistently and cross-platform:

• macOS — OS Keychain
• Linux — Secret Service (secret-tool)
• Windows / other — AES-256-GCM encrypted file

Start a Claude Code session in any project and ask Claude to set up your team:

"Set up a gossipcat team with a Gemini reviewer and a Sonnet implementer"

Claude Code calls gossip_setup() to create your .gossip/config.json and agent definitions. You choose the providers, models, and roles — gossipcat adapts to your setup.

Available presets: reviewer, implementer, tester, researcher, debugger, architect, security, designer, planner, devops, documenter

The fastest path from "just installed" to "first useful review". If you skip this section you'll probably get stuck on the same things everyone else gets stuck on.

cd ~/your-project
claude

Gossipcat is registered globally now, so it boots automatically. You'll see it in the MCP server list.

In Claude Code, just type:

Run gossip_status

This loads gossipcat's operating rules into the current session, creates .gossip/ in your project on first run, and prints the dashboard URL + auth key. Copy the key — you'll paste it into the dashboard once.

You'll see something like:

Status:
  Host: claude-code (native agents supported)
  Relay: running :49664
  Workers: 0
  Dashboard: http://localhost:49664/dashboard (key: c3208820f8f70605fd45fa90004a2a4b)
  Quota: google — OK

Open the dashboard URL in your browser, paste the key. You're now connected.

Tell Claude what you're building:

"Set up a gossipcat team for this project — it's a TypeScript Next.js app with a Postgres backend and Stripe payments."

Claude calls gossip_setup() and proposes a team. Typical proposal:

Proposed team:
  - sonnet-reviewer    (anthropic/claude-sonnet-4-6, native)   reviewer + security
  - gemini-reviewer    (google/gemini-2.5-pro, relay)          reviewer + types
  - haiku-researcher   (anthropic/claude-haiku-4-5, native)    researcher
  - opus-implementer   (anthropic/claude-opus-4-6, native)     implementer

Approve? (y/n)

Native agents (native: true) run through your existing Claude Code subscription — no API key needed. Relay agents need a key for their provider. If you don't have a Google API key, drop gemini-reviewer from the team for now and add it later.

Once you approve, gossipcat writes .gossip/config.json and the agents are live.

In a project where you've made some changes:

"Do a consensus review of my recent changes"

What happens (typical timing):

You get a report like:

Consensus round b81956b2-e0fa4ea4 — 3 agents

CONFIRMED (2):
  [critical] Race condition in tasks Map at server.ts:47 — sonnet + gemini
  [high]     Missing auth on WebSocket upgrade at server.ts:112 — sonnet + gemini

UNIQUE (1):
  [medium]   String concat in SQL query at queries.ts:88 — only sonnet caught this

DISPUTED (1):
  [low]      "Memory leak in timer" — haiku says yes, sonnet/gemini say no
             → verified, sonnet was right (not a leak — cleanup is in finally)

Final: 3 real bugs to fix, 1 false alarm caught by cross-review.

You only act on CONFIRMED + verified UNIQUE findings. The cross-review is the whole point — single-agent reviews ship hallucinated bugs as critical findings 5–10% of the time. Cross-review with verification drops that to under 1%.

The dashboard shows everything live: agents, scores, active tasks, consensus reports, signals. You can leave it open in a tab while you work — every gossipcat tool call pushes an update via WebSocket.

That's the basic loop. The rest of this README covers advanced workflows, troubleshooting, and how to interpret what you're seeing.

Concrete recipes for the most common workflows. Each one shows what to type, what you'll get back, and what to do with it.

Type:

"Review my staged changes"

What you'll get: A consensus report (1–3 minutes) with findings tagged CONFIRMED / UNIQUE / DISPUTED. Claude verifies UNVERIFIED findings against the code and tells you which are real.

What to do with it: Fix the CONFIRMED + verified-real findings. Ignore disputed-but-falsified findings. If a finding looks important but you disagree, ask Claude "verify finding f3 against the code yourself" — it'll re-check and either back you up or push back.

When NOT to use it: Tiny diffs (under 20 lines) — overhead exceeds value. Just eyeball them.

Type:

"Security audit the payment handler at lib/stripe/webhook.ts"

What you'll get: Each security-skilled agent reviews from a different angle (OWASP, input validation, auth, secrets). Findings get cross-validated. Real vulns surface; theoretical ones get caught and dropped.

What to do with it: Fix critical/high findings before merge. Bookmark medium/low findings for the next pass.

Tip: Be specific about the file or module. "Security audit the codebase" is too broad and produces noisy results. "Security audit lib/stripe/webhook.ts" produces actionable findings.

Type:

"Research how the WebSocket connection lifecycle works in this project before I touch it"

What you'll get: A research agent (haiku-researcher by default — fast and cheap) reads the code, traces call paths, and writes a summary. The summary is saved to that agent's cognitive memory so the next time you ask about the same area it remembers.

What to do with it: Use the summary to plan your change. The agent will reference it next time you ask anything related — no re-discovery cost.

Type:

"I think there's a race condition in the tasks Map at server.ts:47 — check if I'm right"

What you'll get: Two agents independently check the specific claim and either confirm or push back. Author self-review is optimistic — this isn't.

What to do with it: If both agree with you, fix it. If they push back, read their reasoning before defending your hypothesis. They might be right.

Type:

"Show me agent scores"

What you'll get: A table of agents sorted by reliability with per-category accuracy and dispatch weights. Categories include trust_boundaries, injection_vectors, concurrency, error_handling, data_integrity, type_safety, etc.

What to do with it: If gemini-reviewer is sitting at 30% accuracy on concurrency, you know not to trust its concurrency findings without cross-review. If sonnet-reviewer is at 90% on trust_boundaries, you can ship its findings on auth/session bugs with high confidence.

Type:

"gemini-reviewer keeps hallucinating about concurrency — develop a skill for it"

What you'll get: Gossipcat reads gemini-reviewer's failure data, generates a targeted skill file with concrete anti-patterns, and injects it into the agent's prompt for all future concurrency-related reviews. Effectiveness is measured statistically (z-test on post-bind signals) — it'll tell you if the skill is actually working after ~30 dispatches.

What to do with it: Nothing — it's automatic. Just keep using the agent. Over time, the failure rate drops.

Type:

"Set up a gossipcat team for a TypeScript Cloudflare Workers project with Drizzle ORM and KV storage"

What you'll get: A proposed team with archetypes matched to your stack. Worker projects need different reviewers than long-running Node services — gossipcat picks accordingly.

What to do with it: Review the proposal, drop agents you can't run (missing API keys), approve.

• Don't ask for "review the whole codebase" — too broad, agents will pick whatever they find first. Scope to a file, module, or diff.
• Don't approve findings without reading them — even after cross-review, ~5% of findings are genuinely wrong. The reasoning matters more than the verdict.
• Don't ignore the dashboard — when something feels weird (slow dispatch, repeated failures, suspicious findings), the dashboard usually shows you why before you have to ask.
• Don't run consensus mode for trivial questions — gossip_run with one agent is fine for "what does this function do?"-tier queries. Save consensus for changes that touch shared state, auth, persistence, or the dispatch pipeline itself.

The dashboard at http://localhost:<port>/dashboard is the visual layer over everything gossipcat knows. Open it once with the auth key from gossip_status, leave the tab open while you work. Updates push live via WebSocket.

Auth keys rotate every session. A fresh key is generated each time gossipcat boots. If the dashboard says "unauthorized", run gossip_status again to get the new key.

The auth key rotates every boot. Run gossip_status in Claude Code to get the current key, paste it into the dashboard login.

Check ~/.gossip/mcp.log (or <your-project>/.gossip/mcp.log) for the boot log. Look for the [gossipcat] 🌐 Dashboard: line — that's the actual port. If it's missing, the relay didn't start. Common causes:

• Conflicting .gossip/relay.pid from a crashed previous boot — delete it and restart Claude Code
• GOSSIPCAT_PORT set to a port already in use — unset the env var or pick a free port

This was a critical bug in v0.1.0 — fixed in v0.1.1. Upgrade with the install one-liner above. v0.1.1+ boots in degraded mode (dashboard + relay only) so you can run gossip_setup from inside Claude Code.

Usually a model or quota problem. Check gossip_status — it shows Quota: google — OK (or cooling down) per provider. If you're rate-limited, gossipcat will fall back to native agents automatically, but fallback agents may not be in your team. Either wait for the cooldown or add native agents to your team.

Record a hallucination_caught signal: ask Claude "record a hallucination_caught signal for finding f3 in the last consensus round — it claimed X but the code shows Y". After 3 such signals, the offending agent's score drops in that category and the orchestrator stops asking it questions in that area.

Edit .gossip/config.json directly. Any OpenAI-compatible endpoint works via provider: "openai" + base_url. Local models work via Ollama (provider: "local"). See the Configuration section.

The strict <agent_finding> parser drops tags whose type isn't one of finding | suggestion | insight (see invariant #8 in docs/HANDBOOK.md). When that happens, the gossip_signals receipt surfaces the drop count and a finding_dropped_format pipeline signal is emitted. Check the consensus round's droppedFindingsByType field on the dashboard — it names the offending type. If you see <agent_finding> instead of raw <agent_finding>, a transport layer is entity-encoding the output; pass agent output verbatim to gossip_relay.

Already supported as of v0.1.1 — each instance gets its own dynamic port. If you want a stable port for one specific instance (e.g. for browser bookmarks), set GOSSIPCAT_PORT=24420 for that one project's environment.

npm uninstall -g gossipcat
claude mcp remove gossipcat -s user
rm -rf ~/.gossip  # if you want to wipe global memory + signals
rm -rf <project>/.gossip  # if you want to wipe per-project state

File an issue at https://github.com/gossipcat-ai/gossipcat-ai/issues. Include the contents of .gossip/mcp.log (last 100 lines) and the output of gossip_status. Or ask Claude in-session: "file a gossipcat bug report about <...>" — the gossip_bug_feedback tool packages it up automatically.

Claude Code translates your natural-language requests into gossipcat MCP tool calls automatically — you don't need to type these — but if you want fine-grained control they're documented here:

gossip_run(agent_id: "auto", task: "...")        → single-agent task
gossip_dispatch(mode: "consensus", tasks: [...]) → multi-agent review with cross-review
gossip_collect(consensus: true)                  → wait for results, run consensus
gossip_signals(action: "record", signals: [...]) → record accuracy after verification
gossip_scores()                                  → view agent performance
gossip_skills(action: "develop", ...)            → improve a struggling agent
gossip_status()                                  → system status + dashboard URL
gossip_setup(...)                                → create or update your team

The dispatch rules at .claude/rules/gossipcat.md (auto-generated on first boot) teach Claude Code when to pick which mode based on what your change touches. You can edit these rules to bias the dispatch.

Currently supported orchestrator: Claude Code only. Cursor, Windsurf, and VS Code agents do not yet have native agent support and cannot run consensus cross-review. If you are reading this as a Claude Code instance with the gossipcat MCP server connected, this guide applies to you.

If you are a Claude Code instance reading this to understand how to use gossipcat, here is the complete operational guide.

You are the orchestrator. Gossipcat gives you tools to dispatch work to a team of specialized agents, collect their results,