# Co-Vibe — full documentation > Every public Co-Vibe doc in one fetch, for agents and tools that prefer a > single file. Per-page markdown lives at the `.md` URL noted before each > section; the index is at [/llms.txt](/llms.txt). --- # Co-Vibe overview Co-Vibe is the coordination layer for teams running multiple AI coding agents such as Claude Code, Codex, and Cursor. It shows what developers and agents are working on before the work becomes a commit, catches real duplicate work early, and records verified usage and session signals. It is for coordination, not surveillance. ## What it does - **Shows work early.** Planned, active, blocked, and completed work appears in one team view. - **Warns before overlap becomes waste.** Agents receive duplicate-work warnings over MCP, not only in the UI. - **Captures agent activity with evidence.** Co-Vibe stores counters, provenance, and session state instead of trusting an agent-written summary. - **Builds a repo brain.** Distils durable team lessons, playbooks, and native code intelligence (file co-change, repeated-revert, churn, ownership) from the team's own history and serves them back to agents — including on the gate they already call before starting work — with a loop that measures whether a fix actually helped. - **Keeps code private.** Repo snapshots store paths, branch state, commit metadata, and diff hashes, not file contents. - **Runs locally or hosted.** The app uses PostgreSQL, WorkOS for hosted auth, and a local companion for repo and agent capture. ## 90-second path 1. Sign in to Co-Vibe and open Settings -> Agent connection. 2. Copy the companion install command and run it once on your machine. 3. Start Claude Code or Codex in any repo; Co-Vibe registers it automatically. 4. Watch active sessions, local file state, and overlap warnings appear in the console. 5. Open Performance for usage, sessions, reports, and developer profiles. ## Where to go next - [Why Co-Vibe](/docs/product/problem) - [Agent setup](/docs/overview/agent-setup) - [Agent rules](/docs/overview/agents) - [MCP tools](/docs/overview/mcp-tools) - [Privacy and telemetry](/docs/overview/privacy-and-telemetry) - Machine-readable summary for AI search: `/llms.txt` --- # Why Co-Vibe Modern engineering work starts before a commit exists. A developer may spend hours planning, debugging, editing local files, or working with an AI coding agent before the team sees a pull request. When every developer is also running agents, that hidden work multiplies. Co-Vibe makes that early work visible enough to coordinate. ## The coordination gap Without a shared work state: - two people can unknowingly work on the same fix - one agent can undo or duplicate another agent's work - blockers stay inside private chats - weekly reporting becomes a manual status chase - local file conflicts appear only after time has been spent The issue is not effort. The issue is timing. Teams see the work too late. ## Who it helps **Developers** get low-friction logging, duplicate-work warnings, and control over which repos are shared. **Team leads** see planned, active, blocked, and completed work without asking every developer for status. **Companies** get a clearer weekly story: what shipped, what is active, what is blocked, and which risks need attention. ## What Co-Vibe tracks Co-Vibe stores structured coordination records: - tasks and workstreams - blockers and decisions - agent sessions - repo snapshots - overlap warnings - verified usage counters - weekly summaries - share links Markdown is used for docs and exported reports. Product state lives in the database. ## What it is not Co-Vibe is not a keystroke tracker, screen recorder, or surveillance tool. It does not store prompts, model responses, transcripts, or file contents. It is a coordination layer for small AI-assisted engineering teams. --- # Agent setup Agent setup connects a developer's local coding tools to Co-Vibe without pasting raw tokens into config files. ## Install the companion Open Settings -> Agent connection and copy the install command for your Co-Vibe origin. Paste the copied block once on your machine: ```bash npm install -g --prefix "$HOME/.local" /downloads/co-vibe.tgz \ && export PATH="$HOME/.local/bin:$(npm prefix -g)/bin:$PATH" \ && covibe-local setup --base-url --log-new-repos ``` The explicit `~/.local` prefix is user-owned, so the service can apply signed updates without `sudo` even when the machine's default npm prefix is root-owned. The `export PATH` line makes that bin available to the copied block and preserves operator-provided npm prefixes. Add `export PATH="$HOME/.local/bin:$PATH"` to the shell profile for later manual commands. When launchd/systemd installation is requested, setup verifies that the service is actually running and exits nonzero on failure. Existing root-owned installs use the same recovery: rerun the copied block without `sudo`. Setup rewrites and reloads the user service to the new `~/.local/lib/node_modules/co-vibe` package. Confirm it with `covibe-local service status --base-url `; completion requires `PASS service: ... installed, running`. Then verify the setup with the separate doctor check: ```bash covibe-local doctor --base-url ``` Use the Co-Vibe origin only, for example `https://co-vibe.dev`. Do not use a callback URL, a path, credentials, a query string, or a hash. After setup, start a coding session in any repo. Claude Code's user-scoped MCP server is already available; agent activity registers the repo automatically for the machine-level watcher, so there is no repo setup or registration command. The watcher lazily installs local support files for the included repo. Restart only agent sessions that were already open when setup ran. ## Zero-touch wiring for later installs An agent installed after setup does not need a setup re-run. The background watch detects an installed-but-unwired agent (Claude Code, Codex CLI or app, Cursor, or Claude Desktop) on its next tick, provisions a token off the machine's existing credential, and writes the agent's MCP config — one attempt per companion version after success, with failed provisioning retried no more than once every 15 minutes, and never re-enrolling an agent you deliberately unwired. Auto-minted tokens are labeled and individually revocable in Settings. Set `COVIBE_AUTO_WIRE=0` in the service environment to disable. `covibe-local unwire claude-code` removes Claude's user MCP and hooks machine-wide (plus legacy project entries); Codex unwire is also machine-wide, while Cursor unwire applies only to the selected repo. Use `--dry-run` first. ## What setup does `covibe-local setup`: - opens the browser for one-click device approval when no token exists - stores per-agent typed credentials in `~/.covibe/credentials.json` - writes Claude Code's token-safe user-scoped MCP server and user-level hooks; project compatibility config is reconciled lazily - writes cwd-free Codex machine MCP config when Codex is installed - writes cwd-free Cursor machine MCP and hook config when Cursor is installed - writes Claude Desktop MCP config when Claude Desktop is installed (tools appear in Desktop chats after the next app launch) - installs a machine-level watch service by default on macOS and Linux, verifies that the requested service is running, and exits nonzero if it is not - reports idempotent, secret-free setup evidence; a failed report is retried at the next watch start without rolling back config Setup can run from a neutral directory and never prompts for the new-repo policy. Outside a Git repo it skips first-connect scanning and sharing; the watcher runs that consent-gated bootstrap after it observes an included repo. The copied command uses `--log-new-repos`; choose `--no-log-new-repos` for opt-in. When the watcher first observes an included repo, it adds the project MCP config, overlap-protocol rules, ignore entries, and `.covibe/telemetry` inbox idempotently. The written agent config carries a non-secret `COVIBE_AGENT` marker. The MCP token is resolved from the credentials file at runtime. ## Supported runtimes | Runtime | What Co-Vibe Captures | | --- | --- | | Claude Code | MCP tools, session hooks, repo snapshots, transcript usage counters | | Codex | MCP tools plus local split usage counters during watch | | Cursor | MCP tools, session hooks, repo snapshots, local usage counters | | Claude Desktop | MCP tools only (task logging, team state) from Desktop chats; no hooks or usage counters — tools appear after the next app launch | | Paxel | User-triggered local builder report through the official Paxel image | ## Watch and debug Setup installs the background watcher when it can. For foreground debugging, run: ```bash covibe-local watch --base-url ``` For a one-off repo snapshot: ```bash covibe-local snapshot --base-url ``` ## Repo brain (memory and skills) The companion has three commands for the repo brain. `memories` and `skills` run against the current repo and read no transcripts. Import this repo's local agent memory (Claude Code file-memory, `CLAUDE.md` / `AGENTS.md`, `.cursor/rules`, gstack learnings, `README.md` sections, and conventional-commit subjects — never code file contents) as active, workspace-visible learnings the team can use immediately. Sources are parsed and redacted locally, and the server applies content safety plus the same typed automatic admission contract as every other writer. Incomplete or transient entries become `no_claim`; callers cannot grant human trust. You can also re-enrich existing learnings or ask the server to synthesize new ones: ```bash covibe-local memories status # list local memory candidates found for this repo covibe-local memories import # upload as active, workspace-visible learnings covibe-local memories backfill # re-tag + re-classify existing learnings server-side covibe-local memories synthesize # server-side AI synthesis (needs a workspace LLM key) ``` `memories synthesize` takes `--source task_flow|transcript_flow|advice|research_doc|default` to run one specific server-side pass (default clusters learnings into playbooks and insights; `research_doc` drains pending research distillation). `transcript_flow` remains accepted only as a retired compatibility no-op; transcript procedures are now synthesized locally. Research output distinguishes an empty queue from a provider request failure and exits nonzero for the latter. The background watcher syncs configured research markdown/HTML at most once every 30 minutes. Commit `.covibe.json` at the repo root so every teammate uses the same folders; without the file/key, the default is `docs/research` plus `docs/reports`: ```json { "research_paths": ["docs/research", "docs/reports"] } ``` An explicit `"research_paths": []` disables ongoing research sync for that repo. Excluded, pending, and read-only repos are skipped. A persisted ignored cursor (`.covibe/research-sync-state.json`) avoids reading unchanged files and uploading unchanged hashes; local deletion prunes the cursor only after a full traversal. Bootstrap and watch sync share a per-repo cross-process lock, and include/read-write/config consent is rechecked before every file. The watcher rejects configured-root or cursor symlinks, securely byte-bounds the cursor, caps each scan at 5,000 new directory entries, and persists a depth-bounded traversal frontier so later ticks advance through large trees. Upload caps or rate limits retry the same page before that frontier advances. Cursor entries are namespaced by a non-secret destination fingerprint and are preserved for paths a partial scan could not inspect, so neither a destination switch nor a temporary filesystem failure silently suppresses the next upload. Terminal server validation rejects advance only the rejected file revision so later documents are not starved; an edit changes the revision and retries it. Materialize the workspace's active playbooks as agent-invokable skills: ```bash covibe-local skills status # show what would be written (no token needed) covibe-local skills sync # write Claude, Cursor, and Codex skill files covibe-local mirror status # show the docs/covibe learning-mirror state covibe-local mirror sync # write the shared-learnings mirror (docs/covibe/, gitignored, pruned) ``` One-shot first-connect bootstrap (the "magic moment": runs after `covibe-local setup` when setup is inside a Git repo, or once the watcher first observes an included repo; manual re-run below). It harvests the consent-gated transcript backlog, imports local agent memory, backfills the repo's existing research documents (the `.covibe.json` `research_paths` folders, default `docs/research` + `docs/reports`, md/html, up to 256KiB each) into the Memory Research library, runs server synthesis, then fetches `GET /api/memory/first-load` and prints what the team already knows about this repo: ```bash covibe-local brain bootstrap # run the first-connect harvest + import + synthesize + print covibe-local brain bootstrap --dry-run # print what would run (no token needed) ``` To decline the automatic first share at install time, run setup with `--no-first-share`: it pauses transcript reading, memory import, and the setup-time bootstrap — including its one-shot research/report backfill — before the watcher service starts (no race window). It does not disable the ongoing, separately-gated `research_paths` sync (above); the committed `.covibe.json` value is that consent surface. Resume the paused sources with `covibe-local transcripts enable` and `covibe-local memories enable`, then run `covibe-local brain bootstrap` yourself. `skills sync` writes `.claude/skills/covibe-*`, `.cursor/rules/covibe-*.mdc`, `.agents/skills/covibe-*`, and `.codex/skills/covibe-*`; the files are companion-managed, gitignored, and pruned when a playbook is no longer active. The background watcher also refreshes them automatically (default every six hours, `COVIBE_SKILLS_SYNC_INTERVAL_MS`), so a manual `skills sync` is only needed for an immediate refresh. Mine brand-new learnings and skills from your own recurring session flows autonomously (on by default, opt-out — see [Transcript-Based Learnings](./privacy-and-telemetry.md#transcript-based-learnings) for exactly what leaves the machine): ```bash covibe-local transcripts status # on by default; shows this repo's consent covibe-local transcripts run --dry-run # preview the bounded local scan (no token) covibe-local transcripts run # mine typed learnings or skills; no approval queue covibe-local transcripts revoke # stickily opt THIS repo out covibe-local transcripts disable # turn off for the whole machine covibe-local transcripts grant # re-opt a revoked repo in (optionally per provider) ``` Every complete, non-backlogged background or manual pass records a content-free per-developer receipt before advancing its local cursor; partial or truncated passes retry without claiming completion. Agents can audit workspace coverage with `covibe_team` operation `transcript_scan_status` (optionally pass `repo_key`): a zero-result receipt proves that developer's scan ran, while no receipt means the scan is not yet proven. Receipts contain only provider/version metadata and numeric outcome counts—including active coverage, previously completed shapes, same-epoch deduplication, and below-quality decisions—never transcript text, prompts, commands, results, or paths. Counts describe that completed pass rather than earlier bounded backlog passes. Transcript causal learnings and complete procedure candidates activate autonomously without a review queue. A procedure candidate is recallable immediately, but managed executable skill files retain the independent verification/graduation trust floor; the local model cannot grant itself verified or global-publication authority. Learnings and skills are synthesized LOCALLY by Claude with tools, skills, settings, persistence, MCP, and browser integration disabled. The process starts in an empty temporary directory with a minimal environment; there is no automatic Codex fallback because read-only Codex can still inspect unrelated local files. `COVIBE_LOCAL_SYNTH_CMD` is a trusted developer override, and `COVIBE_LOCAL_SYNTH=0` disables synthesis. The default Claude runner requires Claude Code 2.1.169 or newer for its tool-free `--safe-mode` contract. The runner sees only the already-redacted closed-vocabulary flow without file targets—never raw commands, results, prompts, paths, or transcript text. Only the scanned procedure contract and 3-64 opaque parent-session recurrence hashes upload. The server re-scans every field, applies the procedure quality/audit bar, and automatically records `active` or `no_claim`. The local model's repo/workspace proposal is retained as an enum nomination topic, but every one-repo transcript admission starts repo-scoped. Only the existing cross-repo graduation pipeline may widen an identical typed claim after independent recurrence in multiple repositories. The hashes show recurrence but remain caller-supplied provenance, so admitted transcript procedures stay unverified until independent research or graduation certification. Exact procedures certified by multi-repo graduation become verified workspace procedures only when at least one member independently clears the graduation trust floor; caller-supplied hashes and repo labels never do. The result may enter canonical skill delivery; workspace-global publication remains a separate authority. Eligible procedures awaiting that independent trust appear in Memory under **Transcript review**. This is an optional verification accelerator, not an admission gate: a signed-in member may choose **Confirm**, and the server revalidates the displayed revision and typed receipt before recording human provenance. Graduation still waits for a second server-owned mining observation at least 24 hours after the first. Historical scanning is resumable and defaults to the most recent 180 days (`COVIBE_TRANSCRIPT_HISTORY_DAYS`, bounded to 1-3,650 days). Each pass stops cooperatively after 60 seconds, 25 changed files, or 32MiB (`COVIBE_TRANSCRIPT_SCAN_BUDGET_MS`, hard-capped at 10 minutes; `COVIBE_TRANSCRIPT_SCAN_MAX_FILES`, `COVIBE_TRANSCRIPT_SCAN_MAX_BYTES`); individual JSONL records are capped at 1MiB. Claude, Codex, and Cursor each reserve a fair share of the file, byte, and time budgets, and unused capacity flows forward. Large files use persisted byte checkpoints, lossless 400-line windows, and bounded action overlap. Replacement or truncation resets safely, and all reads use nonblocking, no-follow regular-file descriptors. Claude completes a resumable full-file structured-`cwd` preflight before any session group is admitted, then rechecks exact file generation and whole-group membership after content reads and before an autonomous typed upload. Groups above 256 files or 16 nested levels are held behind a durable marker; logs name the group and tell the developer to split, archive, or remove it. Codex and Cursor transcript generations are rechecked at commit and autonomous typed upload. Cursor also binds composer attribution to the exact `workspace.json` and `state.vscdb` generations; ambiguous multi-root workspaces fail closed. Both providers validate live Git worktrees instead of lossy directory keys. Local queue, cursor, ledger, and Codex-attribution cache files are fail-closed and bounded (8MiB/2,000 items, 16MiB/2,000 scopes, 512KiB/2,000 timestamped hashes, and 8MiB/20,000 entries respectively). Aged cursor paths are compacted before capacity checks, while queue pressure holds the cursor until a later bounded autonomous pass drains the queue. The ledger prunes out-of-window rows and rotates its oldest eligible row at the cap. Invalid flow history holds synthesis and its cursor without overwriting the history file. Redacted closed-vocabulary history retains up to 2,000 in-window session-flow records per repo under a 16MiB machine cap so recurrence spans passes. Revocation deletes that repo's history across main and linked worktrees. If the shared derived history is unreadable, revocation reports and discards the whole derived file because it cannot safely isolate the repo. Destination state uses a non-secret destination/developer fingerprint. Local synthesis has a 180-second run budget (`COVIBE_TRANSCRIPT_SYNTH_BUDGET_MS`, hard-capped at 15 minutes) and a 30-second candidate cap; rotation prevents starvation, and deferred work does not consume its cursor. The legacy enum upload is opt-in via `COVIBE_TRANSCRIPT_ENUM_UPLOAD=1`. The background watcher runs about once a day per repo (`COVIBE_TRANSCRIPT_SYNC_INTERVAL_MS`; `0` disables). A bounded scan backlog retries within one minute; a local-model or upload deferral waits for the next scheduled pass so a mixed-version rollout cannot hot-loop model spend. The watch loop also auto-imports your local gstack learnings (`~/.gstack/projects//learnings.jsonl`) into the team brain about once a day per repo, workspace-visible so skill clusters learn from them (`COVIBE_GSTACK_IMPORT=0` disables; `COVIBE_GSTACK_IMPORT_INTERVAL_MS` overrides), and recent tenant-visible gstack insights report sections feed the insight synthesis corpus. ## Repo privacy controls Repos a developer works in are logged to Co-Vibe unless excluded. To keep a repo private: ```bash covibe-local exclude ``` To make new repos opt-in instead of logged by default: ```bash covibe-local exclude --new-repos ``` Opt a repo back in with: ```bash covibe-local include ``` To keep coordinating from a repo while never writing team-brain content from it (learnings, transcript findings, skill flows, research documents), mark it read-only: ```bash covibe-local readonly # current repo: recall + coordinate only covibe-local readonly --remove # restore read-write covibe-local readonly --list # list read-only repos ``` See [privacy-and-telemetry.md](./privacy-and-telemetry.md#repo-controls) for what each tier sends. --- # Agent rules Co-Vibe's agent rules are product behavior: what connected coding agents should report, what the server enforces, and what stays private. They are not development instructions for this repository. ## Connect an agent Connect agents from Settings -> Agent connection. Setup opens the browser for approval, mints one typed token per detected agent, stores credentials on the developer's machine, and writes token-safe agent configuration. Onboarding also provides an initial agent setup prompt. It embeds the selected sharing command, verifies the installation, and teaches the task-first work model before the agent's first Co-Vibe call. See [Agent setup](/docs/overview/agent-setup) for the full install path. ## Work rules Agents should register real work before editing: 1. Check or plan the task with `covibe_task`. 2. Include a concrete `title`, `description`, `scope`, and `task_type`. 3. Add `action` and `component` when they clarify the work. 4. Start only after the server accepts the preflight check. 5. When the check returns escalated candidates, pass a `scope_verdict`. 6. When the agent confirms a true duplicate, ask the developer and pass a `confirmation_reason`. 7. Complete work with a result summary. A task is the default delivery unit: one concrete piece of execution, one owner, and one result. A workstream is optional and deliberate. Agents create one through `covibe_workstream` only when a named shared outcome has multiple related tasks. They never create a one-task wrapper or use a session, repo, or agent as a workstream. Passing `workstream_id: null` on `plan` or `start` explicitly keeps a task standalone. Omitting the field allows Co-Vibe to match an existing deliberate workstream with high confidence, but never creates one. Passing an id explicitly links the task. The server records every state change as a work event and every MCP tool call as a usage event. Abandoned work does not linger. A background idle sweep auto-cancels an active task once its owning session has ended and the task has seen no activity past the cutoff (default 48 hours; tasks that never had a session are left alone). It completes a deliberate workstream only after the same idle cutoff and only when no open tasks remain. Tasks do not create wrapper workstreams: unmatched work remains standalone. Re-starting later creates a fresh task; complete or cancel work explicitly to keep the board accurate in real time. ## Duplicate work Co-Vibe checks planned, active, blocked, and recent completed work for overlap. When the match is weak, the warning is visible but does not block the agent. When the match is strong, the agent receives structured candidates and must judge whether the scope is actually the same. A confirmed duplicate needs a human confirmation reason before it can start. The reason is stored with the warning so teammates can see why the overlap was allowed. ## Team context Agents can call `covibe_team` to retrieve the current team state before taking work: - active and planned work - recent completions - blockers and decisions - stale sessions - overlap warnings - published handoff context `covibe_team` also carries the project's durable memory: agents can record, list, share already-active private claims, and dismiss undelivered legacy rows. Typed claims are corrected by recording refuting evidence, not direct dismissal. Admission is automatic and returns `active` or `no_claim`; there is no candidate approval step. Agents can pull advisory context for a task or a set of files (relevant lessons plus co-change, revert, churn, and ownership hints mined from commit history), and read the self-improvement report. This context is advisory and never blocks; only `covibe_task check` gates work. The tool surface is documented on the [MCP tools](/docs/overview/mcp-tools) page. The companion advertises the typed `record_learning` fields. Older prose-only callers still reach the server and receive the structured `typed_contract_required` response. The retired `/api/memory/settings` and `/api/memory/promote-all` paths remain authenticated compatibility shims: they report automatic mode or a deterministic no-op and never restore approval state. Long-running agents should keep sessions current with `covibe_session` start, heartbeat, snapshot, activity, context, and end operations. ## Privacy boundary Co-Vibe is a coordination layer, not surveillance. Connected agents and the local companion report coordination metadata such as task state, session timing, usage counters, branch names, changed file paths, diff hashes, and commit metadata. Co-Vibe does not store prompts, model responses, full transcripts, file contents, or raw MCP tokens. Telemetry payloads that contain prompt, transcript, or response fields are rejected. ## Agent tool surface Agents use eight compact MCP tools: - `covibe_task` - `covibe_workstream` - `covibe_session` - `covibe_note` - `covibe_team` - `covibe_coordination` - `covibe_warning` - `covibe_ingest_agent_telemetry` The public tool summary lives in [MCP tools](/docs/overview/mcp-tools). --- # MCP tools Agents talk to Co-Vibe through eight compact MCP tools. The tools are operation-based: one tool owns a domain, and the `operation` field names the action. ## Public tool surface | Tool | Purpose | | --- | --- | | `covibe_task` | Check, plan, start, start planned work, update, complete, cancel, reassign, list tasks, calculate statistics, or run granular structured queries | | `covibe_workstream` | Check, plan, start, start planned work, update, complete, or cancel larger workstreams | | `covibe_session` | Start, heartbeat, snapshot, record activity, publish/get/revoke context, or end a session | | `covibe_note` | Log a blocker or decision | | `covibe_team` | Read team state, feedback, duplicate audits, a weekly summary, or shipped work; automatically classify typed memory with record/list/dismiss, use compatibility `promote` only to share an admitted active private claim, fetch advisory context packets, inspect improvement signals, and manage research documents | | `covibe_coordination` | Announce work, claim code, ask or reply to peers, hand off or release claims, check conflicts, and summarize coordination | | `covibe_warning` | Dismiss overlap warnings with a reason | | `covibe_ingest_agent_telemetry` | Submit verified usage counters from supported sources | ## Task lifecycle Agents should check or plan work before starting: ```json { "tool": "covibe_task", "input": { "operation": "check", "title": "Fix token revocation status", "description": "Verify revoked agent tokens cannot call MCP", "scope": "MCP token revocation enforcement", "task_type": "bug", "action": "fix", "component": "server" } } ``` `task_type` is required for task `check`, `plan`, and `start`. Valid values are `feature`, `bug`, `refactor`, `chore`, `docs`, `test`, and `spike`. ## Listing, statistics, and granular task queries `operation: "list"` is the read door: it enumerates tasks (default: your own `active` + `blocked`, newest-updated first) and never blocks or warns. Pass `task_id` instead to retrieve one task in full detail: ```json { "tool": "covibe_task", "input": { "operation": "list", "statuses": ["active", "blocked"], "owner": "me", "limit": 20 } } ``` Use `operation: "stats"` when the question is about counts rather than task rows. The filters are exact and composable; repo aliases are folded into their canonical repo before grouping: ```json { "tool": "covibe_task", "input": { "operation": "stats", "developer": "@taskin", "repo": "co-vibe", "statuses": ["planned", "active", "blocked", "done", "cancelled"], "group_by": ["developer", "repo", "task_type", "status"] } } ``` Statistics count the full filtered set, independent of `list`'s 100-row page. Private teammates remain hidden. If more than 100 complete groups would be returned, the call errors and asks for narrower filters instead of returning partial counts. Unknown filters are rejected. Statistics labels are defanged, responses are marked as untrusted teammate content, and responses beyond the 120,000-byte MCP budget ask for narrower filters or fewer grouping dimensions. Use `operation: "query"` for SQL-like drill-down and analytics. It is a structured allowlisted query, not raw SQL. This example answers the original per-developer/per-repo/per-type question for Taskin and can be paged without losing exact totals: ```json { "tool": "covibe_task", "input": { "operation": "query", "mode": "aggregate", "where": { "developers": ["@taskin"], "repos": ["co-vibe"], "statuses": ["planned", "active", "blocked", "done", "cancelled"] }, "group_by": ["developer", "repo", "task_type", "status"], "metrics": ["count", "count_active", "count_planned", "count_done"], "order_by": [{ "field": "count", "direction": "desc" }], "limit": 100, "offset": 0, "include_total": true } } ``` Row mode is the drill-down equivalent: ```json { "tool": "covibe_task", "input": { "operation": "query", "mode": "rows", "select": [ "task_id", "title", "developer_handle", "repo", "status", "task_type", "component", "priority", "workstream_title", "updated_at" ], "where": { "developers": ["@taskin"], "repos": ["co-vibe"], "task_types": ["feature", "bug"], "actions": ["create", "fix"], "components": ["server"], "priorities": ["high", "med"], "q": "query", "q_fields": ["title", "description", "scope"] }, "order_by": [{ "field": "updated_at", "direction": "desc" }], "limit": 50, "offset": 0 } } ``` `where` also supports task/workstream/session ids, branches, overlap statuses, `has_workstream`, `has_session`, session states, and inclusive created/updated/ started/completed time ranges (strict ISO 8601 date-time with `Z` or an explicit offset). Aggregate mode can group by developer, repo, status, task type, action, component, priority, branch, workstream, session state, or created/updated/completed day. It can calculate distinct developer/ repo/workstream/session counts and per-status counts. Every page returns `has_more`, `next_offset`, and `window_exhausted`. At the 100,000-offset window, more data is reported with `has_more: true`, `next_offset: null`, and `window_exhausted: true` so the caller narrows filters instead of receiving an invalid continuation. Row pages also return `applied_limit`: verbose selections can lower it below the requested `limit` to keep worst-case UTF-8/JSON materialization under 100,000 bytes, while exact totals and paging remain intact. Query-returned completion summaries are capped at 4,000 characters without restricting the legacy completion write contract. Legacy title, description, scope, and summary values are bounded inside query SQL. Responses carry a `security` envelope whose `trust` value is `untrusted_teammate_content`, plus `content_note`; these mark defanged teammate-authored prose as untrusted background, never instructions. The runtime and both MCP schemas reject the same invalid combinations. Team-wide text search needs another selective filter, and team-wide grouping by `branch` or `workstream` does too; use `owner: "me"` or add filters such as developer, repo, a narrowed status set, task id, or a fully bounded range of at most 90 days. Presence booleans and complete enum sets do not satisfy the cost guard. Repo aliases are owner-scoped. A legacy name-only task is canonicalized only when that developer's aliases point to one distinct repo key; if the name is ambiguous, the raw repo identity is preserved and canonical filters do not guess based on the most recent heartbeat. ## Planning future work `operation: "plan"` registers a task without starting it — the backlog that `start_planned` later activates: ```json { "tool": "covibe_task", "input": { "operation": "plan", "title": "Add per-agent unwire command", "description": "covibe-local unwire reverses auto-wiring for one agent", "scope": "companion CLI unwire per-agent config removal", "task_type": "feature", "action": "create", "component": "client", "priority": "med" } } ``` Plan each idea as its own task. Plan-time overlap warnings are informational and never block; when an identical open task already exists, the server returns it with `deduplicated: true` instead of creating a twin. To activate a planned task, re-check it first: call `operation: "check"` re-stating the task's exact title together with `planned_task_id`, which stops the plan from matching itself. Then, within 10 minutes, call `operation: "start_planned"` with `task_id`, the returned `check_id`, and a `scope_verdict`. The server activates the stored definition, inherits the session's repo and branch when the plan carried none, and re-checks for overlapping work that started after the task was planned. The same `plan`/`start_planned` lifecycle exists on `covibe_workstream`. A workspace admin can put a planned task directly on a teammate's plate by adding `assignee` (an @handle) to `plan` — the handle must belong to an active member of the workspace. The same admins can move a still-planned task to a different teammate with `operation: "reassign"` (`task_id` + `assignee`); reassignment only applies while the task is still planned, not once it has been started. Either way, the assignee's agent is notified with a live-session banner (when the agent has an active session) and a session-start digest (repeating until the task is picked up), then picks the task up through the same flow above: `check` with `planned_task_id`, then `start_planned`. ## Duplicate-work gate Co-Vibe compares new work against planned, active, blocked, and recent completed work. - Weak matches are disclosed and recorded, but do not block start. - Strong matches return candidates that the agent must judge with `scope_verdict`. - A confirmed duplicate requires a human `confirmation_reason` before it starts. - The server records the verdict and writes an audit event. Warning hygiene: a re-check of the same work supersedes the developer's earlier still-pending warning (status `superseded`), and a warning that sits pending for 7 days with no judgment expires (status `expired`). Both are lifecycle noise — they are hidden from the console cards and excluded from every caught/dismissed metric, so re-checks and abandonment never inflate a KPI or strand an "awaiting judgment" card. Those two statuses are terminal: both the scope-verdict gate and the confirm/dismiss resolvers skip lifecycle-noise rows, so a start replaying a stale `check_id` is never blocked on a retired warning and can never flip a superseded or expired row back into a visible card. This keeps real duplicate work visible while avoiding false blocks on unrelated work. ## Session context Long-running agents should use `covibe_session` to keep work state fresh: - `start` at the beginning of a run - `heartbeat` during long runs - `snapshot` for bounded repo state - `activity` for session-scoped counters and line deltas - `publish_context` when there is useful handoff context - `get_context` before taking related work - `revoke_context` when a published context should be withdrawn - `end` when the run finishes Snapshots store repo metadata, paths, hashes, and commit information. They do not store file contents. ## Peer messaging Agents can send a durable developer-targeted message with `covibe_coordination`: ```json { "tool": "covibe_coordination", "input": { "operation": "ask_peer", "to_handle": "@emre", "repo": "co-vibe", "question": "Can you pause edits in src/server/mcp while I land the schema?" } } ``` Choose exactly one of `to_handle`, `claim_id`, or `to_session`. A handle or claim target is stored in that developer's repo-scoped mailbox even when they are offline; the response reports `delivery_status: "queued"` when a matching session is live or `"waiting_for_session"` otherwise. The row survives session churn and attaches to the next matching session. Pending delivery expires after 30 days; replaying the original `request_id` then reports `expired` rather than pretending the message is still queued. `to_session` is the stricter live-session label from `covibe_team` `recent_sessions` (`session_label`, for example `claude@main`, `cursor@feature-x`, or `codex@main`). The response includes `target_status: "live"` when the message was stored for delivery, or `"offline"` when the target is stale/ended and nothing was stored. Exact-session labels resolve only inside the sender's repository, preventing an identically named session in another repo from being selected accidentally. Delivery happens on the recipient's next agent-visible Co-Vibe activity—not on a wall-clock push channel. Claude Code and Cursor opt in during `SessionStart`/`sessionStart`; all agents also receive pending messages piggybacked on ordinary owned MCP responses in `data.peer_messages`. Background and terminal lifecycle calls cannot consume them. Each entry includes a ready-to-show `banner`, `message_id`, a fixed security disclaimer, and a body fenced as untrusted teammate content. Ask and reply payloads that look like prompt injection are rejected before storage. Reply with `covibe_coordination` `operation: "reply_peer"` and the shown `message_id`. The banner contains no peer prose; official hooks and the stdio bridge show the redacted sender plus fenced body. Routed session ids stay private. Coordination summaries require `session_id` or explicit `repo` scope before returning peer inbox/sent rows. Codex has no hook push channel, so it receives through the universal piggyback only. The stdio MCP bridge starts a Codex session on the first Co-Vibe tool call, caches the returned `session_id`, and attaches it to later calls when the caller did not provide one. That makes Codex addressable as `codex@`, with delivery occurring on its next Co-Vibe MCP response. Transport retries reuse one request id, so a timed-out send cannot create duplicate messages. Authenticated mailbox quotas cap pending depth per sender/lane and per sender workspace-wide, cap each lane, and rate-limit sends. A rejected message creates neither an outbox row nor an audit event. Fair draining gives each sender a turn before returning another message from the same sender. ## Telemetry `covibe_ingest_agent_telemetry` accepts supported payload kinds: `openai_response`, `codex_otel_span`, `anthropic_message`, `claude_sdk_result`, and `direct_counts`. Claude Code, Codex, Cursor, provider events, and local harnesses feed those formats. The server parses counters, stores provenance and a usage hash, and rejects prompt, transcript, or response-style fields. --- # Privacy and telemetry Co-Vibe records coordination metadata. It does not record private conversation or source-code content. ## What Co-Vibe stores Co-Vibe stores: - tasks, workstreams, blockers, decisions, and completion summaries - agent session timing and status - MCP tool usage events - verified model and token counters plus explicit billing-mode metadata (`service_tier`/`speed`) when a provider event exposes it - branch names, changed file paths, diff hashes, and commit metadata - overlap warnings and human confirmation reasons - weekly summaries and share-link snapshots when a user creates them - full research/report deliverables from `docs/research` and `docs/reports` when first-connect sharing runs, or when an agent deliberately ingests one - a secret-free setup report containing agent enums, companion version, semantic config digest, and setup/service states These records let a team see what is happening before a pull request appears. ## What stays local The local companion does not send: - prompts - model responses - full transcripts - ordinary file contents (except research documents selected by the committed `.covibe.json` `research_paths` consent surface described below) - local database files - raw MCP tokens Claude Code, Codex, and Cursor capture paths read only the counters and metadata needed for coordination and verified usage, including explicit billing mode when the local provider event records it. Counter-only telemetry payloads may be submitted to the server, but Co-Vibe normalizes them into counters, provenance, cost data, and a usage hash. Payloads that include prompt, transcript, or raw response fields are rejected. ## Agent credentials Setup stores per-agent credentials in `~/.covibe/credentials.json` with local file permissions. Agent config files contain a non-secret `COVIBE_AGENT` marker and the Co-Vibe origin, not the raw token. MCP tokens are owned by the developer who approved setup. Revoking a token cuts off the corresponding agent. ## Repo controls Developers can exclude a repo: ```bash covibe-local exclude ``` They can also switch the machine to opt-in for new repos: ```bash covibe-local exclude --new-repos ``` Excluded repos do not send snapshots, telemetry inbox files, session activity, or MCP calls to Co-Vibe. With the new-repos opt-in policy, first activity registers a repo as pending and sends nothing until the developer includes it. Between full participation and exclusion sits the read-only trust tier: ```bash covibe-local readonly # mark the current repo read-only covibe-local readonly --list # list read-only repos covibe-local readonly --remove # restore read-write ``` A read-only repo still recalls team learnings and coordinates normally (tasks, sessions, snapshots, and telemetry all flow), but the companion never writes brain content from it: `memories import`, transcript analysis runs, transcript skill flows, approve-to-upload reviews, the entire first-connect bootstrap—including research/report backfill and server-side synthesis—and the ongoing `research_paths` folder sync are all skipped for that repo. This is the consultant case — search the shared brain from a client checkout without contaminating it with that client's work. The setting is local-only; it needs no token or network. The memory import also has a machine-wide pause, independent of transcript analysis: `covibe-local memories disable` stops agent-memory uploads from every repo on the machine until `covibe-local memories enable`. Setup's `--no-first-share` flag writes this pause (plus the transcript disable) before the watcher service installs, so declining the first-connect share has no race window. Consent updates use same-directory atomic replacement, and an existing malformed or torn consent file fails closed across transcript, memory-import, and first-share gates. A durable first-share pause also stops every later setup, watch, or manual bootstrap—including research/report backfill—at the shared boundary. After re-enabling transcripts and memories, the developer explicitly runs `covibe-local brain bootstrap` to perform the share. ## Reports Paxel reports run only when the developer triggers them. Claude Code insights reports run on demand (`covibe-local insights`) and on a background cadence (default every 3 days; `COVIBE_GSTACK_INSIGHTS_INTERVAL_MS=0` disables the auto-run). Both paths refuse while transcript reading is disabled machine-wide (`covibe-local transcripts disable` or setup `--no-first-share`), and refuse entirely on machines with excluded repos, since insights cannot honor per-repo exclusions. Insights reports are **team-visible by default** — like the other first-connect knowledge sources (transcripts, memories, research docs) — so a captured report is shared with the workspace unless the owner marks it private from their profile. Report narrative sections are evaluated by the automatic typed admission lane, but prose without a complete grounded claim writes only a hash-only `no_claim` receipt—no candidate or learning row. Because an insights narrative can name projects and clients across every repo the developer has worked in, treat a report as shared and flip it private if it should not be. (Paxel reports remain private by default.) ## Research documents Research documents enter the workspace through two bounded paths: - an explicit `covibe_team ingest_research_doc` agent call made on your instruction; - the companion's sync of the folders declared by the repo's committed `.covibe.json` `research_paths` (default `docs/research` + `docs/reports` when the file/key is absent) — the SAME scanner, run in two contexts. That sync runs FORCED once during the first-connect bootstrap, so existing matching documents backfill immediately, and is not a continuous watcher. Repo exclusion, the new-repos opt-in policy, read-only mode, `--no-first-share`, and `COVIBE_BRAIN_BOOTSTRAP=0` stop that bootstrap invocation at the shared `runBrainBootstrap` boundary before any stage reads or uploads. Thereafter the same sync runs on a per-repo cursor at most once every 30 minutes to pick up new or changed documents — still not a continuous watcher, and NOT gated by `--no-first-share` (which only skips the one-shot bootstrap invocation above). An explicit `"research_paths": []` opts the repo out of both invocations; excluded, pending, and read-only repos are always skipped. JSON syntax or shape errors warn and fall back to the convention folders; a config that cannot be securely opened, contained, or read within 64KiB fails closed and disables this source. Bootstrap and watch sync share a per-repo cross-process lock, and consent is rechecked before each document is opened or uploaded. The ignored `.covibe/research-sync-state.json` cursor avoids reading files whose size/mtime did not change and avoids uploading unchanged hashes. Configured roots and the `.covibe` cursor directory are realpath-contained inside the repo. A tick advances at most 5,000 new directory entries and saves a depth-bounded traversal frontier; a directory with more than 5,000 direct entries stops with a warning. An upload stop retries the same scan page before the frontier advances, while cycle-wide unseen, unreadable, or not-yet-scanned paths retain their previous cursor state. Destination state is keyed by a hash of origin+token, never the raw token. The cursor is opened no-follow and nonblocking with a 16MiB cap. Each file is opened without following a final symlink, revalidated before and after the read (including same-inode mutation), and read with a hard byte bound. New or changed documents are sent to the registry entry's Co-Vibe origin using that watcher's authenticated token, so they land in that token's tenant/workspace. Runs name the destination origin and repo in local logs. A local deletion prunes only the cursor after a complete traversal; it never deletes shared research knowledge. Both paths store accepted documents as workspace-visible team knowledge that teammates can retrieve in full. The synthesis lane submits durable sections to automatic typed admission; report prose and incomplete claims produce no memory row. The server scrubs token-shaped secrets and enforces a 256KiB per-document cap; research can legitimately contain names, contact details, and statistics, so what the developer shares is what the workspace sees. These paths are for research deliverables, never repo code or transcripts. ## Transcript-based learnings This feature is on by default (included by design) and opt-out at every level: `covibe-local transcripts disable` turns it off for the whole machine, `covibe-local transcripts revoke` stickily opts a single repo out, excluded repos never participate, and read-only repos never upload transcript-derived content (even findings queued before the repo was marked read-only). A revoked repo stays revoked until an explicit `covibe-local transcripts grant`; an explicit grant can also narrow which providers are read, and it never widens access beyond the default. Learning/skill synthesis from transcripts runs LOCALLY: for recurring patterns the companion feeds one representative, already-redacted closed-vocabulary flow to the developer's own Claude CLI. The default runner starts in an empty temporary directory with tools, skills, settings, persistence, MCP, and browser integration disabled and receives a minimal environment. There is no automatic Codex fallback: read-only Codex can still read unrelated local files. `COVIBE_LOCAL_SYNTH_CMD` is an explicit trust override for a developer-controlled command; it still starts in the isolated temporary directory with the minimal environment. That CLI may use a local model or its configured remote model under the developer's provider account, but it never receives raw commands, results, prompts, absolute paths, file targets, or transcript text from Co-Vibe. It receives only closed-vocabulary command, tool, outcome, and error tokens. Only the resulting typed procedure or causal learning, secret/PII-scanned fail-closed, uploads as a machine-labelled contract that the server re-scans. Every recurrent flow autonomously terminates as a skill, a causal learning, or `no_claim`; human approval is not part of this path. Current v6 typed claims carry three independent, companion-computed repo-salted session hashes and closed-vocabulary trace anchors present in the input. The server treats the hashes as opaque caller-supplied provenance rather than proof that it can independently verify the salting. The v2 causal-learning wire must be echoed by the server before a terminal result is consumed, so an older server causes an automatic retry instead of losing a learning. During the rolling upgrade, legacy procedure payloads retain their prior text-anchor admission behavior; current payloads carry source-trace anchors. A legacy template-only review queue remains as an optional migration fallback and is retired only after the corresponding destination completes its autonomous scan. The raw transcript store is never part of a Co-Vibe upload; only scanned typed claim fields are sent. As a backstop behind that local redaction, the server re-checks every uploaded finding against its content-safety rules and rejects anything it detects as a secret or raw content; because that detection is best-effort pattern matching, the local-analysis design (not the backstop) is what keeps raw content off the wire. Uploaded contracts become `active` or `no_claim` automatically. Verified procedures still require a certified delivery lane before they can reach agents. Any opt-out immediately stops further uploads. After a complete, non-backlogged pass, the companion sends a content-free scan receipt before it advances the local skills cursor. Partial or truncated work retries without publishing one. The receipt contains the authenticated developer, canonical repo key, consented provider names, companion version, and numeric counts only: sessions read, recurring flows, synthesis attempts, procedure/learning uploads, existing active coverage, same-evidence-epoch deduplication, previously completed terminal shapes, `no_claim`, below-quality, not-teachable, and content-gate outcomes. These are per-pass counters, not a cumulative total across earlier bounded backlog passes. It contains no prompt, response, transcript, command, path, file target, or generated claim text. Workspace members can query the latest receipt per developer with `covibe_team transcript_scan_status`; absence means “not proven scanned,” while a zero-result receipt proves the pass ran. The included-by-design local lane also powers transcript pattern mining (`covibe-local transcripts skills`). Instead of free text, it reduces each recurring session flow to a CLOSED-VOCABULARY action trace on the machine — a fixed set of tool names and the canonical command allowlist in `transcript-flow-vocab.ts` (`npm`, `git`, `tsc`, `vitest`, `pytest`, `gh`, `pnpm`, `yarn`, `npx`, `tsx`, `node`, `python3`, `make`, `docker`, `curl`) with an allow-listed second-word verb per command (`git commit`), while keeping repo-relative file paths out of the model prompt, plus a two-value ok/error outcome with a closed-vocabulary failure signature drawn from the paired tool result, collapsed repeat counts, and numeric counts. That reduced material is retained locally (bounded to 2,000 session-flow records per repo and 16MiB per machine) so a procedure that recurs across separate time-bounded scans is still detected. It contains no arguments, tool-result text, prose, prompts, or responses, and `transcripts revoke` applies to the main checkout and every live linked worktree, deleting every destination's cursor, queue, and retained history for that repository. If the shared derived history is unreadable and the repo cannot be isolated safely, revocation discards that entire derived file and reports the fallback rather than retaining the revoked repo's material. Consent and read-only policy are re-read after every asynchronous coverage or local-model step, immediately before each upload, and again inside each local state mutation lock. A revoke therefore wins over an in-flight scan: no later upload starts, its deleted cursor, queue, or history cannot be recreated, and the older run cannot add a synthesis-ledger marker. Consent and repo-policy mutations also use locked, fresh read-modify-write transactions behind one shared odd/even policy seqlock: odd is published before the policy write and the next even generation only after it completes. Comparing the exact captured even generation closes revoke→regrant and disable→enable ABA races, while the locks prevent concurrent grants, revokes, excludes, and read-only changes from erasing one another. The developer's own local agent CLI sees one representative, already-redacted closed-vocabulary flow without file targets and returns a strict procedure. Raw commands, results, prompts, paths, and transcript text never enter that runner. The default lane requires Claude Code 2.1.169 or newer so its tool-free `--safe-mode` contract is available. The companion safety-scans every returned field and uploads only the typed procedure, closed-vocabulary trace anchors, an opaque flow hash, and at least three and at most 64 sorted, unique repo-salted parent-session hashes through `ingest_transcript_candidates`. Subagent files share their canonical parent session identity, so they cannot inflate recurrence. Those hashes come from the deterministic recurrence miner, not the synthesizing model. The server re-scans every procedure field for secrets, PII, and unsafe absolute paths, validates distinct recurrence evidence, and source-binds the result as an active unverified procedure or records `no_claim`. The local model proposes `repo` or `workspace` scope; that enum nomination is retained, but a one-repo transcript cannot prove workspace generality: every local admission starts repo-scoped. A workspace proposal can be widened only by the existing graduation pipeline after the identical typed claim is independently grounded in multiple repositories. Opaque caller-supplied hashes are recurrence provenance, not verification authority. Raw context and the retained enum history are not uploaded by the default lane. The legacy enum-material upload is separately opt-in with `COVIBE_TRANSCRIPT_ENUM_UPLOAD=1`; its server-side synthesis source is retired, and even that compatibility wire omits local file targets. Cross-repo graduation may widen grounded knowledge to workspace scope, but it certifies an exact multi-repo procedure only when the cluster also clears the existing independent trust floor. Caller-supplied hashes and repo labels never satisfy that floor. Valid transcript procedures awaiting independent trust appear in a bounded Memory **Transcript review** inbox. This optional verification action does not gate autonomous admission. **Confirm** is a cookie-session human action over the exact displayed revision; the server revalidates the typed receipt and records server-owned human provenance. MCP/agent tokens cannot invoke that authority port or choose trust. Graduation then requires a second server mining observation at least 24 hours after the first; transcript timestamps cannot manufacture that age. The graduation receipt lets the canonical workspace procedure enter the existing skill-delivery lane. Explicit workspace-global publication authority remains a separate boundary: the local model can propose a repo skill, but cannot silently publish a machine-global skill. The word “skill” in transcript scan counters means a complete typed procedure candidate admitted autonomously as active memory. It becomes an executable, companion-managed skill only after the unchanged source-authorized verification/graduation policy clears it. Human confirmation can accelerate that trust path but is not a scan, synthesis, or learning-admission gate. Historical scans default to the newest 180 days (`COVIBE_TRANSCRIPT_HISTORY_DAYS`, bounded to 1-3,650), stop cooperatively after 60 seconds, 25 changed files, or 32MiB, and resume from independent findings and skills cursors. One JSONL record is capped at 1MiB. Header, attribution, Cursor metadata, and SQLite response bytes share the allowance; SQLite page I/O is separately deadline-bounded with fair database shares and rotation. Discovery receives 75% of each provider read budget and prioritizes unseen files. Claude, Codex, and Cursor each receive a reserved share of the remaining file, byte, and time budgets, while unused capacity flows forward to later providers. Transcript scans hard-cap the shared batch at 64 changed files; skills scans reserve the final quarter of their wall-clock allowance for recurrence mining. Recurrence mining seeds candidates only from the current scan, lets retained history add support only to those candidates, and never lets a history deadline discard completed scan progress. Current materials are retained locally before cursors advance; only an unreachable-by-default current-candidate safety-cap breach holds those cursors for operator correction. The Codex provider includes Codex CLI and Codex Desktop rollouts from the local `~/.codex/sessions/**/rollout-*.jsonl` and `~/.codex/archived_sessions/**/rollout-*.jsonl` stores under one deadline, discovery-byte allowance, and head cache. Repo attribution reads only the first `session_meta` record, with a hard 64KiB envelope; a longer or malformed header is excluded instead of being read without a bound. The cache format is versioned, and upgrading from the former 8KiB probe invalidates its negative entries so real Desktop sessions are re-attributed. Within an admitted rollout, only user and assistant messages become turns: paired Desktop event/response copies are deduplicated, while reasoning and system/developer instructions are ignored. Function and custom tool calls are paired with their results locally and reduced to the same closed action vocabulary before any skill mining. Large files advance through lossless 400-line byte windows with bounded action overlap. Replacement or truncation resets to byte zero; oversized records advance a bounded skip checkpoint. Reads pin no-follow, nonblocking regular-file generations. Claude recursively groups subagents and completes a resumable full-file scan of structured top-level `cwd` fields before admitting any group. A missing child `cwd` requires a verified parent. Exact source generation and whole-group membership are rechecked after reads and before autonomous typed uploads. Codex and Cursor transcript generations are bound and rechecked at those same boundaries. Cursor also binds each composer attribution to the exact `workspace.json` and `state.vscdb` generations that established its repo. Its full Git checkout identity is checked before and after the database read, so a separately initialized or metadata-forged nested repository cannot donate transcripts to its parent repository's learning scope. That identity travels with the local attribution witness and is revalidated at read, queue/cursor commit, skill commit, and typed-upload boundaries. Groups above 256 files or 16 levels are held with a durable, periodically rechecked marker; local warnings name the group and prescribe split, archive, or removal. Cursor uses workspace/composer provenance and rejects ambiguous multi-root histories. Both providers cover live worktrees without trusting non-injective provider directory keys. Only in-window, timestamped flow history contributes recurrence. The default history is the newest 180 days (`COVIBE_TRANSCRIPT_HISTORY_DAYS`, bounded to 1–3,650 days). Each scan defaults to 60 seconds and is hard-capped at 10 minutes. A versioned skills cursor replays that bounded window once when the typed-claim contract changes, then returns to forward-only incremental scans. Local state fails closed under explicit bounds: legacy review queue 8MiB/2,000 items, cursor 16MiB/2,000 scopes, synthesis ledger 512KiB/2,000 timestamped hashes, and Codex attribution cache 8MiB/20,000 entries. Queue pressure holds rather than consumes the cursor; aged path state is compacted before cursor capacity checks. Ledger rows outside the history window are pruned and the oldest eligible row rotates out at the item cap, so a full valid ledger cannot permanently wedge synthesis. Malformed, oversized, symlinked, or concurrently replaced flow history blocks synthesis without overwriting the file or advancing the skills cursor. Destination state uses a non-secret origin/developer hash. History and ledger mutations use locked fresh read-modify-write cycles. Findings commit queue-before-cursor behind an optimistic snapshot fence; skills use the same fence, so concurrent or stale runs retry instead of overwriting progress. Synthesis defaults to 180 seconds and is hard-capped at 15 minutes; each candidate is capped at 30 seconds, and candidate order rotates. Deferred, failed, and unvisited work is not consumed. Scan backlogs retry within one minute; local-model or upload deferrals wait for the next scheduled pass to avoid a mixed-version model-spend loop. --- # Dedicated Deployments Co-Vibe runs as a hosted service, and teams that need stronger isolation can get a dedicated deployment: a private instance of the Co-Vibe control plane operated for a single organization, with its own database, domain, and sign-in. The product is identical — only the isolation boundary changes. ## What does the standard hosted service look like? On the standard service at co-vibe.dev, every workspace shares one control plane. Tenant data is isolated with PostgreSQL row-level security: every query runs inside the requesting tenant's scope, and cross-tenant reads are rejected at the database layer, not just in application code. The local companion CLI is the only component on developer machines — repo snapshots, agent configuration, and usage-counter reads happen locally and sync out through authenticated MCP calls. ## What changes with a dedicated deployment? A dedicated deployment moves the entire control plane — web console, MCP API, and PostgreSQL storage — onto infrastructure that serves only your organization: | Component | Standard hosted | Dedicated | | -------------------- | --------------------------- | ----------------------------------- | | Control plane | Shared, multi-tenant | Private instance | | Database | Shared cluster, RLS-scoped | Own database | | Domain and sign-in | co-vibe.dev | Your domain, your SSO | | Local companion | Developer machines | Developer machines (same) | | Operations | Operated by Co-Vibe | Scoped per engagement | ## What stays on developer machines either way? The local companion owns repo snapshots, per-agent configuration, and local usage-counter reads. The companion never uploads your source code in either model: agents report work items, session activity, and telemetry through MCP tools, and the privacy model is the same as the standard service — see [Privacy and telemetry](/docs/overview/privacy-and-telemetry). ## How do I arrange one? Dedicated deployments are set up per team. Contact [hakan@spaceflow.tech](mailto:hakan@spaceflow.tech) with your team size and requirements, and we will scope the deployment together.