gossipcat

Why

A single AI reviewer will, with total confidence, report bugs that aren't there. You read the finding, you go look, you waste twenty minutes — the code was fine. There's no second opinion and no track record, so you can't tell a real catch from a hallucination until you've already spent the time.

Gossipcat runs several agents in parallel, has them cross-check each other's findings against your actual file:line, and only surfaces what survives. When an agent invents a finding, a peer catches it and the agent's accuracy score drops — so over time the system routes each kind of work to whoever is actually reliable at it. Cross-review catches hallucinations a solo reviewer would have shipped to you; that delta is the whole point.

It runs as an MCP server inside Claude Code and Cursor, ships a live operator dashboard, and lets you drive the orchestrator straight from the browser.

The consensus tags you'll see (this is your whole job — read these, ignore the rest):

Related MCP server: CodePeel MCP Server

How it works

flowchart LR
    A([agent review]) -->|cites file:line| B([peer cross-review])
    B -->|verifies against code| C{verdict}
    C -->|confirmed| D[reward signal]
    C -->|hallucination| E[penalty signal]
    D --> F[competency score]
    E --> F
    F -->|steer dispatch| G([next agent pick])
    E -->|≥3 in category| H[auto-generate skill]
    H -->|inject into prompt| A
    G --> A
    style A fill:#0ea5e9,stroke:#0369a1,color:#fff
    style H fill:#f59e0b,stroke:#b45309,color:#fff
    style D fill:#10b981,stroke:#047857,color:#fff
    style E fill:#ef4444,stroke:#b91c1c,color:#fff

The reward signal is grounded in your source code, not a judge model's opinion. Every finding cites a real file:line; peers verify the citation mechanically. That ground truth is what makes the loop trustworthy enough to automate. The "policy update" is a markdown file under .gossip/agents/<id>/skills/ — no weights touched, no fine-tuning, no RLHF. (It's effectively in-context reinforcement learning at the prompt layer; the framing is deliberate, the mechanism is exactly the table above.)

A small synthesis model (consensus_judge, configurable) merges and deduplicates the cross-review results — it does not grade quality. Verdicts come from citation checks against your code, never from one model judging another.

Native vs Relay agents

Every agent has a type (where it runs) and a preset (what skills it starts with — reviewer, implementer, researcher, …). You mix them freely; a team of native reviewers and relay researchers is perfectly normal.

Both participate equally in consensus and skill development. Relay workers get file_read + file_grep during cross-review so their verification parity matches natives.

How Gossipcat compares

The difference: gossipcat verifies findings against actual file:line citations in your codebase. That ground truth is what makes the reward signal trustworthy enough to automate.

Quickstart

Requirements: Node.js 22+ and either host below. Claude Code and Cursor are co-equal first-class hosts — pick the one you use; gossipcat auto-detects it and runs native agents either way.

Fastest path (skills CLI): one command installs the server and walks you through setup:

npx skills add gossipcat-ai/gossipcat-ai

This drops an installer skill into .claude/skills/; your agent runs the install and then hands off to gossip_status() for the live rules. Prefer it over the manual steps below if you use the skills CLI. The manual npm install is documented next.

Install the package once:

npm install -g gossipcat

Register the MCP server:

claude mcp add gossipcat -s user -- gossipcat

Restart Claude Code. Native agents dispatch via Agent().

Add to .cursor/mcp.json:

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

Reload Cursor. Native agents dispatch via Task().

Then in any project, ask the orchestrator: "Set up a gossipcat team for this project."

Add to ~/.claude/mcp_settings.json (Claude Code) or project-local .mcp.json:

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

# Pin to a version
npm install -g gossipcat@0.6.11

# Pin to a GitHub release tarball (bypasses the npm registry)
npm install -g https://github.com/gossipcat-ai/gossipcat-ai/releases/download/v0.6.11/gossipcat-0.6.11.tgz

# Project-local (postinstall writes .mcp.json — open the IDE there, no `mcp add` needed)
cd your-project && npm install --save-dev gossipcat

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

The install ships the MCP server binary, the prebuilt dashboard (dist-dashboard/, launches on a dynamic port), bundled skill templates + rules + project archetypes, and a postinstall wizard that writes .mcp.json with correct absolute paths.

Upgrade: npm install -g gossipcat@latest, or ask in-session "check for gossipcat updates" (the gossip_update tool applies it with your confirmation).

API keys (relay agents only)

Native agents need no key. For relay agents, pass provider keys with -e at registration or set them in your shell:

Keys are stored persistently and cross-platform — macOS Keychain, Linux Secret Service (secret-tool), or an AES-256-GCM encrypted file on Windows. Mixing providers is the common production shape: cheap Gemini reviewers + native heavy implementers, dispatched by category strength.

First Run

The fastest path from "just installed" to "first useful review."

1 · Open your IDE in a project and bootstrap once. In Claude Code or Cursor, run:

Run gossip_status

This loads gossipcat's operating rules into the session, creates .gossip/ on first run, and prints the dashboard URL + auth key:

Status:
  Host: claude-code (native agents supported)   ← which IDE you're in
  Relay: running :49664                          ← background server for agents + dashboard
  Workers: 0                                     ← agents busy right now (rises during a round)
  Dashboard: http://localhost:49664/dashboard (key: c3208820…)  ← open it, paste the key
  Quota: google — OK                             ← provider rate-limit status (falls back to native on cooldown)

Open the dashboard URL, paste the key (it rotates each boot — re-run gossip_status for a fresh one).

2 · Create your first team. Tell the orchestrator what you're building:

"Set up a gossipcat team for this project — a TypeScript Next.js app with Postgres and Stripe."

It proposes a team matched to your stack. Smallest working team: sonnet-reviewer + haiku-researcher — both native, zero API keys. Drop any relay agent whose provider key you don't have; add it later. Native agents (native: true) run on your subscription. Approve, and .gossip/config.json is written.

3 · Run your first review in a project with some changes:

"Do a consensus review of my recent changes"

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: not a leak, cleanup is in finally. False alarm caught.

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

Act on CONFIRMED + verified UNIQUE. The false alarm that cross-review caught is the bug a single reviewer would have shipped to you.

How to use it day-to-day

Each recipe: what to type, what you get, what to do with it.

Review a diff before committing → "Review my staged changes." Consensus report in 1–3 min; fix CONFIRMED + verified findings. For diffs under ~20 lines, skip consensus — ask gossip_run for a single fast agent (~10s) and save the round.

Catch security issues → "Security audit lib/stripe/webhook.ts." Each security agent reviews from a different angle (OWASP, validation, auth, secrets); real vulns survive cross-review, theoretical ones get dropped. Be specific about the file — "audit the codebase" is too broad.

Understand code before changing it → "Research how the WebSocket lifecycle works before I touch it." A research agent traces call paths and writes a summary into its cognitive memory, so next time it remembers — no re-discovery cost.

Verify your own assumption → "I think there's a race in the tasks Map at server.ts:47 — check if I'm right." Two agents independently confirm or push back. Author self-review is optimistic; this isn't.

See which agents you can trust → "Show me agent scores." Per-category accuracy + dispatch weights. If gemini-reviewer sits at 30% on concurrency, don't trust its concurrency findings solo.

Improve a struggling agent → "gemini-reviewer keeps hallucinating about concurrency — develop a skill for it." Gossipcat generates a targeted skill from its failure data and measures whether it works (z-test on post-bind signals). Then it's automatic.

Avoid: "review the whole codebase" (too broad — scope to a file/module/diff); approving findings without reading the reasoning; running consensus for trivial questions (use a single gossip_run agent).

Reading the dashboard

Open it once with the key from gossip_status; leave the tab open while you work. Every tool call pushes a live WebSocket update.

Drive it from your browser

The dashboard's Chat page is a live, two-way bridge into the running orchestrator — type from the browser and your message lands in the active session; the orchestrator's dispatches, findings, and replies mirror back into the same thread in real time.

The gossip_ask answer boundary is fail-closed: only known options are accepted and "Other" free-text is sanitized before it reaches the orchestrator, so a dashboard answer can't smuggle instructions into the session. Launch with the gossipcat code wrapper (or ask the orchestrator to enable channel mode), then open the Chat tab.

Host compatibility

Gossipcat auto-detects the host and adapts dispatch + the rules file it writes.

On Claude Code and Cursor, native agents run with no API key and participate fully in consensus. Other MCP hosts can still run relay agents.

Troubleshooting

Dashboard says unauthorized / 401 — the key rotates every boot. Run gossip_status for the current key.

Dashboard URL won't load — check .gossip/mcp.log for the 🌐 Dashboard: line (the real port). If missing, the relay didn't start: delete a stale .gossip/relay.pid from a crashed boot and restart, or free up GOSSIPCAT_PORT if it's taken.

Agents return empty findings — usually quota. gossip_status shows Quota: <provider> — OK / cooling down. On a rate limit gossipcat falls back to native agents (add some to your team if you have none).

The same hallucinated finding keeps coming back — record it: "record a hallucination_caught signal for finding f3 — it claimed X but the code shows Y." After 3, the agent's score drops in that category and dispatch stops routing it there.

An agent produced output but the consensus report is empty — the strict <agent_finding> parser drops tags whose type isn't finding | suggestion | insight (invariant #8 in docs/HANDBOOK.md); the gossip_signals receipt surfaces the drop and a finding_dropped_format signal. If you see <agent_finding> instead of raw tags, a transport layer is entity-encoding output — pass agent output verbatim to gossip_relay.

Multiple IDE instances — each gets its own dynamic port. For a stable port on one project, set GOSSIPCAT_PORT=24420 in that environment.

Uninstall — npm uninstall -g gossipcat && claude mcp remove gossipcat -s user; rm -rf ~/.gossip (global state) or <project>/.gossip (per-project).

Still stuck? Open an issue with the last 100 lines of .gossip/mcp.log + gossip_status output, or ask in-session "file a gossipcat bug report about …" (gossip_bug_feedback packages it).

Configuration

Most of .gossip/config.json is auto-generated by gossip_setup() — hand-edit only to change providers/models/endpoints. First-run defaults work for most projects. Config is searched: .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
    }
  }
}

OpenClaw runs locally and exposes an OpenAI-compatible API; gossipcat talks to it like any relay agent, with a separate quota slot so its rate limits don't bleed into your OpenAI agents. Store the gateway token once (macOS: security add-generic-password -s gossip-mesh -a openclaw -w <token>; Linux: secret-tool store --label "Gossip Mesh openclaw" service gossip-mesh provider openclaw), then add an agent with provider: "openclaw" (default base_url http://127.0.0.1:18789/v1, models openclaw / openclaw/default / openclaw/main). It joins consensus and earns skills like any other agent.

MCP Tools

The orchestrator (Claude Code / Cursor) selects and calls these from your natural-language requests — you don't invoke them manually.

Architecture

gossipcat/
  apps/cli/               MCP server, host-aware 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 + shadcn/ui frontend (warm-cream theme — see DESIGN.md)
    client/               Lightweight WebSocket client for relay connections
    tools/                File / shell / git tool implementations for worker agents
    types/                Shared TypeScript types and message protocol

The dashboard ships prebuilt in dist-dashboard/ and the relay serves it as static files; rebuild from source with npm run build:dashboard.

Reading this as a Claude Code or Cursor instance? Call gossip_status() — it boots your full operating rules. The detailed orchestrator workflow (dispatch rules, consensus protocol, signal pipeline) lives in CLAUDE.md and .claude/rules/gossipcat.md.

Roadmap

Shipped work lives in CHANGELOG.md and GitHub Releases. What's next:

Contributing

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

• Bugs / features → open an issue, or ask Claude Code "file a gossipcat bug report about …" (gossip_bug_feedback posts a structured issue).

• Pull requests → fork, branch, PR against master. Run npm test first. Conventional commits (fix:, feat:, chore:, docs:). Release process and contributor setup are in CONTRIBUTING.md.

• Discussions → GitHub Discussions.

CLAUDE.md documents the operational rules gossipcat's own agents follow during development — a useful read for understanding the signal pipeline and consensus workflow from the inside.

Star History

License

MIT