# 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`](./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`).