# ty-find

> Type-aware Python code navigation — powered by ty's LSP server.

ty-find is a CLI tool (`tyf`) for Python code navigation. Unlike grep, it understands
your code's type structure: it finds actual symbol usages (not string matches
in comments or docs), resolves definitions through imports, and shows type
signatures. It talks to ty's LSP server behind the scenes, but you don't need
to know anything about LSP to use it.

First command takes 1-2s (LSP startup); subsequent ones are 50-100ms thanks to
a daemon that keeps connections warm.

## Commands

### inspect — Definition, type signature, and usages of a symbol by name

The most useful command. Given a symbol name, it shows:
- Where it's defined (file + line)
- Its type signature and documentation
- Optionally, every place it's used

No file path needed — it searches the whole project by name.

```
tyf inspect MyClass
tyf inspect calculate_sum UserService       # multiple symbols at once
tyf inspect MyClass --references            # also list all usages
tyf inspect MyClass --file src/models.py    # narrow to one file
tyf --format json inspect MyClass           # JSON output for scripting
```

### find — Find where a symbol is defined by name

Given a symbol name, returns the file and line where it's defined.
Searches the whole project — no need to know which file it's in.
Use `--fuzzy` for partial/prefix matching with richer output (kind + container).

```
tyf find calculate_sum
tyf find calculate_sum multiply divide      # multiple symbols at once
tyf find handler --file src/routes.py       # narrow to one file
tyf find handle_ --fuzzy                    # fuzzy/prefix match
```

### refs — All usages of a symbol across the codebase

Find every location in the codebase that references a symbol. Supports both
name-based and position-based lookup. Essential before renaming or removing
code — tells you exactly what will break.

```
tyf refs my_func my_class                   # by name
tyf refs -f myfile.py -l 10 -c 5           # by position
tyf refs file.py:10:5 my_func              # mixed
... | tyf refs --stdin                      # piped input
```

### members — Public interface of a class

Shows the public interface of a class: methods with signatures, properties,
and class variables with types. Like `list` scoped to a class, with type info.
Excludes private/dunder members by default; `--all` includes everything.
Only shows directly-defined members, not inherited ones.

```
tyf members MyClass
tyf members MyClass UserService          # multiple classes at once
tyf members MyClass --all                # include __init__, __repr__, etc
tyf members MyClass --file src/models.py # narrow to one file
```

### list — All functions, classes, and variables defined in a file

Shows all functions, classes, and variables defined in a file — like a table
of contents. Useful for getting an overview of a file you haven't seen before.

```
tyf list src/services/user.py
```

### daemon — Manage the background server

The daemon starts automatically on first use and shuts down after 5 minutes
of inactivity. You usually don't need these commands.

```
tyf daemon start     # start manually
tyf daemon status    # check if running, uptime, cache info
tyf daemon stop      # stop the daemon
```

## Output Formats

All commands support `--format` (placed before the subcommand):
- `human` — default, readable text with source context
- `json` — structured JSON, good for piping to jq or scripting
- `csv` — tabular, good for spreadsheets or further processing
- `paths` — just file paths, one per line (for xargs, editors, etc.)

```
tyf --format json inspect MyClass
tyf --format paths find calculate_sum | head -1 | xargs code
```

## When to use tyf vs grep

Use **tyf** when you want type-aware, precise results:
- Find where a function/class/variable is actually defined
- Find all actual usages of a symbol (not string matches)
- Get type signatures and documentation
- Understand impact before renaming or deleting code

Use **grep** for non-symbol text:
- String literals, config values, TODOs
- Comments and documentation content
- Non-Python files

## Performance Tips

Install [ripgrep](https://github.com/BurntSushi/ripgrep) (`rg`) to speed up lookups for non-existent symbols. When a symbol isn't found on the first LSP attempt, tyf uses `rg` to quickly check if the symbol text exists in any `.py` file. If not, it skips the retry chain (~3 seconds) and returns immediately.

## Installation

Requires [ty](https://github.com/astral-sh/ty) (`uv add --dev ty`).
Optional: [ripgrep](https://github.com/BurntSushi/ripgrep) for faster non-existent symbol lookups.

```
pip install ty-find
# or
uv add --dev ty-find
```
