Skip to main content
Install Copass into Claude Code and your agent gets a window-aware retrieval layer that surfaces only the context it needs, when it needs it. No chunk dumps, no duplicated facts across turns, no prompt-engineering gymnastics to keep the window lean. Under the hood this is progressive disclosure — cheap menu first, detail on demand. This page covers what the extension unlocks in Claude Code specifically and how to turn it on.

​
What you unlock in Claude Code

Automatic context per turn

A prompt-submit hook runs a discover call on every user message and threads the result into the agent’s context. The agent sees relevant project knowledge without you having to remember to ask for it.

Context window stays lean

Exploratory turns stay under ~1 KB of menu text. Detail only materializes when the agent commits to a specific item.

No duplicate retrieval

The extension tracks what the agent has already seen in this conversation and skips re-surfacing it. Follow-up turns reach deeper, not sideways.

Agent-driven depth

The agent decides when to read structure vs. when to pull full prose. You get real signal-per-token discipline on long coding sessions.

​
What you see on every turn

The extension renders the discovered context as an ontology graph — a live ASCII tree of the structural neighborhood around your question, drawn from your own codebase and notes. This is the Copass differentiator: you’re not looking at a flat list of chunks, you’re looking at how the knowledge connects. 
User: "why is checkout flaky this week?"

[Copass] Related Ontology Graph

Checkout Service
├── Stripe Webhooks
│   ├── retry policy
│   │   └── exponential backoff
│   └── dead-letter queue
│       └── manual review
├── Errors
│   ├── catches
│   └── throws
│       └── 5xx rate spike
└── Logs
    └── webhook latency

Alerts
└── Checkout webhook failures
    ├── PagerDuty integration
    └── threshold configuration

Payments API
└── idempotency keys
    └── dedup window
You see the shape of your system around the question — which services connect to which, what’s upstream of what, which alerts point at which subsystems. One glance tells you whether the graph has anything useful for this question and where to look next.
This is what makes the extension different from vector-search RAG panels. Trees show structure. Flat lists of chunks don’t.

​
Expanding a branch with interpret

The tree is the menu. Pick any branch — or a set of branches — and call interpret to get a grounded brief on exactly that slice of the graph. The agent does this automatically; you can also call it yourself from the CLI. 
Checkout Service
├── Stripe Webhooks       ◄── pick this subtree
│   ├── retry policy
│   │   └── exponential backoff
│   └── dead-letter queue
│       └── manual review
└── …
The agent turns the selection into a call: 
copass interpret '[["stripe-webhooks-id", "retry-policy-id"]]' \
  --message "why is checkout flaky this week?"
And gets back a brief synthesized from the actual source content behind that subtree — not a chunk dump, not a list of document snippets, but a 1-2 paragraph answer grounded in what your codebase and notes actually say: 
The checkout flow uses Stripe webhooks for confirmation, with an
exponential-backoff retry policy on 5xx responses. The handler lives in
`services/webhooks.ts` and persists failures to a dead-letter queue for
manual review. Recent alerts suggest retry pressure is driven by the
webhook latency rising past the configured threshold — see the latency
spike in the logs branch.

Citations:
  • Stripe Webhooks > retry policy    (100%)
  • Stripe Webhooks > dead-letter     ( 94%)
The agent can pick multiple branches in one interpret call, pinning the brief to exactly the combination it wants to reason about: 
copass interpret '[
  ["stripe-webhooks-id", "retry-policy-id"],
  ["alerts-id", "checkout-webhook-failures-id"]
]' --message "why is checkout flaky this week?"
Two tuples, one synthesized answer that spans both — and nothing outside them. The agent decides the scope; the brief follows.
The tree and the brief are two resolutions of the same graph. Tree for “where should I look?”, brief for “what does that part say?”. Together they’re the whole loop — navigation and grounding in two cheap calls instead of one expensive dump.
Curious why the shape is tree → brief → synthesis instead of “dump everything”? The Progressive Disclosure page walks through the four principles that drive it — and the token math against naive RAG.

​
Install

1

Install the CLI and log in

npm install -g @copass/cli
copass login
Requires Node.js 20+.
2

Set up a project

From a directory you want the agent to know about:
cd ~/your/project
copass setup
copass index
setup creates your sandbox and project. index ingests the current directory into the knowledge graph.
3

Register the MCP server in Claude Code

{
  "mcpServers": {
    "copass": {
      "command": "copass",
      "args": ["mcp"]
    }
  }
}
Reload Claude Code. The discover, interpret, and search tools appear in the agent’s toolbox.
4

Turn on the prompt-submit hook (recommended)

copass setup --enable-hook
Now discover runs automatically on every user prompt and the menu is threaded into the agent’s context. Zero-friction.

​
Where this shines

Long coding sessions

The retrieval layer doesn’t fill the window with sludge as the conversation grows. Turn 20 stays as sharp as turn 1.

Codebases you don't fully remember

Menu-first retrieval lets the agent navigate structure before committing to prose. Great for orienting inside unfamiliar code.

Cost-aware agents

Discover is cheap enough to run on every turn. Interpret and search are opt-in. Budget per turn as you like.

Multi-client setups

The same MCP server works in Cursor, Cline, and anything else that speaks MCP. One sandbox, many clients.

​
FAQ

No. Without it, the discover, interpret, and search tools are still available and the agent can call them explicitly. The hook is a convenience that makes discover happen automatically every turn.
The extension sees that and won’t re-surface it. Discover returns the next layer of relevant context rather than repeating what the agent has already read. See Progressive Disclosure → The window has memory.
Yes. The MCP server is client-agnostic — any MCP-speaking agent gets the same three tools.
Yes. The hook lives in .olane/hooks/ and runs only when the working directory matches a Copass-registered project. Remove the hook file or run copass setup --disable-hook to turn it off.
The CLI needs network access to hit the Copass API. Local indexing state and refs are cached, but retrieval is a live call.

​
Next steps