Co-VibeDocs

Engineering

Claude Code Integration#

Co-Vibe supports Claude Code in two ways:

  1. Claude Code can call Co-Vibe MCP tools through the project .mcp.json.
  2. Claude Code hooks submit verified model and token usage through covibe_ingest_agent_telemetry.

Setup#

Start Co-Vibe:

bash
npm run dev

Create an MCP token in the UI, install the companion with the command shown in Agent Setup, then export the token before opening Claude Code. Hosted builds serve the companion package from /downloads/co-vibe.tgz, so the default command looks like:

bash
npm install --save-dev http://localhost:3000/downloads/co-vibe.tgz \
  && printf "Co-Vibe MCP token: " \
  && read -rs COVIBE_MCP_TOKEN \
  && printf "\n" \
  && export COVIBE_MCP_TOKEN \
  && npm exec -- covibe-local setup --base-url http://localhost:3000 \
  && npm exec -- covibe-local doctor --base-url http://localhost:3000 \
  && claude

For hosted Co-Vibe, keep the same local commands but use the hosted tenant URL in the install command, setup base URL, and doctor base URL. Developers do not need to run the cloud app locally, but they still need the installed companion package in each tracked repo for hooks, transcript usage, git-aware snapshots, and .covibe/telemetry inbox flushes for Codex/Cursor wrapper exports. Use only the Co-Vibe origin for --base-url, not credentials, /callback, query strings, hashes, or another path. Setup reads COVIBE_MCP_TOKEN for readiness checks and the first snapshot; the token is not written to repo config. The copied block is an && chain so doctor and Claude do not open when install or setup fails.

The token prompt is optional: when no --token, COVIBE_MCP_TOKEN, or stored credentials exist, covibe-local setup runs a browser device flow, the developer approves the request once in the console, and per-agent typed tokens land in ~/.covibe/credentials.json (mode 0600). The written .mcp.json carries a non-secret COVIBE_AGENT=claude-code marker so the stdio bridge can look up the right token; COVIBE_MCP_TOKEN keeps precedence for existing setups. See device-setup.md for the full flow.

One setup run integrates every supported agent: it writes the Claude Code files below, a Codex ~/.codex/config.toml MCP entry when Codex is installed (see codex-integration.md), Cursor .cursor/mcp.json plus .cursor/hooks.json files when Cursor is installed (see cursor-integration.md), and a marker-delimited overlap-protocol snippet in the repo's AGENTS.md, in CLAUDE.md (created if missing when claude-code is configured), and in .cursor/rules/covibe.mdc when cursor is configured (skip with --no-agent-rules, reapply with covibe-local agent-rules [--agents ...]). Setup prints one INFO line per file it writes, reports already up-to-date files, and supports --dry-run to print the planned writes without touching anything (a token is not required for a dry run).

Claude Code reads .mcp.json and exposes the Co-Vibe tools from the covibe server. If Claude asks whether to trust the project MCP server, approve it for this repository.

Automatic Usage Capture#

The project .claude/settings.json registers scripts/claude-code-covibe-hook.ts for SessionStart, Stop, and SessionEnd.

The hook:

  • starts a Co-Vibe claude-code session when Claude Code starts
  • submits bounded git/repo snapshots without file contents
  • includes dirty files, unpushed commit files, and deterministic diff hashes
  • receives warning responses when another session has overlapping dirty or unpushed files, and surfaces them to the agent: on SessionStart and Stop the hook emits the conflict (owner, branch, files, what to do) as hookSpecificOutput.additionalContext — covering both a teammate's session and the same developer's other agent session
  • warns mid-session: a PostToolUse hook (matcher Edit|Write|MultiEdit|NotebookEdit) checks each edited file against the conflict map cached from the latest snapshot warning and injects a one-time per-file warning as additionalContext — no server roundtrip per edit
  • reads only new usage-bearing records from Claude's transcript JSONL
  • sends model, token, cache, and cost counters to covibe_ingest_agent_telemetry
  • ends the Co-Vibe session when Claude Code exits

The hook does not submit prompt text, model responses, code snippets, or full transcript records. It builds a compact claude_sdk_result payload with usage counters only. Co-Vibe still parses and prices the payload server-side. Repos excluded with covibe-local exclude are never logged: the hook exits before any tool call or state write (see device-setup.md). For other repos, hook activity registers the repo in ~/.covibe/repos.json so the machine-level watch service picks it up automatically — no per-repo registration command.

Environment#

Required (one of):

  • COVIBE_MCP_TOKEN (legacy shared token; takes precedence when set)
  • a claude-code token in ~/.covibe/credentials.json written by the device-flow setup (see device-setup.md)

Optional:

  • COVIBE_BASE_URL, default http://localhost:3000
  • COVIBE_AGENT, the credentials-file lookup key written into .mcp.json
  • COVIBE_CREDENTIALS_PATH, default ~/.covibe/credentials.json
  • COVIBE_CLAUDE_AGENT_NAME, default Claude Code
  • COVIBE_BRANCH, when a wrapper wants to pin the branch label
  • COVIBE_CLAUDE_HOOK_STATE, default data/claude-code-hook-state.json

If no token can be resolved, the hook exits successfully without logging so Claude Code is never blocked by Co-Vibe setup.

Verification#

Run:

bash
npm run claude:hook < sample-hook-input.json
npx vitest run tests/unit/claude-code-hook.test.ts tests/unit/verified-telemetry.test.ts
View as .md