gossipcat

agentic orchestration framework — agents that learn, adapt, and get better every round.

Install · First Run · Daily Use · Dashboard · Troubleshooting · Config · For AI Agents

What is Gossipcat?

Gossipcat is an MCP server that orchestrates multiple AI agents to review your code in parallel. Agents independently review, then cross-review each other's findings. Agreements are confirmed. Hallucinations are caught and penalized. Over time, each agent builds an accuracy profile — the system learns who to trust for what.

Why multi-agent?

Gossipcat is right for you if

• You want multiple AI models catching different classes of bugs
• You don't trust a single agent to catch everything
• You want agents to cross-check each other's findings before you act on them
• You want to know which agents are actually accurate vs. hallucinating
• You want agents that get better over time based on their track record

Features

Works with

Full support

Cursor Not yet

Windsurf Not yet

VS Code Not yet

Provider gateways

HTTP gateway ✅

Local models ✅

Any base_url ✅

How it works

  dispatch ──→ parallel review ──→ cross-review ──→ consensus
                                                       │
                                                 ┌─────┴─────┐
                                                 ▼           ▼
                                             signals    skill development
                                                 │           │
                                                 ▼           ▼
                                          dispatch weights   targeted prompts
                                          (who gets picked)  (agent improves)

Two types of agents

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.

Quickstart

Requirements: Node.js 22+ and Claude Code.

One-liner

npm install -g https://github.com/gossipcat-ai/gossipcat-ai/releases/latest/download/gossipcat.tgz && \
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",
      "args": ["mcp"]
    }
  }
}

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

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 ships from GitHub Releases, not the npm registry. The install URL above always points at the latest release. npm downloads the tarball directly, installs it globally, and drops a gossipcat binary on your PATH — no npm publish involved.

What the install ships

Alternative install paths

Pin to a specific version:

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

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

cd your-project
npm install --save-dev https://github.com/gossipcat-ai/gossipcat-ai/releases/latest/download/gossipcat.tgz

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"

Upgrading

Re-run the one-liner — npm will fetch the latest release tarball and replace the installed version:

npm install -g https://github.com/gossipcat-ai/gossipcat-ai/releases/latest/download/gossipcat.tgz

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.

3. API keys

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

Examples — registering gossipcat with each provider

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

4. Initialize your team

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

First Run — 5 Minutes

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.

Step 1 — Open Claude Code in any project

cd ~/your-project
claude

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

Step 2 — Bootstrap once

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.

Step 3 — Create your first team

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.

Step 4 — Run your first review

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

Step 5 — Watch the dashboard

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.

How to use it day-to-day

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

Recipe 1: Review a diff before committing

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.

Recipe 2: Catch security issues before shipping a feature

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.

Recipe 3: Understand a piece of code before changing it

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.

Recipe 4: Verify your own assumption

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.

Recipe 5: See which agents you can actually trust

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.

Recipe 6: Improve an agent that keeps making the same mistake

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.

Recipe 7: Set up a team for a brand-new project

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.

Things to avoid

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

Reading the dashboard

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.

Troubleshooting

"Dashboard says unauthorized / 401"

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

"Dashboard URL doesn't load at all"

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

"Boot says 'No gossip.agents.json found' and nothing happens"

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.

"Agents keep returning empty findings"

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.

"The same hallucinated finding keeps coming back"

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.

"I want to use my own model / provider"

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.

"Multiple Claude Code instances all want gossipcat"

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.

"How do I uninstall?"

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

Still stuck?

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.

Under the hood

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.

For AI Agents

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, run cross-review consensus, and record accuracy signals. You do not implement code directly — you coordinate.

Step 1 — Check what you have

gossip_status()

This tells you: which agents are available, their providers/models, relay status, dashboard URL, and suggested workflows. Always call this first in a new session.

Step 2 — Dispatch work

Single agent (auto-selected):

gossip_run(agent_id: "auto", task: "Review the auth module for security issues")

The system picks the best agent for the task based on past accuracy. For relay agents, this returns the result directly. For native agents (Claude Code subagents), it returns ⚠️ EXECUTE NOW instructions — follow them immediately in the same response.

Parallel (fan-out, no consensus):

gossip_dispatch(mode: "parallel", tasks: [
  { agent_id: "gemini-reviewer", task: "..." },
  { agent_id: "sonnet-reviewer", task: "..." }
])

Consensus (cross-review):

gossip_dispatch(mode: "consensus", tasks: [
  { agent_id: "gemini-reviewer", task: "..." },
  { agent_id: "sonnet-reviewer", task: "..." },
  { agent_id: "haiku-researcher", task: "..." }
])

Step 3 — Collect results

gossip_collect(task_ids: ["id1", "id2", "id3"], consensus: true)

With consensus: true, agents cross-review each other's findings. If native agents are in the round, gossip_collect returns ⚠️ EXECUTE NOW with prompts — dispatch those Agent() calls immediately, then relay each result via gossip_relay_cross_review.

Step 4 — Verify and record signals

After consensus, verify every UNVERIFIED finding against the actual code (grep/read the cited files). Then record signals:

gossip_signals(action: "record", signals: [{
  signal: "unique_confirmed",   // or "hallucination_caught", "agreement"
  agent_id: "gemini-reviewer",
  finding: "Race condition in task map at line 47",
  finding_id: "<consensus_id>:<agent_id>:f1"   // mandatory
}])

Signals update dispatch weights. Agents that hallucinate get penalized. Agents that catch real bugs get promoted.

Key rules

• Always follow ⚠️ EXECUTE NOW — dispatch those Agent() calls in the same response, do not wait.
• Never leave UNVERIFIED findings unexamined — read the code, confirm or deny, record the signal.
• finding_id is mandatory on every signal — format: <consensus_id>:<agent_id>:fN.
• Use gossip_progress after reconnect — if a consensus round was in flight, it re-surfaces the pending EXECUTE NOW prompts.

When to use consensus

Use gossip_dispatch(mode: "consensus") when the change touches: shared mutable state, auth/sessions, file persistence, or the core dispatch pipeline. Use gossip_run for single-agent research, exploration, or review tasks that don't need cross-validation.

MCP Tools

These tools are called by the internal LLM (the orchestrator — Claude Code with gossipcat MCP). You don't invoke them manually; the orchestrator selects and calls them based on your requests.

Dashboard internals

User-facing dashboard guide is in Reading the dashboard above. This section covers the build + tech stack.

Built with React + Vite + shadcn/ui. Source lives at packages/dashboard-v2/. The bundled assets ship in dist-dashboard/ and the relay serves them as static files at http://localhost:<dynamic-port>/dashboard/. Live updates push via WebSocket — every gossipcat tool call emits an event that connected dashboard tabs receive in real time.

To rebuild from source (contributors only):

npm run build:dashboard

Architecture

gossipcat/
  apps/
    cli/                  MCP server, native agent bridge, boot sequence
  packages/
    orchestrator/         Dispatch pipeline, consensus engine, memory, skills,
                          performance scoring, task graph, prompt assembly
    relay/                WebSocket relay server, dashboard REST/WS API
    dashboard-v2/         React + Vite frontend (Terminal Amber theme)
    client/               Lightweight WebSocket client for relay connections
    tools/                File/shell/git tool implementations for worker agents
    types/                Shared TypeScript types and message protocol

OpenClaw Integration

Gossipcat supports OpenClaw as a provider gateway. OpenClaw runs locally and exposes an OpenAI-compatible HTTP API — gossipcat talks to it like any other relay agent, with your stored gateway token and a separate quota slot so OpenClaw rate limits never bleed into your OpenAI agents.

Wiring an OpenClaw agent

Store your gateway token once (macOS):

security add-generic-password -s gossip-mesh -a openclaw -w <your-gateway-token>

On Linux:

secret-tool store --label "Gossip Mesh openclaw" service gossip-mesh provider openclaw
# (enter token when prompted)

Then add it to your team:

"Add an OpenClaw reviewer to my team"

Or directly via gossip_setup:

gossip_setup(mode: "merge", agents: [{
  id: "openclaw-agent",
  type: "custom",
  provider: "openclaw",
  custom_model: "openclaw/default",
  role: "reviewer",
  skills: ["code_review", "typescript"]
}])

The gateway runs at http://127.0.0.1:18789/v1 by default. Override with base_url if yours is on a different port. Available models: openclaw, openclaw/default, openclaw/main.

Once added, the agent participates in consensus rounds, accumulates accuracy signals, and gets skill files generated from its failure patterns — same as any other agent in the mesh.

Configuration

Config is searched in order: .gossip/config.json > gossip.agents.json > gossip.agents.yaml.

{
  "main_agent": {
    "provider": "google",
    "model": "gemini-2.5-pro"
  },
  "utility_model": {
    "provider": "native",
    "model": "haiku"
  },
  "consensus_judge": {
    "provider": "anthropic",
    "model": "claude-sonnet-4-6",
    "native": true
  },
  "agents": {
    "sonnet-reviewer": {
      "provider": "anthropic",
      "model": "claude-sonnet-4-6",
      "preset": "reviewer",
      "skills": ["code_review", "security_audit", "typescript"],
      "native": true
    }
  }
}

Host compatibility

Gossipcat auto-detects the host environment:

Roadmap

Contributing

Gossipcat is open source and early-stage — bug reports, feature ideas, and PRs are all welcome.

• Bugs / feature requests → open an issue. Or ask Claude Code directly: "File a gossipcat bug report about <...>" — the gossip_bug_feedback tool posts structured issues from your current session.
• Pull requests → fork, branch, PR against master. Run npm test before pushing. Commit messages follow conventional commits (fix:, feat:, chore:, docs:).
• Discussions → new ideas, design questions, "should this be a feature?" → GitHub Discussions.

See CLAUDE.md in the repo for the operational rules gossipcat's own agents follow during development — it's a useful read if you want to understand the signal pipeline and consensus workflow from the inside.

Cutting a release (maintainers)

Releases go to GitHub Releases via a two-stage script that respects branch protection — no direct commits to master.

# Stage 1 — open the version bump PR
./scripts/release.sh 0.1.2

# review + merge the PR via gh or web UI
gh pr merge <pr-number> --squash --delete-branch

# Stage 2 — build, tag, release (from master, after the PR is merged)
git checkout master && git pull
./scripts/release.sh   # no args

Stage 1 creates chore/release-X.Y.Z, bumps package.json, opens the PR, exits. Stage 2 reads the version from package.json, builds the MCP bundle + dashboard, packs the tarball, tags, pushes the tag, and creates the GitHub release with auto-generated notes from commits since the last tag.

Star History

License

MIT