The Two Codebase Tools I Tell My Agents to Use

Over the last few months, I have tried many codebase indexing, search and context tools for coding agents. Several produced impressive demos or detailed repository maps. But most quickly disappeared or never made it into my workflow.

Two, however, became permanent agent instructions: Semble and RTK.

My global agent instructions include both tools, but do not prescribe every step:

• use semble first whenever code needs to be located and
• do not bypass RTK when running shell commands.

Everything after that is left to the agent. Agents by now are really good at deciding whether they need more context, an exact text search or a related implementation once they have a useful starting point.

Semble reduces how much code the agent reads while finding the right place. RTK reduces how much terminal output reaches the agent after that.

Semble is the default navigator #

An agent starting work in a repository usually does not know the right filename, symbol or terminology. Standard tools can still get it there, but the common loop is expensive: search broadly, read several files, follow imports and search again.

My instructions therefore say to use Semble first for questions such as “where is this implemented?”, “find usages of this” or “how is this called?” This also applies to cross-repository searches and unfamiliar third-party libraries. Semble is not offered as one optional search tool among several; it is the default entry point.

Semble indexes a repository and returns a small set of relevant snippets with file paths and line numbers. This gives the agent a useful starting point without reading whole files.

The instruction itself is intentionally short:

Use Semble first when locating code, finding usages, exploring third-party libraries or searching across repositories.

That is enough guidance. Semble’s own tool description encourages agents to navigate directly to returned files and lines instead of repeating the same search, while the agent remains free to use find_related, rg, sed or another tool when the next question requires it.

My current Semble statistics show how often the tool gets used:

These numbers are estimates, not a measurement of an API bill. Semble compares the returned snippets with the full contents of the unique files containing those snippets and estimates tokens at four characters each. The useful signal is the difference in context volume: a few focused snippets instead of complete matched files.

RTK filters the shell work after discovery #

RTK is not another code index. It sits between shell commands and the agent, applying command-specific filtering, grouping, truncation and deduplication before output reaches the context window.

My agent environment has RTK’s auto-rewrite hook enabled and a global rule not to bypass it. The agent can issue ordinary shell commands such as git status or rg; the hook rewrites supported commands to their RTK equivalents before execution. Commands I run myself in Nushell are outside that hook, so I add the rtk prefix explicitly when I want the same filtering there.

After Semble returns a file and line, two RTK commands appear frequently, but they do different jobs:

• rtk rg searches for a text or regular-expression pattern and returns matching lines, usually across many files. After Semble has identified the relevant area, rtk rg 'current_user|require_auth' path/to/package can find exact occurrences inside that narrower scope.
• rtk read reads a known file directly and can cap or structurally compress the output when the agent needs more context around a result.

In practice, Semble finds the likely place. rtk read shows the file and rtk rg finds exact text when needed. The agent decides which one to use next.

RTK also filters the noisier steps that follow: Git output, test failures, build logs and other shell commands that often repeat progress or boilerplate.

My RTK statistics for the same seven-day period look like this:

RTK estimates token counts at four bytes per token. The savings percentage measures the reduction in shell output, not a reduction in the overall model bill.

The figures include only commands routed through RTK; raw commands I run in my terminal are not counted. Savings vary with the command mix: a short successful Git command has little noise to remove, while test, build or log output may contain a lot of repetition.

Lightweight enough to leave enabled #

Both tools are lightweight compared with many others I have tried. Some codebase tools maintain heavier repository indexes or services, while change-analysis tools run quality metrics over every diff and add another review result for the agent to process. Those approaches can be useful, but they also add setup, latency and more output.

Semble does build an index, but it runs locally on CPU, caches it and returns small code chunks. RTK is a single binary that filters commands already being run; it does not add a separate analysis step. Neither tries to score the whole change or build a complete repository model as a side effect of normal work.

That makes both easy to keep active globally. They improve frequent operations without turning each agent task into another indexing or code-quality pipeline.

Why the combination works #

Semble and RTK are useful together because they reduce context at different stages:

This is why these tools stayed while more ambitious codebase-context tools did not. Each has a narrow place in the workflow and needs little instruction. Semble is the first choice for locating code; AGENTS.md tells Codex not to bypass RTK, while the hook handles supported shell commands automatically.

Modern agents do not need a detailed decision tree for what happens between those two rules. They can choose the next tool from the result in front of them, while the defaults keep discovery focused and subsequent output compressed.

The Semble and RTK savings should not be added into one headline number. They cover different periods and use different baselines. But both reports point to the same practical result: better codebase context often comes from returning less information at the right time, not from giving the agent a larger representation of the entire repository.

Semble finds the place. RTK keeps the shell work after that focused. The important part is that my agents are instructed to use both before they begin.