Co-VibeDocs

Overview

Co-Vibe#

Co-Vibe helps small AI-assisted engineering teams see what people and agents are working on before the work becomes a commit.

Install Companion In A Repo#

When a developer connects an agent, open Settings → Agent setup and copy the local companion command. Local and hosted builds default to the served tarball:

bash
npm install --save-dev http://localhost:3000/downloads/co-vibe.tgz \
  && npm exec -- covibe-local setup --base-url http://localhost:3000 \
  && npm exec -- covibe-local doctor --base-url http://localhost:3000

Setup also installs a machine-level background service by default (launchd LaunchAgent on macOS, systemd user unit on Linux; skip with --no-service), so continuous sync survives closing the terminal. Settings → Agent setup still shows the foreground command separately:

bash
npm exec -- covibe-local watch --base-url http://localhost:3000

Hosted customers use the hosted origin in the copied setup and runtime commands; external repos install the companion package and run covibe-local. The local companion does not run a database. It writes ignored local config plus .covibe/telemetry inbox files, then sends snapshots, heartbeats, Codex split usage counters, Cursor usage counters, and provider usage counters to the Co-Vibe server. One setup run integrates Claude Code, Codex, and Cursor: it writes .mcp.json plus .claude/settings.json hooks for Claude Code; when Codex is installed, a ~/.codex/config.toml [mcp_servers.covibe] entry whose env_vars = ["COVIBE_MCP_TOKEN"] passes the token from your shell at spawn time — no raw token on disk (see docs/engineering/codex-integration.md); and when Cursor is installed, a repo-local .cursor/mcp.json server entry that references the token as ${env:COVIBE_MCP_TOKEN} plus .cursor/hooks.json lifecycle hooks (see docs/engineering/cursor-integration.md). Setup also installs a marker-delimited overlap-protocol snippet into the repo's AGENTS.md, CLAUDE.md, and .cursor/rules/covibe.mdc per configured agent (skip with --no-agent-rules, reapply with npm exec -- covibe-local agent-rules). Each written file gets one INFO line; setup --dry-run prints the planned writes without changing anything. Use the Co-Vibe origin for --base-url, for example https://co-vibe.example.com, not credentials, /callback, a query string, a hash, or another path. The companion CLI accepts flags before or after the command plus --flag=value syntax; unknown flags and extra positional arguments fail before local config is written, so mistyped setup commands cannot silently point agents at the wrong server. Run npm exec -- covibe-local --help for the command list, npm exec -- covibe-mcp --help for the stdio bridge env/tools, and npm exec -- covibe-claude-hook --help for the installed Claude Code hook — none of them need a token. Hosted builds serve the package at /downloads/co-vibe.tgz, so Agent Setup can show a customer-ready install command without npm publication. Set COVIBE_COMPANION_INSTALL_COMMAND only to override that with a public npm or internal-registry command. Setup needs no token paste: it runs a one-time browser device approval and the shell never sees a raw token. The copied block is chained so setup and doctor do not run when an earlier step fails. Every repo you work in is logged to Co-Vibe unless you exclude it with npm exec -- covibe-local exclude (or flip the machine to opt-in with covibe-local exclude --new-repos) — setup asks this once up-front on a TTY ("Sync git activity from new repos on this machine to <server>? [Y/n]") and prints exactly this disclosure. There is no per-repo registration command: agent activity (hooks, MCP bridge, companion commands) registers the repo in ~/.covibe/repos.json, scoped per server; under the opt-in policy a new repo is pending and nothing leaves the machine until you run covibe-local include inside it. Exclusion is sticky: excluding deletes the repo's registry entries and session activity cannot re-register it — only covibe-local include brings it back (see docs/engineering/device-setup.md). The companion writes ignored .mcp.json, .claude/, .covibe/, and .cursor/ local files without storing the raw token, then doctor rechecks Node, git, token, token-safe MCP config, config cwd, Claude hooks, Codex wiring (INFO-skipped when Codex is absent), Cursor wiring (INFO-skipped when Cursor is absent), and hosted server reachability. The watch loop is machine-level: each tick it syncs snapshots, telemetry inbox flushes, local Codex and Cursor usage, and session heartbeats for every registered, included repo — Paxel never runs in the background (see Paxel Profiles). The setup-installed service runs this loop unattended and re-reads rotated credentials from ~/.covibe/credentials.json at runtime, so token rotation needs no reinstall (setup from a temporary npx cache refuses the service install and prints the fix); the watch command above runs the same loop in the foreground, and --repo <path> restricts it to a single repo for debugging. The service also silently self-updates npm-managed installs when the server ships a newer companion (disable with setup --no-auto-update or covibe-local update --off; git checkouts get a git pull hint — see docs/engineering/device-setup.md). Codex sync uses the local Codex thread database only to scope work to this repo, reads numeric response.completed counters from local Codex logs, stores last-seen response ids in ignored .covibe/codex-usage-state.json, and skips Codex usage when split logs are unavailable. Cursor sync reads per-message token counts and per-model cost counters from Cursor's local state database, scoped to this repo, with dedupe state in ignored .covibe/cursor-usage-state.json. Neither sync reads transcripts, prompts, or responses, and no Co-Vibe storage runs locally. Run npm exec -- covibe-local snapshot --base-url http://localhost:3000 for a one-off repo-state resync. The device approval stores per-agent typed tokens in ~/.covibe/credentials.json (mode 0600); a legacy exported COVIBE_MCP_TOKEN keeps precedence for existing setups — see docs/engineering/device-setup.md.

Run Locally#

bash
npm install
docker compose up -d postgres
export COVIBE_DATABASE_BACKEND=postgres
export DATABASE_URL=postgres://covibe_app:covibe_app@127.0.0.1:5432/covibe
npm run setup
npm run dev

npm run setup initializes the PostgreSQL schema and runs npm run doctor. The dev script prints the UI URL, MCP JSON endpoint, auth mode, and a WorkOS callback warning if the localhost callback port does not match the dev server. If your shell has complete WorkOS env but you want seeded local developers, run COVIBE_AUTH_MODE=local-dev npm run dev.

Health check:

bash
curl http://localhost:3000/api/health

npm run doctor can be rerun any time. It checks the Node version, lockfile policy, schema table and column health, MCP tool readiness, token-safe MCP config, and whether the running server answers /api/health.

Before a WorkOS-backed deploy, run:

bash
npm run doctor:production

That command fails if WorkOS env is incomplete, production auth is forced to local-dev, the cookie password is weak, or the redirect URI is malformed. For co-vibe.dev, use Cloud SQL for PostgreSQL. Initialize the database with npm run db:postgres:init and verify tenant/workspace isolation with npm run smoke:postgres, then verify the app repository path with npm run smoke:postgres:runtime.

First Human Test#

Open the UI, sign in or use local-dev test identity setup, create an MCP token, run the local companion setup, plan/start/complete work through MCP, run the duplicate-work test, audit parallel work, generate a weekly summary, and confirm Workstreams, Coordination, Performance, Activity, and token inventory all update. The full checklist lives in docs/ops/build-loop-tests.md.

Agent Call Shape#

For MCP clients that support stdio servers, run npm exec -- covibe-mcp through config like this:

json
{
  "mcpServers": {
    "covibe": {
      "command": "npm",
      "args": ["exec", "--", "covibe-mcp"],
      "cwd": "/path/to/customer/repo",
      "env": {
        "COVIBE_BASE_URL": "http://localhost:3000",
        "COVIBE_AGENT": "claude-code"
      }
    }
  }
}

The non-secret COVIBE_AGENT marker tells the bridge which typed token to read from ~/.covibe/credentials.json (written by device-flow setup). Never paste a raw token into a config file; a legacy shell COVIBE_MCP_TOKEN keeps precedence.

Direct HTTP clients post { "tool": "covibe_task", "input": { ... } } to /api/mcp. Use scope, action (create|modify|remove|fix|audit), and component (server, client, db, ui, etc.) on task checks to improve duplicate-work precision. See docs/engineering/mcp-contract.md and docs/engineering/overlap-precision.md.

Every MCP call writes usage data. Warnings and blocks are returned to the agent and saved as structured feedback events. Run npm run db:embed after upgrading to backfill overlap embeddings for existing work.

Agents call eight compact MCP tools: covibe_task, covibe_workstream, covibe_session, covibe_note, covibe_team, covibe_coordination, covibe_warning, and covibe_ingest_agent_telemetry.

Claude Code uses .mcp.json plus .claude/settings.json hooks from the local companion. Copy the install block from Settings → Agent setup, then run:

bash
npm install --save-dev http://localhost:3000/downloads/co-vibe.tgz \
  && npm exec -- covibe-local setup --base-url http://localhost:3000 \
  && npm exec -- covibe-local doctor --base-url http://localhost:3000 \
  && claude

The hook logs counters, model names, cache counters, cost estimate, and a payload hash. It does not send prompt text, model responses, or full transcripts. See docs/engineering/claude-code-integration.md; Codex CLI integration is documented in docs/engineering/codex-integration.md, and Cursor IDE integration (.cursor/mcp.json plus .cursor/hooks.json lifecycle hooks and local usage capture) in docs/engineering/cursor-integration.md.

Use covibe_team operation: "state" before choosing work and operation: "feedback" to retrieve recent warnings or blocks. During long runs, use covibe_session for start/heartbeat/end, covibe_note for blockers and decisions, and covibe_team operation: "audit_parallel_work" to catch duplicate active or recently completed work.

The console has six dedicated routes: /workstreams, /performance, /coordination, /analytics, /activity, and /settings. Developer profiles open under /performance/developers/<handle>, and / redirects to Workstreams. Weekly summaries store rendered text plus structured JSON for planned work, active work, completed work, blockers, decisions, warnings, audits, and sessions.

Paxel Profiles#

Open your own profile (Performance → your row) and click Run Paxel to profile how you build with AI. Co-Vibe records the request, then the local companion runs the official ycombinator/paxel Docker image on your machine (your Claude, Codex, and Cursor transcripts never leave it) and returns the report link:

bash
npm exec -- covibe-local paxel --base-url http://localhost:3000
# --all-repos, --project NAME, --since DATE, --no-repo, --no-sentry,
# --timeout-ms MS, --dry-run (previews the docker command; needs no token)

Requires Docker running locally. Paxel is strictly user-triggered — the background watch loop never runs it. A UI-requested run waits until you run covibe-local paxel on your machine, which claims and executes it (30-min timeout via COVIBE_PAXEL_TIMEOUT_MS, 2-h stale auto-fail via COVIBE_PAXEL_STALE_MS, one active run per developer). Completed reports stay private until you mark them team-visible; teammates then see the report link/token read-only on your Performance profile. On for local/self-hosted installs, off on the central hosted origin (COVIBE_PAXEL_ENABLED, or a tenant admin can toggle it in Settings). See docs/engineering/paxel-integration.md.

Change Tracking, Visibility, and Sharing#

  • Exact change tracking (P3). Each repo snapshot also captures recent commits — the deterministic events that caused file changes — with before/after lineage (parent_sha → sha), branch, and per-file status, stored without any code content. They appear under Activity → Recent commits. When one developer runs two agents (e.g. Claude and Codex) on the same files, the second snapshot warns that it overlaps your other session, over MCP and in the UI.
  • Filters (P6). Activity filters commits and sessions by repo, branch, and agent; Performance keeps the 7d/30d/90d range toggle and the workspace switcher.
  • Consent and visibility (P6). Settings → Account → Profile visibility lets a developer mark their profile and metrics private. Private developers are hidden from teammates' team views and from MCP tool responses (team state, sessions, performance, members); overlapping-file warnings still fire but name the other side @private. They always see themselves, and tenant admins see everyone for coordination. Co-Vibe is for coordination, not surveillance.
  • Share links (P7). Settings → Share links creates a public, read-only link to your latest weekly summary (/share/<token>). The link carries a frozen, sanitized snapshot — the public page needs no auth and never queries tenant data. Links expire (7 days) and can be revoked.
  • Connected repos. Settings → Connected repos lists, read-only for every member, the repos each developer's machine companion reports via heartbeat, with a synced / pending / excluded pill per repo; a pending repo shows the covibe-local include opt-in hint. Only repo basenames leave the machine.
  • Tenant data reset. Settings → Danger zone (tenant admins only) wipes all work data — tasks, sessions, events, telemetry — for every workspace in the tenant after typing the tenant name to confirm. Developers, workspaces, and agent tokens are kept, so agents stay connected. This cannot be undone.

Data Export#

Export structured coordination data with:

bash
npm run db:export

The default output goes under data/exports/. Pass -- --out path/to/export.json to choose a file. MCP token hashes and raw tokens are not included.

Auth#

Local dogfood mode does not auto-select a default developer. Enter an owner name/email on the local sign-in page, then create the tenant and first workspace at /onboarding and start from that real tenant/workspace context. WorkOS AuthKit activates when all WorkOS env vars in .env.example are set; /auth/sign-in then offers GitHub, Google, and email sign-in (the providers deep-link, email continues to hosted AuthKit), /auth/sign-up is the tenant-creation path (it provisions a WorkOS organization so the team can grow), and first-session users land in the /welcome wizard — agent setup, the repo-logging disclosure, and team invites. Production cannot fall back to local dogfood auth: protected routes fail closed when WorkOS config is incomplete.

WorkOS Organizations are the tenant/company boundary. Co-Vibe workspaces sit inside that tenant, and MCP tokens log work on behalf of the signed-in developer who created them. See docs/engineering/auth-plan.md for tenant/workspace, Settings, logout, and WorkOS callback details.

To test tenant creation locally without WorkOS, run COVIBE_AUTH_MODE=local-dev npm run dev -- --port 3206, enter a name/email on the sign-in page, and create the tenant at /onboarding. To test WorkOS locally, set the WorkOS env vars and run COVIBE_AUTH_MODE=workos NEXT_PUBLIC_WORKOS_REDIRECT_URI=http://localhost:3206/callback npm run dev -- --port 3206 with that exact localhost callback added in the WorkOS dashboard Redirects page; without the allowlisted URI, WorkOS redirects to redirect-uri-invalid. For deployment, NEXT_PUBLIC_WORKOS_REDIRECT_URI must be the deployed HTTPS callback, for example https://co-vibe.example.com/callback.

Run npm run doctor:production before deploying WorkOS mode; use npm run doctor:production -- --help to inspect the required env first. After npm run build, run npm run smoke:production:blocked to verify a built server fails closed when WorkOS env is missing.

Quality Gates#

Run npm run readiness before calling a build customer-ready; still run npm run doctor:production with real WorkOS deploy env before hosted release. npm run check:accuracy runs the committed overlap-recall/precision and Performance quality read-model tests that back the 90%+ product-quality target. For hosted customer rehearsal, run npm run readiness:customer locally. After deploy, run npm run readiness:handoff -- https://...; it starts with a fast remote /api/health preflight and production doctor before the long customer and hosted canary gates. The final hosted command must target the real HTTPS customer origin; local container rehearsal uses npm run readiness:container:hosted. Run npm run doctor:production -- --help for the WorkOS deployment env, npm run readiness:customer -- --help for Docker and WorkOS rehearsal requirements, npm run readiness:hosted -- --help for hosted release gates, and npm run readiness:handoff -- --help for the accepted URL forms and rejection rules before a customer handoff.

bash
npm run check:accuracy
npm run readiness
npm run readiness:customer
npm run readiness:handoff -- https://...

Use npm run test:e2e:isolated when another Co-Vibe dev server is already running; to test an already-running local-dev server, set COVIBE_E2E_BASE_URL before npm run test:e2e.

Docs#

For a visual, non-technical-friendly walkthrough of the whole system, open docs/overview/how-co-vibe-works.html in a browser. For deployment and local setup orientation, open docs/overview/co-vibe-dev-guide.html; for agent capture details, open docs/overview/co-vibe-agent-logging-technical.html; for product-scope details, open docs/overview/agent-mesh-scope.html. For a one-screen executive summary, read docs/overview/bluf.md. AI search tools can read the machine-readable summary served at /llms.txt. The public marketing page is the root route / — see docs/product/landing-page.md.

See AGENTS.md for required read-first docs and repo rules.

License#

Co-Vibe is licensed under the GNU Affero General Public License v3.0 (AGPL-3.0-only) — see LICENSE. The AGPL's network-use clause (section 13) means anyone who runs a modified Co-Vibe as a hosted service must make their modified source available to its users.

© 2026 Spaceflow Technologies, Inc. Security issues: security@co-vibe.dev (see SECURITY.md).

View as .md