Bob for coding agents

Bob does not know what an agent is. It knows commands, plans, and locks. That is a feature: an agent gets the exact same deterministic contract a human does, no special pleading, no hidden mode. This page is the fast path to using that contract well.

If you are an agent reading this to decide what to do next: run bob learn --json before you plan anything. It is one read-only call and it will save you from guessing at flags this page also documents.

bob learn

bob learn is a one-shot onboarding brief. It takes no arguments. It mutates nothing and makes no network call — it is a summary of what Bob already knows about itself, not a probe of your workspace.

bob learn

Human mode prints a compact text briefing: what Bob is, the lifecycle order, the command list, and where to read more. Good for a person skimming a terminal. An agent should prefer the JSON form.

bob learn --json

The data object

bob learn --json returns Bob's standard envelope (below) with "command": "learn". Its data field carries the whole brief:

Field	Contents
product	What Bob is: a deterministic repository factory and lifecycle reconciler.
summary	A short prose description of the product contract.
lifecycle	The ordered workflow: init/new preview → plan → apply → check.
commands	One entry per command: name, purpose, whether it mutates, whether it supports --json.
json_envelope	A field guide to the envelope itself — what ok, data, warnings, and next_actions mean.
invariants	The safety guarantees an agent can rely on without re-deriving them.
mcp	The bob mcp serve command and the six read-only tools it exposes.
boundaries	What Bob explicitly refuses to own — see Non-goals.
docs	Canonical documentation URLs: https://bobcli.dev and https://bobcli.dev/agents.

Nothing in data requires a workspace. bob learn describes the product, not a repository, so it works identically from any directory.

Recommended agent bootstrap

Run bob learn --json once at session start. Cache the brief for the rest of the session — it does not change between commands, only between Bob versions. Then drive the actual work with the normal read-only commands:

bob learn --json          # once, at session start
bob plan --json            # before proposing or reviewing any change
bob check --json            # to confirm convergence, exits non-zero on drift

Only call bob apply after a human or an explicit policy has approved a conflict-free plan. Bob will refuse an unsafe apply regardless, but an agent should not treat that refusal as the review step.

The --json envelope contract

Every non-interactive command that supports --json writes one versioned envelope to stdout and nothing else:

{
  "schema_version": 1,
  "ok": true,
  "command": "plan",
  "data": {},
  "warnings": [],
  "next_actions": []
}

• schema_version is 1. Bob rejects wire formats it does not recognize rather than guessing at a shape.
• ok is true on success. On failure it is false, and data carries an error code and message instead of the command's normal result.
• command names the command that produced the envelope.
• warnings and next_actions are always arrays, even when empty.
• stdout carries only this JSON document. Diagnostics, Cobra usage text, and process errors go to stderr. Parse stdout without stripping anything first.

bob mcp serve is the one exception: its stdout is reserved entirely for newline-delimited JSON-RPC, and it never wraps transport errors in the CLI envelope above.

Exit codes

• 0 means the requested operation completed.
• Non-zero means it did not. Validation failures, unsafe paths, apply conflicts, failed required doctor checks, and transport failures all exit non-zero.
• bob check is the deliberate special case: it exits non-zero when the repository or lock would change, even though its JSON body is a normal, successful plan. Non-zero here is the answer, not an error.

An agent scripting Bob should branch on the exit code first and only inspect data for detail — do not infer success from the presence of JSON alone.

The read-only MCP surface

bob mcp serve runs Bob's MCP server over stdio. It exposes six tools, and none of them mutate a repository:

Tool	Result
bob_plan	Bounded plan actions, counts, truncation metadata, and a deterministic plan digest.
bob_check	Convergence, conflict, and lock-drift state, sharing the same plan digest.
bob_inspect	Bob state and offline binary availability, without running specialist probes.
bob_stats	Aggregate opt-in local usage for one workspace or all retained pseudonymous workspaces.
bob_recipe_describe	The embedded recipe schema, version, and supported choices.
bob_validate_manifest	Strict validation of a workspace manifest or bounded inline YAML.

A computed conflict from bob_plan or bob_check is still a successful, read-only result. It carries no mutation authority. Apply always goes through the normal approved shell path: bob apply <workspace>, reviewed like any other command, then plan again to confirm convergence.

Workspace allowlist

The server starts in exact-allowlist mode. Its startup workspace is the only one the tools may read by default:

bob mcp serve --help

Flags:
      --allow-any-workspace           allow MCP tools to read any existing workspace accessible to Bob
      --allow-workspace stringArray   additional exact existing workspace allowed to MCP tools (repeatable)
      --workspace string              default existing workspace (defaults to startup cwd)

• --workspace sets the default workspace explicitly instead of relying on the process's startup directory.
• --allow-workspace is repeatable and adds specific additional existing workspaces to the allowlist.
• --allow-any-workspace is the explicit broad mode. It allows the tools to read any existing workspace the Bob process can access. It is read authority, not a sandbox — the hosting process and agent runtime remain responsible for what the Bob process itself can reach.

Pick the narrowest mode that gets the job done. One repository needs --workspace and nothing else.

Example: Claude Code setup

claude mcp add bob -- bob mcp serve <workspace>

Replace <workspace> with the absolute path to the repository Bob should read. Add --allow-workspace <path> (repeatably) for a small fixed set of additional repositories, or --allow-any-workspace only on a trusted, machine-local setup that is meant to serve arbitrary local repositories.

What Bob refuses to own

Bob is not an LLM runtime, a planning agent, an evidence authority, a secret manager, a package manager, or a generic task runner. It does not run models, schedule agents, hold credentials, or declare that generated code behaves correctly. Optional tools — Codemap, Vecgrep, Cairntrace, TinyVault, file.cheap, Glyphrun — stay behind explicit public contracts that Bob describes but never operates on your behalf.

Safety invariants agents can rely on

These hold across the CLI and MCP surfaces, and an agent can build on them without re-verifying each session:

• plan, check, plain inspect, stats, learn, and Studio never mutate a repository.
• All six MCP tools are read-only; none of them run specialist probes or write to the target repository.
• apply preflights the complete plan first and writes nothing if any single action is a conflict.
• Bob never overwrites an unmanaged file that differs from the desired content — it reports conflict and stops instead of guessing.
• A managed file only updates if its current hash still matches the prior lock; a hand-edited managed file is a conflict, not a silent overwrite.
• Repeated apply converges to a no-op. Once a plan reports only unchanged actions, running apply again writes nothing.
• JSON stdout is machine-clean on every surface; warnings, errors, and diagnostics go to stderr (or, for MCP, stay outside the JSON-RPC stream).

See also

• MCPHub & local-agent for wiring the same six tools through MCPHub and scoping them to a local-agent gateway.
• Ownership & Safety for the full plan-state vocabulary (create, adopt, unchanged, update, conflict).
• CLI Reference for every command's flags in one table.
• Canonical docs: bobcli.dev and bobcli.dev/agents.