Claude Code

In one of my cal.diy experiments, Claude planned a rename in 16.01 seconds using its native tools. With Pharaoh (ours) available, it averaged 16.95 seconds. Both configurations named all fifteen expected files.

On a different question about the same repository, tracing the impact of a permission-check change took 32.03 seconds natively and 16.93 seconds with Pharaoh.

I build Pharaoh, so I would be happy with a result that said a graph made every task faster. These runs gave me a more useful rule: decide what information the task needs before deciding how to provide it.

A function body, a bundle of source files and a call graph each leave something for the agent to work out. The useful comparison is how much of that work remains for the question you are asking.

When I start with native search

If I have a symbol name and want to inspect its implementation, I usually start with search. For example, this locates the permission check and places that mention it in a cal.diy checkout:

rg -n '\bcheckAdminOrOwner\b' apps packages

The results point into source files I can open immediately. An IDE's references and rename tools

I ask Claude what breaks if I change a function, and I watch what it does. It greps, opens a file, greps again, opens three more, and keeps going until it's confident or out of patience. On my own codebase that one question takes 15 tool calls and 52.9 seconds.

With Pharaoh connected (I build Pharaoh), it takes one call and 10.2 seconds.

That's the whole idea. Pharaoh maps your repo into a graph of functions, callers, modules, endpoints and cron jobs, and hands it to your AI agent over MCP. Your agent stops reading the codebase one street sign at a time and starts reading the map.

The numbers

I asked Claude Code (Opus 5.5) the questions developers ask before they change code, with Pharaoh and without, three times each, and graded every answer against an expected-item key derived from the TypeScript compiler. On questions about how code connects in my own repository:

33.4 s → 13.6 s per question.

17.0¢ → 5.9¢ per question.

100% → 100% of the expected items mentioned.

Less than half the time, about a third of the cost, the same expected items named. Across two graded runs, Claude with

The auth module in the recorded cal.diy session below contains 43 files. Its callers reach into the API and the web app, so starting Claude inside auth, while useful for focus, wouldn't tell you how far a change could travel.

That's the tension I want the setup to handle. Keep the initial search small, let the task expand when the evidence requires it, even if that means revisiting your scope, and make the agent name the files outside its starting directory before you accept its plan.

Start in the package you're changing

For a task confined to one package, launch there. Substitute your own package path in this example.

cd packages/api
claude

claude starts an interactive session in that directory.

Use the CLI's --add-dir flag when you need access to a sibling directory.

claude --add-dir ../shared

claude --add-dir grants file access, so use it when the task reaches a sibling package, check the paths you're adding, and keep the edit scope explicit in your prompt. It doesn't import that package's full configuration. Additional-directory access and configuration are separate.

Starting below the root is a useful default for local work. A change spanning several packages may belong at the

A permission check can occupy three lines and still need a refactor plan that reaches into an API and the web app. In the captured cal.diy results below, checkAdminOrOwner appears in an auth utility, its callers include application services, and the impact query reaches two HTTP endpoints.

That's the project context I want before asking Claude Code to edit a shared helper. The definition is a start. I also need the rules around it, the callers that depend on its contract, the source revision those relationships describe, and a way to check the proposed change.

What project context needs to tell Claude

Claude Code can read source, search the checkout, run commands to investigate, and execute tests. Anthropic describes those capabilities in how Claude Code works.

For a refactor, I separate instructions from evidence. Instructions say which behavior must survive, where edits belong, which commands count as verification, and which boundaries need an explanation before crossing them. Evidence comes from inspecting the implementation and tracing its consumers.

An instruction to preserve a public signature helps. It doesn't establish who uses that signature.

For choosing between search, a source pack, or a graph, see how much repository context Claude needs

If Claude starts proposing a fix you've already rejected, check the session before adding another explanation. Run this inside Claude Code:

/context

The answer might be a crowded window, but it could be a caller Claude never read, an assumption carried over from another task, or a requirement that only exists in chat. I wouldn't diagnose all of those as a context limit.

The useful first step is to separate what fits in the session from what the task actually needs.

Check the window your session has

Claude Code's context includes instructions, conversation history, file contents it has read, and tool responses. Your latest prompt is only part of it. Anthropic's context-window guide documents /context as the way to inspect the live breakdown and find suggestions for reducing its size.

Don't assume every session has the same ceiling.

The current model configuration docs describe both 200K and 1M configurations, depending on your model and account, with provider differences too, so run /model to check the selection, then /context to inspect the session itself.

Before asking Cursor to change a shared authentication helper, ask it to find a caller outside that helper's package. Pick one you already know exists. If the answer misses it, check which folders are open, inspect the exclusions, and get that lookup working before asking for edits.

I'd use that as the first test of a large-repo setup. A plausible explanation of the helper isn't enough to plan a change to its consumers.

What Cursor indexes now

Cursor's current search documentation describes Instant Grep, an automatically used search engine with a local index, alongside Explore, a subagent with its own context window, so broader investigations can happen separately. Cursor says it doesn't store codebase embeddings for search.

That changes the indexing advice worth following. Old instructions about waiting for a semantic index, uploading chunks, or forcing a full reindex don't match the current search page, which says Cursor doesn't upload file paths or code to build a search index, so I'd start by testing whether a known reference is discoverable.

Local indexing also says little about the rest of the request. When Agent opens a match, its contents can enter the model request, as the same documentation explains.

Check the

The interesting question is what happens after the first index. You edit something, switch branches, close your agent, and eventually a teammate asks a question against their own checkout. Which version of the code are they asking about?

Codebase intelligence gives a developer or an AI agent facts about how a repository fits together, including which functions call each other, what a module depends on, what a change touches, and which code appears unused. A text match can point you toward an implementation. The extra question is how that implementation connects to the rest of the system, with enough evidence to check the answer before changing it.

Which kind of tool do you need?

I'd start with the question you're stuck on. These layers stack, so you can keep formatting checks, run a security scanner, review a patch with AI, and give your coding agent a map of the repository before it edits anything.

Linters and formatters answer whether code follows the syntax and style rules you've configured. They don't establish the consequences of changing a shared function, and if the last problem you hit was inconsistent formatting, I'd fix that directly, without making it a reason to install a

Before changing an authorization helper, ask your agent to identify its production callers. If it can explain the function, describe its arguments, and suggest a replacement, but can't show which endpoint reaches it, hold the edit. You have enough context to discuss the implementation. You haven't yet checked the change against the rest of the repository.

Full context means enough evidence for this task and a way to find what you haven't read. Trying to hand over every file is a different job.

I build Pharaoh, so I have a preference for queryable code relationships. But I would still start with a small instruction file and the search tools already in your editor, because a new context service is a poor first answer to a missing test command, an unclear task, or a file you already know how to find.

Choose context by the question you need answered

Instruction files, repository packs, search results, and code graphs give an agent different kinds of evidence. Use this as a starting decision, then check the result on your own task.

A plan to add a helper is hard to trust when Claude hasn't looked for an existing one. Before giving it more files, ask it to show where it searched, which implementation it found, and why that implementation doesn't fit.

That's where I'd start. If an instruction didn't load, check that first, then separate unanswered questions about callers from the revision problem, because an answer about the wrong checkout is a different thing to review.

Check what Claude actually loaded

Claude Code has native tools for finding and reading code, so ask it to investigate, show what it found, explain where it stopped, and let you review the evidence before adding another service.

Check instructions too. Anthropic documents that CLAUDE.md files in the working directory and its ancestors load at launch, nested files in subdirectories load once Claude reads, writes or edits a file there, project instructions guide the model, and they don't enforce rules mechanically. See how Claude Code loads project instructions.

In an active session, run:

/context

Look under Memory files to confirm which instruction files loaded at launch. A CLAUDE.md in a subdirectory doesn't appear there, because it loads on demand; when it loads, the