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:

npm install -g --prefix "$HOME/.local" <origin>/downloads/co-vibe.tgz \
  && export PATH="$HOME/.local/bin:$(npm prefix -g)/bin:$PATH" \
  && covibe-local setup --base-url <origin> --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 <origin>; completion requires PASS service: ... installed, running.

Then verify the setup with the separate doctor check:

covibe-local doctor --base-url <origin>

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#

Watch and debug#

Setup installs the background watcher when it can. For foreground debugging, run:

covibe-local watch --base-url <origin>

For a one-off repo snapshot:

covibe-local snapshot --base-url <origin>

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:

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:

{ "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:

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:

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 for exactly what leaves the machine):

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/<slug>/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:

covibe-local exclude

To make new repos opt-in instead of logged by default:

covibe-local exclude --new-repos

Opt a repo back in with:

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:

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 for what each tier sends.