Key takeaways
CLAUDE.md,AGENTS.mdand Cursor rules carry commands and conventions. They cannot tell the agent where a behaviour is implemented, and they only cover the repositories on disk.- On a 1.5M-line repository, OpenCode with grep and file reads spent 2.80M tokens per task. Our research agent, working from an index, used 767K and scored 12.8 points higher on the same model.
- A call graph helped on that 1.5M-line repository (relevant files found went from 78.3 to 82.4) and changed almost nothing on a 513K-line one.
- One model had a separate graph tool in all 40 tasks and never called it. Put relationships into the response the agent already reads.
- Library documentation (Context7) and team SaaS tools (Albato MCP, vendor MCP servers) are separate layers. They do not replace code context.
To give Claude Code or Cursor useful context on a large multi-repo codebase, use three layers. Keep a short instruction file in each repository for commands, layout and rules. Give the agent search that matches the question: grep for exact names, semantic search when it does not know the name, a call graph for "who calls this". For code outside the current checkout, connect an MCP server that indexes all the repositories and answers across them.
CodeAlive is our product, and the numbers below come from our own benchmark runs. Some tools mentioned here are made by companies we cross-mention with.
Which context source answers which question?
Why does a coding agent get lost in a large codebase?
A coding agent starts each session without a map of the system and finds code by exact text. The Claude Code documentation puts it plainly: each session begins with a fresh context window. Cursor's Agent searches with Instant Grep, a local exact-match and regex index, and can hand broad searches to an Explore subagent.
Text search is fast and precise when the agent knows what to look for. On a large repository it rarely does. It guesses a name, greps, reads a few whole files, guesses again, and every file it reads stays in the history that goes back to the model on the next step.
We measured this on RepoContextBench v2. On Sapling, about 1.5M lines, OpenCode with its built-in search and file reads made 1,157 tool calls across 20 tasks, spent 2.80M tokens and 297 seconds per task, and scored 43.9 out of 100. On the 513K-line Microsoft Agent Framework the same agent needed 180K tokens per task. The same agent and the same number of questions cost about 15 times more tokens on the larger repository (CodeAlive harness vs OpenCode).
What do CLAUDE.md, AGENTS.md and Cursor rules do well?
Instruction files put the same text in front of the agent at the start of every session, which suits facts that rarely change: how to build and test, how the repository is laid out, naming rules, files that are generated and must not be edited.
The three formats overlap:
Anthropic's own guidance is to keep CLAUDE.md to facts the agent needs in every session, and to move multi-step procedures or rules for one part of the codebase into skills or path-scoped rules.
Where do instruction files stop helping?
Instruction files describe the code someone remembered to write down. They cannot answer which of 40 services reads a given queue, or which functions call the method you are about to change.
They also have a fixed cost. Whatever is in an always-applied file is in the context of every session, whether the task needs it or not. Claude Code's documentation adds that it treats these files as context, not enforced configuration: to block an action for certain, it points to a hook instead. Cursor notes that a file @-mentioned inside a rule is not inlined; the agent still has to open it.
And they only see the repositories on disk. A rule in the payments repository says nothing about the order service unless someone copied that knowledge in by hand, where it starts going stale the next day.
We keep instruction files small and use them for routing. Our local workspace is a folder of 19 independent repositories with a root AGENTS.md that lists each repository, what it holds and which file to read first. The agent reads the child repository's own AGENTS.md before working in it. Questions about how the code behaves go to search.
When is grep enough?
Grep is enough when the agent knows the exact string: an identifier from a stack trace, an error message, a config key, a route path. It costs no setup, it is always current, and it never returns something that is not in the code.
It also wins on small and medium tasks where an index adds overhead. On Agent Framework (513K lines), OpenCode with grep used 180K tokens per task against 398K for our research agent, because our agent starts with a larger prompt and receives whole symbols with their callers. Our agent scored 24.7 points higher there, so the extra tokens bought answer quality. Still, if the question is "where is PaymentFailedError thrown", grep answers it in one call.
Grep stops being enough when the agent has to guess names. On Sapling the same grep-first agent made 1,157 tool calls across 20 tasks; the CodeAlive research agent made 459.
When does semantic search help a coding agent?
Semantic search helps when the agent knows the behaviour it is looking for but not the name of the code that implements it, which describes most real questions: "how do we retry failed webhooks", "where is tenant isolation enforced".
The tools alone are only part of the gain. When we connected CodeAlive's search to OpenCode over MCP, its score on all 40 questions went from 46.6 to 50.3 and its tokens on Sapling dropped 30%, to 1.97M per task. The CodeAlive research agent, with the same tools and the same model, scored 65.3 with 767K tokens per task:
The difference is in how the agent uses search: it starts from semantic search, reads by symbol instead of whole files, and gets a next-step hint at the end of each tool result. These are one run per configuration; a repeated run moved scores by about ±2 points (full comparison).
When does a call graph help a coding agent?
A call graph helps on large repositories and on questions about relationships: callers, callees, implementations, the impact of a change. On a medium repository search already finds most of what the graph adds.
How the graph reaches the model matters as much as the graph. DeepSeek V4.1 Flash had a separate graph tool in all 40 tasks and called it zero times. GPT-5.6 Luna called it 15 times on Sapling and gained about 4 to 5 points. Adding the position of every call made things worse: −6.2 points on Sapling (GraphRAG for code).
The graph also has to be right. Checked against the compiler on Playwright, Zod and FluentValidation, 98.5–98.9% of CodeAlive's call edges were correct and it found 82–91% of real calls. The strongest open-source indexer we could score, codebase-memory-mcp, reached 41–65% precision and 40–51% recall (indexer comparison). A wrong edge sends the agent to read the wrong code.
How do you give an agent context across several repositories?
There are two working approaches: put the repositories on disk next to each other, or connect a service that has indexed all of them.
Claude Code documents --add-dir in its CLI reference, and Cursor documents multi-root workspaces on its search page.
With an indexed server, the first step in a multi-repo task is choosing where to look. In CodeAlive, get_data_sources accepts a description of the task and returns only the repositories and workspaces relevant to it, each with a reason for the match (MCP documentation). The agent then searches those and fetches the code it picked, which keeps search results small even when the system is large (how CodeAlive MCP evolved).
Which MCP servers give an agent code context?
Five MCP servers cover different parts of the problem. They are listed in no particular order.
Sourcegraph MCP
The Sourcegraph MCP server exposes a Sourcegraph instance's code search, file reading, history and Deep Search to agents. Administrators can disable individual tools and limit MCP access with a role permission, and users only see repositories they already have access to.
For whom: organisations that already run Sourcegraph across their repositories.
When it does not fit: teams without Sourcegraph Enterprise, since the MCP server is supported on Enterprise plans.
CodeAlive
CodeAlive keeps a hosted index of your repositories with semantic search and a code graph, refreshed on every push. Its MCP server exposes 11 read-only tools, including semantic_search, grep_search, fetch_artifacts, get_artifact_relationships and chat, and supports GitHub, GitLab, Bitbucket, Azure DevOps and Gitea. It can be self-hosted with your own LLM.
For whom: teams with large or multi-repo codebases who want Claude Code, Cursor or Codex to search code they have not cloned.
When it does not fit: a single small repository where grep already finds everything; tasks where the agent has to rename or move symbols, since the tools are read-only. A new repository needs initial indexing, which the documentation puts at 5 to 15 minutes.
Serena
Serena is an MCP toolkit that gives the agent IDE-style tools at the symbol level: find a symbol, find its references, rename, move, edit a function body. It runs locally against the checkout you have open.
For whom: work inside one repository where the agent edits and refactors, and you want reference lookups based on language tooling rather than text matches.
When it does not fit: questions about services you have not cloned. It works on the local checkout only.
codebase-memory-mcp
codebase-memory-mcp builds a code graph locally and serves it over MCP. On FluentValidation it indexed in 1.5 seconds in our runs, faster than CodeAlive's 2.8.
For whom: a local graph for one repository, where an approximate list of callers is good enough.
When it does not fit: tasks where the exact caller matters. In our check against the compiler it found fewer than half of real calls.
Context7
Context7 fetches current, version-specific documentation and examples for public libraries. It runs as an MCP server at https://mcp.context7.com/mcp or as a CLI with skills, and a free API key raises the rate limits.
For whom: anyone whose agent writes code against fast-moving frameworks and keeps suggesting last year's API.
When it does not fit: questions about your own services. It covers library documentation, not your code.
How do you connect the agent to the team's SaaS tools?
For tickets, CRM records or chat, connect an MCP server for each tool or a gateway that covers many of them. Some vendors publish their own MCP servers. A gateway trades that for one connection and one place to manage access.
Albato is an integration platform with 1,000+ connectors. Albato MCP is its white-label, multi-tenant MCP server: the agent connects once, and Albato routes each request to the right app, handles authentication with the end user's own credentials and returns the result. Its tools include find_action for locating an app and action, and create_connection_link for asking the user to connect an account (MCP quickstart).
For whom: SaaS teams building an agent that has to act in their customers' apps, such as HubSpot, Salesforce, Jira or Slack, without maintaining a server and an OAuth flow per app.
When it does not fit: a developer who wants Claude Code to read one Jira project this week. Albato MCP is part of Albato Embedded, listed from the Pro plan at $5,000 a month (Embedded pricing), and the server URL comes from an Albato manager. The vendor's own MCP server is the shorter path there.
FAQ
Should CLAUDE.md describe the whole system architecture?
No. Keep it to commands, layout and rules the agent needs in every session, and say where other repositories and documents live. Architecture details go stale in an instruction file and cost context on every task; let the agent find them through search.
Does Cursor read AGENTS.md?
Yes. Cursor lists AGENTS.md as a plain-Markdown alternative to .cursor/rules, and Claude Code can read AGENTS.md in place of CLAUDE.md. One file can serve both tools.
Is semantic search better than grep for coding agents?
They answer different questions. Grep finds a string you already know; semantic search finds code by what it does. On a 513K-line repository grep was cheaper, and on a 1.5M-line one the indexed agent used 3.6 times fewer tokens and scored higher.
Do I need a code graph?
On a medium repository, probably not: in our runs it moved scores within noise. On a large one it helped the agent find 4 to 5 points more of the right files, provided the graph was shown next to the code rather than behind a tool the model had to remember to call.
Can Claude Code search repositories I have not cloned?
Yes, through an MCP server that has indexed them, such as CodeAlive or Sourcegraph MCP. Without one, the agent only sees directories on disk, including any added with --add-dir.