ty-find

An LSP adapter for AI coding agents. Symbol name in, structured code intelligence out.

LSP servers are the gold standard for code navigation — but they require file positions (file.py:29:7). LLMs think in symbol names (MyClass). To use an LSP, an LLM first has to grep for the position, which is imprecise and adds a round-trip. tyf bridges this gap: one command gives you definition, signature, and references — by name, no file paths needed.

$ tyf show list_animals
# Definition (func)
main.py:14:1

# Signature
def list_animals(animals: list[Animal]) -> None

# Refs: 2 across 1 file(s)

$ tyf show list_animals --all    # add docs, refs, test refs

Built for: Claude Code, Codex, Cursor, Gemini CLI — and humans who want fast terminal-based navigation.

Why tyf?

vs grep/ripgrep:

• grep matches text — tyf understands Python's type system
• grep returns hits in comments, strings, and docstrings; tyf returns only real symbol references

vs raw LSP (in editors):

• LSP requires file:line:col positions to answer queries
• An LLM doesn't know positions without searching first
• Searching with grep is imprecise — circular problem
• tyf accepts symbol names directly, resolves positions internally

Usage with Claude Code

Add this to your project's CLAUDE.md to enable type-aware code navigation:

### Python Symbol Navigation — `tyf`

This project has `tyf` — a type-aware code search that gives LSP-quality
results by symbol name. Use `tyf` instead of grep/ripgrep for Python symbol lookups.

- `tyf show my_function` — definition + signature (add `-d` docs, `-r` refs, `-t` test refs, or `--all`)
- `tyf find MyClass` — find definition location
- `tyf refs my_function` — all usages (before refactoring)
- `tyf members TheirClass` — class public API
- `tyf calls my_function` — call tree (`--in` for callers, before refactoring)
- `tyf list file.py` — file outline

All commands accept multiple symbols — batch to save tool calls.
Run `tyf <cmd> --help` for options.

Use grep for: string literals, config values, TODOs, non-Python files.

Installation

Prerequisite: ty type checker (uv add --dev ty)

Optional: ripgrep (rg) — speeds up lookups for non-existent symbols by quickly verifying whether a symbol appears in any .py file before retrying LSP queries. Without it, searches for non-existent symbols still work but may be slower.

# macOS
brew install ripgrep

# Ubuntu/Debian
sudo apt install ripgrep

# Or via cargo
cargo install ripgrep

uv add --dev ty-find

Not sure where to start? uvx ty-find guide prints agent-facing instructions (setup, then the command reference) without installing anything or starting the daemon. Inside a project that has it installed, uv run tyf guide does the same.

Note: On Windows, only tyf find --file and tyf guide are supported for now. All other commands require Unix domain sockets (Linux, macOS).

Usage

Show (Definition + Signature + References)

All-in-one command — searches the workspace by symbol name, no file needed. Add -d (docs), -r (references), -t (test refs), or --all for everything:

tyf show calculate_sum

# Multiple symbols at once
tyf show calculate_sum UserService Config

# Include docstring + refs + test refs
tyf show calculate_sum --all

# Narrow to a specific file
tyf show calculate_sum --file src/math.py

Find Symbol by Name

Searches the workspace for a symbol's definition. Supports multiple symbols in a single call. Use --fuzzy for partial/prefix matching with richer output (kind + container):

tyf find calculate_sum

# Find multiple symbols at once (results grouped by symbol)
tyf find calculate_sum multiply divide

# Narrow to a specific file (text-based search + goto_definition)
tyf find function_name --file myfile.py

# Fuzzy/prefix match (returns symbol kind + container info)
tyf find handle_ --fuzzy

Find References

# By position (exact, pipeable from list)
tyf refs -f myfile.py --line 10 --column 5

# By name
tyf refs my_function MyClass

# Mixed and piped
tyf refs file.py:10:5 my_func
... | tyf refs --stdin

Members (Class Public API)

tyf members MyClass

Call Tree

Requires ty 0.0.41 or newer.

# What does this call, transitively? (2 levels by default, max 5)
tyf calls process_order

# Who calls this? (impact analysis before an edit)
tyf calls check_inventory --in

Document Outline

tyf list src/services/user.py

MCP Server

For harnesses that consume MCP servers more easily than a shell command, tyf mcp serves the same lookups over stdio — one tool per lookup command, same parameters, same output (calls is CLI-only for now). It bridges to the same background daemon, so both frontends share one warm index.

claude mcp add tyf -- tyf mcp

Use MCP where your harness makes MCP easier than shell; the CLI remains the primary interface for Claude Code. See docs/src/mcp.md for registration snippets for Codex, Cursor and Gemini CLI, and the full tool surface.

Daemon Management

The daemon starts automatically on first use. Run tyf daemon --help for manual control.

Output Formats

All commands support --format (placed before the subcommand): human (default), json, csv, paths.

tyf --format json show MyClass
tyf --format csv find User --fuzzy

Architecture

CLI Command  ─┐
              ├→ Daemon Client (auto-connects) → Unix Socket
MCP Tool Call ─┘  → Daemon Server (5min idle timeout) → LSP Client Pool → ty LSP Server

The daemon keeps LSP connections warm: first command takes 1-2s, subsequent commands 50-100ms. See How it works for details.

Development

cargo build --release
cargo test
cargo clippy
cargo fmt --check

# Verbose logging
RUST_LOG=ty_find=debug cargo run -- find hello_world

Testing / supported ty versions

tyf does not ship ty — it drives whatever ty LSP server you have installed. ty is 0.0.x and changes frequently, so the integration suite is run in CI against a curated set of pinned, exact ty versions on every push and PR (and on dependabot ty bumps).

The tested floor is 0.0.15 and the current latest tested is 0.0.49. This is a practical baseline, not a hard limit: the suite behaves identically (same output, same ~180ms cold start) across the whole modern range — genuine capability gaps only exist in ty ≤ 0.0.5, which don't return multi-file workspace symbols (0.0.1 has no Linux glibc wheel at all).

The exact list of tested versions is the single source of truth in ci/ty-versions.json; the methodology and per-version findings are in docs/dev/TY_VERSIONS.md.

Troubleshooting

# Check ty is installed
ty --version

# Debug daemon issues
tyf daemon status
RUST_LOG=ty_find=debug tyf daemon start

# Restart daemon
tyf daemon stop && tyf daemon start

Contributing

Contributions welcome! Please open an issue to discuss major changes.

License

MIT License - see LICENSE file for details.

Credits

Built with ty - Astral's Python type checker.