ty-find 0.1.5

CLI tool for finding Python function definitions using ty's LSP server

ty-find

A command-line tool for Python code navigation using ty's LSP server. Uses a daemon-backed architecture to keep LSP connections warm between commands.

Features

• Daemon mode: Keeps LSP connections warm (50-100ms per command after initial startup)
• Type-aware: Uses ty's LSP for accurate symbol resolution
• Multiple commands: hover, definition, references, symbols, outline
• JSON output: Structured output for scripting and integration with other tools
• Auto-daemon: Starts background daemon on first use
• User-isolated: Each user gets their own daemon process

Installation

Prerequisites

• ty type checker: pip install ty

Quick Install (Recommended)

Pre-built wheels are available for Linux and macOS:

# Install from PyPI (coming soon - once first release is published)
pip install ty-find

# Or with uv
uv pip install ty-find

Note: Windows is not currently supported. PRs welcome!

For Python Projects

Add to your pyproject.toml:

# For pip/setuptools projects
[project.optional-dependencies]
dev = [
    "ty-find",  # Once published to PyPI
]

# For uv projects (recommended)
[dependency-groups]
dev = [
    "ty-find",
]

Install from Git (Pre-Release)

Until the first PyPI release, install from Git:

# Requires Rust toolchain to build from source
pip install "ty-find @ git+https://github.com/mojzis/ty-find.git"

# Or with uv
uv pip install "ty-find @ git+https://github.com/mojzis/ty-find.git"

Note: Installing from Git requires the Rust toolchain. Pre-built wheels eliminate this requirement.

From Source (Development)

git clone https://github.com/mojzis/ty-find.git
cd ty-find
cargo install --path .

Usage

Type Information (Hover)

Get type information and documentation at a specific position:

ty-find hover src/main.py --line 45 --column 12

# Output:
Type: UserService
Documentation: Service for managing user accounts
Signature: class UserService(BaseService[User])

# JSON output for programmatic use
ty-find --format json hover src/main.py --line 45 --column 12

Go to Definition

Find where a symbol is defined:

ty-find definition myfile.py --line 10 --column 5

# Output:
Definition: src/services/user.py:15:6
def create_user(name: str, email: str) -> User:

Find References

Find all usages of a symbol across the workspace:

ty-find references myfile.py --line 10 --column 5

# Output:
Found 4 reference(s) for: myfile.py:10:5

1. src/services/user.py:15:6
   def create_user(name: str, email: str) -> User:

2. src/api/routes.py:42:12
   result = create_user(name, email)

3. tests/test_user.py:8:4
   create_user("test", "[e-mail]")

4. tests/test_user.py:22:4
   create_user("other", "[e-mail]")

# JSON output
ty-find --format json references myfile.py --line 10 --column 5

Search Symbols Across Workspace

Search for symbols across your entire codebase:

ty-find workspace-symbols --query "UserService"

# Output:
UserService (class) - src/services/user.py:10:6
UserServiceTest (class) - tests/test_user_service.py:5:6

# JSON output
ty-find --format json workspace-symbols --query "auth"

Document Outline

Get the structure/outline of a file:

ty-find document-symbols src/services/user.py

# Output:
UserService (class)
  ├─ __init__ (method)
  ├─ create_user (method)
  ├─ get_user (method)
  └─ update_user (method)

Find Symbol by Name

Find all occurrences of a symbol in a file:

ty-find find myfile.py function_name

Interactive Mode

REPL-style interface for exploring code:

ty-find interactive
> myfile.py:10:5
> find myfile.py function_name
> quit

Daemon Management

The daemon starts automatically, but you can manage it manually:

# Start daemon (optional - auto-starts on first use)
ty-find daemon start

# Check daemon status
ty-find daemon status
# Output:
# Daemon: running
# Uptime: 5m 23s
# Active workspaces: 2

# Stop daemon
ty-find daemon stop

Output Formats

All commands support multiple output formats via the global --format flag (placed before the subcommand):

# Human-readable (default)
ty-find hover myfile.py -l 10 -c 5

# JSON (for Claude Code, scripts, etc.)
ty-find --format json hover myfile.py -l 10 -c 5

# CSV
ty-find --format csv workspace-symbols --query "User"

# Paths only
ty-find --format paths definition myfile.py -l 10 -c 5

Performance

Without Daemon (Old Approach)

• Each command: 1-2 seconds
• 10 commands: ~15-20 seconds

With Daemon (Current)

• First command: 1-2 seconds (starts daemon + LSP)
• Subsequent: 50-100ms (warm cache)
• 10 commands: ~3 seconds

Usage with Claude Code

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

Code Navigation (ty-find)

Use ty-find for type-aware Python code navigation - more accurate than grep for symbols.

Commands (use relative paths from repo root):

ty-find references path/to/file.py -l LINE -c COL   # Find all usages of symbol
ty-find definition path/to/file.py -l LINE -c COL  # Go to definition
ty-find hover path/to/file.py -l LINE -c COL       # Get type info
ty-find find path/to/file.py SymbolName            # Find symbol by name in file
ty-find workspace-symbols --query "ClassName"      # Search symbols across codebase
ty-find document-symbols path/to/file.py           # Get file outline

When to use:

• Before renaming/refactoring: ty-find references to find all usages
• Understanding unfamiliar code: ty-find hover for type info
• Finding class/function definitions: ty-find workspace-symbols

Output formats: Add --format json before subcommand for programmatic use.

Why ty-find over grep?

Scenario	grep	ty-find
Find symbol usages	Matches in docs, comments, strings	Only actual code references
Rename refactoring	May miss or over-match	Type-aware, precise
Performance	Fast	Fast (daemon-backed, ~10ms)

Architecture

CLI Command
    ↓
Daemon Client (auto-connects)
    ↓
Unix Socket (/tmp/ty-find-{uid}.sock)
    ↓
Daemon Server (auto-started, 5min idle timeout)
    ↓
LSP Client Pool (one per workspace)
    ↓
ty LSP Server (spawned on-demand)

The daemon runs in the background and keeps LSP connections warm, providing fast responses for all subsequent commands.

Examples

Basic Usage

# Get type at cursor position
ty-find hover src/calculator.py --line 25 --column 10

# Find where 'calculate_total' is defined
ty-find find src/calculator.py calculate_total

# Find all usages of the symbol at line 25, column 10
ty-find references src/calculator.py --line 25 --column 10

# Search for all authentication-related symbols
ty-find workspace-symbols --query "auth"

# Get file structure
ty-find document-symbols src/api/routes.py

With Workspace Specification

ty-find hover src/app.py -l 15 -c 8 --workspace /path/to/project

JSON Output for Scripting

# Get symbol information as JSON
ty-find --format json hover src/main.py -l 45 -c 12 | jq '.result.contents.value'

# Find all class definitions
ty-find --format json workspace-symbols --query "" | jq '.results[] | select(.kind == 5)'

Available Commands

Command	Description	Example
hover	Get type information at position	ty-find hover file.py -l 10 -c 5
definition	Go to definition	ty-find definition file.py -l 10 -c 5
references	Find all references to a symbol	ty-find references file.py -l 10 -c 5
workspace-symbols	Search symbols across workspace	ty-find workspace-symbols --query "User"
document-symbols	Get file outline	ty-find document-symbols file.py
find	Find symbol by name in file	ty-find find file.py symbol_name
interactive	Interactive REPL mode	ty-find interactive
daemon start	Start daemon manually	ty-find daemon start
daemon stop	Stop daemon	ty-find daemon stop
daemon status	Check daemon status	ty-find daemon status

Documentation

• Implementation Summary - What was implemented and how
• Daemon Architecture - Technical details of daemon design
• CLI-First Approach - Why CLI over MCP
• Project Roadmap - Future plans

Troubleshooting

Daemon won't start

# Check if ty is installed
ty --version

# Check socket path
ls -la /tmp/ty-find-*.sock

# Try starting daemon manually with verbose logging
RUST_LOG=ty_find=debug ty-find daemon start

Slow responses

# Check daemon status
ty-find daemon status

# Restart daemon
ty-find daemon stop
ty-find daemon start

ty not found

# Install ty
pip install ty

# Verify installation
ty --version

Development

# Build
cargo build --release

# Run tests
cargo test

# Run with verbose logging
RUST_LOG=ty_find=debug cargo run -- hover test.py -l 1 -c 1

# Check code
cargo clippy
cargo fmt --check

Contributing

Contributions welcome! Please:

1. Open an issue to discuss major changes
2. Follow existing code style
3. Add tests for new features
4. Update documentation

License

MIT License - see LICENSE file for details

Credits

• Built with ty - Astral's Python type checker