Using Columbus with Your Agent

Using Columbus with Your Agent

Columbus is a tool, not an autopilot. Your coding agent learns when and how to call it; Columbus just answers, deterministically.

The integration model: skills

Agents learn Columbus through skills — small instruction files that teach the agent the CLI: when to search before editing, how to read the dependency graph, how to record a decision, how to look up prior work. The skills live in the agent / plugin layer, never in the Columbus binary. This keeps Columbus a small, deterministic context server with no opinion on your workflow (see Scope Boundary).

Note: Columbus skills (for Claude Code and other agents) are published separately as plugin assets. Link coming soon.

The contract an agent consumes

Two machine-facing projections, both pure views of the same typed result as the human text output — they can never silently diverge:

• --json — a versioned, machine-readable contract with a canonical error envelope. Stable to parse, safe to depend on. See JSON Contract & Errors.
• --llm — markdown shaped for a context window: ranked results, exact line ranges, and a short "why relevant" per hit.

columbus search "where do we parse config" --llm    # drop straight into context
columbus graphs --in internal/server --json         # dependency graph, machine-readable

A typical agent loop

1. Locate before editing. columbus search "<intent>" --llm → jump to exact ranges instead of grepping and reading whole files.
2. Understand impact. columbus show symbol <name> --json and columbus graphs --in <path> → who imports / is imported by.
3. Check prior knowledge. columbus search "<topic>" --kind memory and --kind epic → has this decision already been made? what work touches this?
4. Record outcomes. columbus memory add context --type decision … and columbus memory update task … --status … → durable record for the next session.
5. Stay fresh. columbus reindex --changed after edits (cheap, incremental).

Why this beats naive exploration

• Fewer tokens — exact ranges, not whole files; locate once, not every session.
• Deterministic — the agent gets the same answer each run; reasoning is reproducible.
• Durable — decisions and work survive across sessions in memory/epics/tasks.
• Private & free — on-device embeddings, no cloud, no per-query cost.

Freshness signal

The --json projection of graphs (and others) includes a freshness block so the agent can decide whether to reindex:

"freshness":{"indexed_head":"c3035af…","dirty":false,"last_indexed_at":"2026-06-07T12:31:18Z","stale":false}

Related

Output Modes · JSON Contract & Errors · Exit Codes