# Co-Vibe

> Co-Vibe is the coordination layer for engineering teams using multiple AI coding agents. It shows what Claude Code, Codex, Cursor, and Paxel are doing across a repo, detects overlap and conflicts before they become commits, captures trusted (deterministic, not self-reported) agent metrics, and surfaces the useful parts in developer and team profiles — coordination, not surveillance.

Bottom line: agents and developers call eight compact MCP tools to declare work, get blocked on real duplicate-work overlap (100% recall, >90% precision), and emit verified usage/session telemetry. A local companion (open-source trust boundary) runs hooks, redaction, and the official Paxel profiler on the developer's own machine. Self-hostable; multi-tenant ready.

## Capabilities

- Deterministic agent capture: Claude Code via native hooks + transcript usage readers; Codex/Cursor via MCP sessions + counter-only telemetry inbox; every signal stored with provenance (hook, transcript, MCP, proxy, provider report, local snapshot).
- Exact change tracking: file paths, staged/worktree diff hashes, branch, commit SHA captured without storing code; same-developer multi-agent overlap detection; warnings returned through MCP so agents see them, not just the UI.
- Duplicate-work gate: a task cannot start over a real overlap without a human confirmation reason; the agent receives structured feedback and the next action.
- Paxel integration: runs the official ycombinator/paxel Docker image locally from a developer profile and stores the report URL/token (no clone).
- Developer and team profiles: per-agent usage, session history, stale sessions, conflicts, productivity signals, spend; filter by repo/branch/workspace/agent/time.

## Quickstart

- Run locally: `npm install && docker compose up -d postgres && npm run setup && npm run dev`, then open the printed UI URL. App state uses PostgreSQL locally and in production; the local companion does not run product storage.
- Connect an agent: Settings → Agent setup copies the companion install + `covibe-local setup` command; Claude Code, Codex, and Cursor are supported over MCP.
- Health: `curl http://localhost:3000/api/health`. Quality gate: `npm run readiness`.

## Docs

Each page below is served as raw markdown — append nothing, the links already point at the machine-readable `.md` surface.

- [README](/docs/overview/readme.md) — install, run, MCP call shape, auth, quality gates
- [Product problem](/docs/product/problem.md) — what Co-Vibe is for
- [MCP contract](/docs/engineering/mcp-contract.md) — the eight tools and hard rules
- [Overlap precision](/docs/engineering/overlap-precision.md) — recall/precision method
- [Verified agent telemetry](/docs/engineering/verified-agent-telemetry.md) — Claude/Codex/Cursor capture + provenance
- [Paxel integration](/docs/engineering/paxel-integration.md) — running the official profiler locally
- [Architecture](/docs/engineering/architecture.md) and [data model](/docs/engineering/data-model.md)

## MCP tools

covibe_task, covibe_workstream, covibe_session, covibe_note, covibe_team, covibe_coordination, covibe_warning, covibe_ingest_agent_telemetry. HTTP clients POST `{ "tool": "covibe_task", "input": { "operation": "check", ... } }` to `/api/mcp`.