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 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 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.