jahala/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 (1026 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:
bash
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.
A qualified name such as Engine::handleHTTPRequest or Context.reset finds the definition that type holds, in search and in grok. A qualifier that names a module or package (gin.New, crate::search::symbol::search) finds the function at the top level of that module, and Self::new, self.run or this.handle find the name in whichever type holds it.