jahala/tilth

tilth – Smart code‑reading for humans and AI agents

What it is – tilth is a single‑binary command‑line tool (and an MCP server) that parses source code with tree‑sitter and lets you query the structure of a codebase without building an index. It can show where symbols are defined, who calls them, what a file depends on, and even give a function‑level diff between commits.

Why it matters for AI agents – Large language models often resort to a chain of cheap tools (glob → grep → read) to locate a function, then have to read many files to discover callers or dependencies. tilth does the heavy lifting in one step: it understands the syntax tree, so agents get precise definitions, call‑graphs, and file‑level outlines instantly, reducing the number of tool calls and the chance of false positives from plain text search.

---

Core capabilities

Feature	What you get
File outline / section view	Small files are printed whole; large files return a structural outline with line‑range blocks. Use --section to fetch a specific range or markdown heading.
Symbol search	tilth <symbol> --scope <dir> finds definitions first, then usages, showing surrounding code snippets. --expand adds the source of top matches; --full raises the match limit.
Callers & callees	--callers lists every call site (structurally, not just text matches). Expanded definitions include a -- calls -- footer with the functions they invoke.
File‑level dependencies	tilto <file> --deps reports what the file imports/uses and which other files import it – handy before refactoring.
grok	One‑shot command that returns a symbol’s signature, doc comment, body, its callees, callers, siblings and associated tests.
Structural diff	tilth diff <commit> shows added/removed/changed functions with line numbers, not just raw diffs.
MCP server mode	Exposes the same functionality over the MCP protocol so AI agents (Claude‑code, Cursor, Gemini, etc.) can call tilth_search, tilth_deps, tilth_grok, etc., directly from their toolchain.
Edit mode	With --edit the server also offers tilth_write/tilth_read that edit files safely using hash‑anchored line references.

---

Typical use cases

• AI‑assistant tooling – plug tilth into Claude‑code, Cursor, or any MCP‑compatible agent to let the model ask “who calls ServeHTTP?” or “what changed in recovery.go?” without writing custom scripts.
• Developer navigation – quickly locate a function definition, see its call graph, or understand a file’s outward dependencies from the terminal.
• Code review & refactoring – generate a function‑level diff between commits, or verify that a rename won’t break callers.
• Large codebases – works on projects with thousands of files (FastAPI, Gin) in tens of milliseconds because it walks the syntax tree in parallel.

---

Installation & getting started

# via Rust’s package manager
cargo install tilth
# or a one‑off binary with npm (bundles the compiled binary)
npx tilth

Pre‑built binaries are also available on the GitHub releases page.

To run as an MCP server (the mode most agents use):

tilth --mcp            # start the server
# install a client config for an agent, e.g.
tilth install claude-code   # writes ~/.claude.json

The server can be started with --edit to enable safe file‑editing capabilities.

---

Architecture at a glance

• Language parsing – uses tree‑sitter (17 supported languages) to build an in‑memory syntax tree for each file. No type resolution, only structural analysis.
• Search engine – combines tree‑sitter queries (for definitions, callers, callees) with ripgrep crates for plain‑text/regex/glob searches.
• Parallelism – directory walking (ignore crate) and symbol look‑ups are parallelised with rayon, giving sub‑100 ms response times on medium‑size repos.
• Caching – an outline cache (via DashMap) is invalidated when a file’s modification time changes, keeping repeated queries fast.
• Zero runtime dependencies – the binary is pure Rust (~35 k lines) and makes no network calls, ensuring all code stays local.

---

Limitations

• No type inference – tilth works purely on syntax; it cannot resolve generic types or overloads.
• Name‑only matching for callers – if two functions share a name in different modules, callers may be ambiguous.
• Language coverage – only languages with a tree‑sitter grammar are fully supported; others fall back to plain text search.
• Dynamic dispatch – functions invoked via reflection or runtime code generation are not detected.

---

License & community

• License: MIT – permissive, suitable for commercial and open‑source projects.
• Support: The author accepts donations via Buy‑Me‑A‑Coffee; issues and feature requests are handled on GitHub.

---

TL;DR

tilth gives AI agents (and developers) a fast, index‑free, syntax‑aware view of a codebase: search definitions, trace call graphs, inspect file dependencies, and see function‑level diffs—all from a tiny Rust binary or an MCP server. It bridges the gap between raw grep‑style tools and heavyweight language servers, making code‑understanding tools more efficient and reliable.