tilth

Smart code reading for humans and AI agents. tilth parses your code with tree-sitter and answers questions that text search can't. It shows where a symbol is defined, who calls it, what it calls, what depends on a file, and what changed at function level.

tilth is one binary. It works as a command-line tool and as an MCP server, which is how most agent hosts connect to tools. It builds no index and needs no setup.

$ tilth fastapi/dependencies/utils.py
# fastapi/dependencies/utils.py (1027 lines, ~9.6k tokens)

[1-]   imports: dataclasses, inspect, sys
[86-110]     fn ensure_multipart_is_installed
           def ensure_multipart_is_installed() -> None
[113-125]    fn get_parameterless_sub_dependant
           def get_parameterless_sub_dependant(*, depends: params.Depends, path: str) -> Dependant
[128-179]    fn get_flat_dependant
           def get_flat_dependant(
...
[203-215]    fn _get_signature
           def _get_signature(call: Callable[..., Any]) -> inspect.Signature
[218-232]    fn get_typed_signature
           def get_typed_signature(call: Callable[..., Any]) -> inspect.Signature
...

Small files come back whole. Large files come back as an outline with line ranges. Ask for the part you need with --section:

tilth fastapi/dependencies/utils.py --section 218-232
tilth docs/guide.md --section "## Installation"

The examples in this README are real output from the FastAPI and Gin repositories. Lines marked ... are cut for length.

Search finds definitions first

$ tilth get_typed_signature --scope fastapi --expand=1
# Search: "get_typed_signature" in fastapi — 2 matches (1 definitions, 1 usages)

### dependencies/utils.py:218-232 [definition]
  [203-215]    fn _get_signature
             def _get_signature(call: Callable[..., Any]) -> inspect.Signature
-> [218-232]    fn get_typed_signature
             def get_typed_signature(call: Callable[..., Any]) -> inspect.Signature
  [235-241]    fn get_typed_annotation

```dependencies/utils.py:218-232
 218 | def get_typed_signature(call: Callable[..., Any]) -> inspect.Signature:
 219 |     signature = _get_signature(call)
 220 |     unwrapped = inspect.unwrap(call)
 ...
 232 |     return typed_signature
```

-- calls --
  _get_signature  dependencies/utils.py:203-215  def _get_signature(call: Callable[..., Any]) -> inspect.Signature
  get_typed_annotation  dependencies/utils.py:235-241  def get_typed_annotation(annotation: Any, globalns: dict[str, Any]) -> Any

### dependencies/utils.py:277 [usage in function get_dependant]
  [244-253]    fn get_typed_return_annotation
             def get_typed_return_annotation(call: Callable[..., Any]) -> Any
-> [256-328]    fn get_dependant
             def get_dependant(
  [331-352]    fn add_non_field_param_to_dependency

(~439 tokens)

tilth uses the syntax tree to tell a definition from a mention, and it lists definitions first. Each match is shown with the symbols around it, so you can see where you are without reading the file.

An expanded definition ends with a -- calls -- footer. It lists the functions the definition calls, each with its file, line range and signature. An agent can follow a call chain from there without searching again.

When a search finds more than it shows, the header says so, for example 10 of 43 matches. Add --full to raise the limit from 10 to 100.

Expanded search

On the command line, search returns compact results. --expand adds the source of the top matches:

tilth ServeHTTP --scope . --expand       # top 2
tilth ServeHTTP --scope . --expand=5     # top 5

In MCP mode, expand defaults to 2.

Multi-symbol search

Look up several symbols in one call:

tilth "ServeHTTP, HandlersChain, Next" --scope .

Each symbol gets its own block of results. The expand budget is shared across them, with at least one expansion per symbol.

Callers

Find every call site of a symbol. tilth matches calls on the syntax tree, so comments and strings that mention the name are left out.

$ tilth isTrustedProxy --callers --scope .
# Callers of "isTrustedProxy" in ~/gin — 5 call sites

## context.go:1011 [caller: ClientIP]
-> trusted = c.engine.isTrustedProxy(remoteIP)
...
## gin.go:496 [caller: validateHeader]
-> if (i == 0) || (!engine.isTrustedProxy(ip)) {

In MCP mode, use kind: "callers" on tilth_search.

File dependencies

See what a file uses and what uses it. This is worth a look before you rename or remove an export.

$ tilth recovery.go --deps
# Deps: recovery.go — 5 local, 0 external, 3 dependents

## Uses (local)
context.go                     Abort, AbortWithStatus, Error, Next
debug.go                       IsDebugging
fs.go                          Open
gin.go                         New
routergroup.go                 handle

## Used by
benchmarks_test.go:22          BenchmarkRecoveryMiddleware → Recovery
benchmarks_test.go:36          BenchmarkManyHandlers → Recovery
gin.go:239                     Default              → Recovery
recovery_test.go:22            TestPanicClean       → RecoveryWithWriter
...

In MCP mode, use the tilth_deps tool.

Grok a symbol

grok returns everything about one symbol in a single call: signature, doc comment, body, callees, callers, siblings and tests.

$ tilth grok get_typed_signature --scope fastapi
# grok: get_typed_signature [dependencies/utils.py:218]

## signature
def get_typed_signature(call: Callable[..., Any]) -> inspect.Signature

## body
...

## callees (2 internal, 5 extern)
  dependencies/utils.py
    _get_signature       [203-215]   def _get_signature(call: Callable[..., Any]) -> inspect.Signature
    get_typed_annotation [235-241]   def get_typed_annotation(annotation: Any, globalns: dict[str, Any]) -> Any
...

## callers (1)
  dependencies/utils.py
    [277]   in get_dependant()

In MCP mode, use the tilth_grok tool.

Session memory

In MCP mode, a definition that was already expanded comes back as [shown earlier] in later searches. The agent does not receive the same body twice.

Structural diff

$ tilth diff HEAD~1
# Diff: HEAD~1 — 10 files, 10 modified, 9 added (~447 tokens)
...
## binding/bson.go (3 symbols)
  [+]      Name                                     L16  (new, 3 lines)
  [+]      Bind                                     L20  (new, 7 lines)
  [+]      BindBody                                 L28  (new, 3 lines)

## context.go (3 symbols)
  [~]      <const>                                  L31  (body, 13→14 lines)
  [~]      Negotiate                                L1357  (body, 30→34 lines)
  [+]      BSON                                     L1242
...

The diff reports changes per function: what was added, what was removed, and whether a signature or only a body changed. Narrow it with --scope, or summarise a range of commits with --log.

Why

I built tilth after watching AI agents make 6 tool calls to find one function: glob, read, "too big", grep, read again, read another file.

An agent with grep can find where a piece of text appears. To find out who calls a function, it has to read files and work out the answer, and that answer can be wrong without anyone noticing. tilth parses the code and computes the answer. The outline shows what is in a file, search shows where things are defined, and --section returns the lines you asked for.

What it doesn't do

• tilth parses syntax. It does not resolve types.
• Callers and dependencies are matched by name. tilth cannot tell apart two functions with the same name in different modules, and it cannot follow dynamic dispatch.
• A language without a tree-sitter grammar in tilth gets text search and plain file reading only.

Install

cargo install tilth
# or
npx tilth

Prebuilt binaries are on the releases page.

MCP server

tilth install claude-code      # ~/.claude.json
tilth install cursor           # ~/.cursor/mcp.json
tilth install windsurf         # ~/.codeium/windsurf/mcp_config.json
tilth install vscode           # .vscode/mcp.json (project scope)
tilth install claude-desktop
tilth install opencode         # ~/.config/opencode/opencode.json
tilth install gemini           # ~/.gemini/settings.json
tilth install codex            # ~/.codex/config.toml
tilth install amp              # ~/.config/amp/settings.json
tilth install droid            # ~/.factory/mcp.json
tilth install antigravity      # ~/.gemini/antigravity/mcp_config.json
tilth install zed              # ~/.config/zed/settings.json
tilth install copilot-cli      # ~/.copilot/mcp-config.json
tilth install augment          # ~/.augment/settings.json
tilth install kiro             # ~/.kiro/settings/mcp.json
tilth install kilo-code        # VS Code globalStorage (extension)
tilth install cline            # VS Code globalStorage (extension)
tilth install roo-code         # VS Code globalStorage (extension)
tilth install trae             # .trae/mcp.json (project scope)
tilth install qwen-code        # ~/.qwen/settings.json
tilth install crush            # ~/.config/crush/crush.json
tilth install pi               # ~/.pi/agent/mcp.json

Add --edit to turn on hash-anchored file editing (see Edit mode):

tilth install claude-code --edit

For an MCP client that is not in the list, the server entry is the same everywhere. Only the config file location and the top-level key vary (mcpServers for most hosts, amp.mcpServers for Amp, TOML syntax for Codex):

{
  "mcpServers": {
    "tilth": {
      "command": "tilth",
      "args": ["--mcp"]
    }
  }
}

For edit mode, use "args": ["--mcp", "--edit"].

You can also call tilth from a shell. See