leta

name

leta

description

Fast semantic code navigation via LSP. Load FIRST before ANY code task - even 'simple' ones. Trigger scenarios: (1) fixing lint/type/pyright/mypy warnings or errors, (2) fixing reportAny/reportUnknownType/Any type errors, (3) adding type annotations, (4) refactoring or modifying code, (5) finding where a function/class/symbol is defined, (6) finding where a symbol is used/referenced/imported, (7) understanding what a function calls or what calls it, (8) exploring unfamiliar code or understanding architecture, (9) renaming symbols across codebase, (10) finding interface/protocol implementations, (11) ANY task where you'd use ripgrep to find code or read-file to view a function. Use `leta show SYMBOL` instead of read-file, `leta refs SYMBOL` instead of ripgrep for usages, `leta grep PATTERN` instead of ripgrep for definitions, `leta files` instead of list-directory.

Leta - LSP Enabled Tools for Agents

Leta provides fast semantic code navigation using Language Server Protocol. Unlike text-based search tools, Leta understands code structure and can find symbol definitions, references, implementations, and more.

⚠️ STOP AND THINK - Default to leta

After loading this skill, leta should be your DEFAULT tool for code exploration, not ripgrep-like tools or file reading.

Before you act, check this list:

If you're about to...	STOP! Instead use...
Use read-file to view a function/class you know the name of	leta show <symbol_name>
Use read-file with specific start and end line ranges to view a specific function	leta show <symbol_name>
Use read-file to "browse" or "understand" a file	leta grep ".*" "path/to/file" -k function,method to list functions, or leta show <symbol>
Use ripgrep-like tools to find where a function is defined	leta grep "<function_name>" -k function,method
Use ripgrep-like tools to find usages/references of a symbol	leta refs <symbol_name>
Use ripgrep-like tools to see where a function is imported/wired up	leta refs <symbol_name>
Use ripgrep-like tools to find code related to a concept (e.g. "billing")	leta grep "<concept>" -k function,method
Use list-directory to explore project structure	leta files
Manually search for interface implementations	leta implementations <interface>
Grep for function calls to trace code flow	leta calls --to/--from <function>
Read a function's implementation to understand what it depends on	leta calls --from <function> first for overview
Read multiple files to understand how functions connect	leta calls --from <function> to see the call graph

The Golden Rule: If you know the symbol name, always use leta. Only use ripgrep when searching for things that aren't symbols (string literals, comments, config values).

DON'T fall back to old habits. If you know a symbol name, use leta.

⚠️ Anti-pattern: "Browsing" Files

Don't read a whole file just "to understand it" or "see the context." This is a common mistake.

If you're tempted to do this, ask yourself: What symbol am I actually looking for? Then use:

• leta show <symbol> if you know the symbol name
• leta grep ".*" path/to/file -k function,method to see what functions exist in a file
• leta refs <symbol> to find where something is used

⚠️ Anti-pattern: "I want to see where this is imported/wired up"

When you think "I want to see where this function is imported" or "how is this view wired into URL routes" - that's just finding references! Don't use ripgrep to search for the function name. Use:

• leta refs <function_name> - shows imports, URL configs, everywhere it's used

When to Use leta vs ripgrep-like tools

Use leta for:

• Finding where a function/class/method is DEFINED
• Finding all USAGES of a symbol
• Understanding call hierarchies (what calls what)
• Finding interface implementations
• Semantic refactoring (rename symbol across codebase)
• Exploring project structure with symbol information
• Viewing a symbol's implementation when you know its name

Use ripgrep-like tools for:

• Searching for literal strings in comments, docs, or config files (not code)
• Multi-word phrase search in non-code content
• Searching for library/external symbols not defined in your code
• Pattern matching in string literals or configuration
• Searching in file types leta doesn't understand (markdown, yaml, etc.)

Don't use ripgrep-like tools for:

• Finding where a function/class is defined → use leta grep
• Finding where a symbol is used → use leta refs
• Finding code related to a concept (e.g. "billing", "auth") → use leta grep "<concept>" -k function,method

Quick Start

Before using leta on a new project, add it as a workspace:

leta workspace add /path/to/project

Core Commands

leta show - View Symbol Definition ⭐ USE THIS INSTEAD OF READ-FILE

This is the killer feature you should use constantly. Print the full body of a function, class, or method. ALWAYS use this instead of read-file when you know the symbol name.

# Show a function
leta show handle_request

# Show a method on a class
leta show UserRepository.add_user

# Show with surrounding context
leta show parse_config -n 5

# Limit output length
leta show COUNTRY_CODES --head 50

Symbol formats:

• SymbolName - Find by name
• Parent.Symbol - Qualified name (Class.method)
• path:Symbol - Filter by file path
• path:Parent.Symbol - Path + qualified name

leta grep - Find Symbol Definitions

Search for symbols matching a regex pattern. Only searches symbol NAMES, not file contents. Use this instead of ripgrep-like tools when looking for where something is defined.

leta grep PATTERN [PATH_REGEX] [OPTIONS]

The optional PATH_REGEX argument filters files by matching a regex against the relative file path.

# Find all functions/methods starting with "test"
leta grep "^test" -k function,method

# Find a class and show its documentation
leta grep "UserRepository" -k class -d

# Find all methods in a specific file
leta grep ".*" "server\.py" -k method

# Find symbols in Python files only
leta grep "validate" '\.py$' -k function

# Find symbols in a specific directory
leta grep "User" "models/"

# Find symbols in test files
leta grep "test" "test/"

# Find public Go functions (capitalized)
leta grep "^[A-Z]" '\.go$' -k function -C

Options:

• -k, --kind TEXT - Filter by kind: class, function, method, variable, constant, interface, struct, enum, property, field, constructor, module, namespace, package, typeparameter
• -d, --docs - Include documentation/docstrings
• -x, --exclude TEXT - Exclude files matching regex (repeatable)
• -C, --case-sensitive - Case-sensitive matching. Note that leta grep is case-insensitive by default
• --head N - Maximum results to return (default: 200)

leta files - Project Overview

Show source file tree with line counts. Good starting point for exploring a project. Always prefer leta files over list-directory-like tools since it prints not just the filenames, but a full tree of files (excluding .git, __pycache__, etc.), and their sizes and line counts. If you believe this command will output too many tokens, you can pipe it through | head -n1000 for example.

# Overview of entire project
leta files

# Only show src/ directory
leta files src/

# Exclude test directories (regex pattern)
leta files -x test -x vendor

# Only show Python files
leta files -f '\.py$'

leta refs - Find All References ⭐ USE THIS INSTEAD OF RIPGREP FOR USAGES

This is the correct way to find where a symbol is used. Don't use ripgrep to search for a function name - use leta refs instead. It understands code structure and won't give you false positives from comments or similarly named symbols.

# Find all usages of a function
leta refs validate_email

# Find with context lines
leta refs UserRepository.save -n 2

# Find where a class is instantiated or referenced
leta refs UserRepository

leta calls - Call Hierarchy ⭐ USE THIS TO UNDERSTAND FUNCTION DEPENDENCIES

Before reading a function's implementation, use calls to get the architectural overview. This shows you what a function depends on or what depends on it - much faster than reading code to figure out the call graph.

# What does main() call? (understand dependencies before reading code)
leta calls --from main

# What calls validate_email()? (find all callers)
leta calls --to validate_email

# Find path from one function to another
leta calls --from main --to save_to_db

# Include stdlib/dependency calls
leta calls --from process_request --include-non-workspace

When to use calls:

• You found a function and want to understand what it does at a high level → --from
• You want to know where/how a function is used → --to
• You're tracing data flow through a system → combine --from and --to
• You want to understand the architecture before diving into implementation details

leta implementations - Find Implementations

Find all implementations of an interface or abstract method.

# Find all classes implementing Storage interface
leta implementations Storage

# Find implementations of a specific method
leta implementations Validator.validate

leta supertypes / leta subtypes - Type Hierarchy

Navigate class inheritance.

# What does this class extend/implement?
leta supertypes MyDatabaseStorage

# What classes extend this one?
leta subtypes BaseHandler

leta declaration - Find Declaration

Find where a symbol is declared (useful for variables, parameters).

leta declaration config_path

Refactoring Commands

leta rename - Rename Symbol

Rename a symbol across the entire workspace. Updates all references.

# Rename a function
leta rename old_function_name new_function_name

# Rename a method
leta rename UserRepository.add_user create_user

leta mv - Move File and Update Imports

Move/rename a file and update all import statements.

leta mv src/user.ts src/models/user.ts

Common Workflows

Exploring Unfamiliar Code

# 1. Get project overview
leta files

# 2. Find main entry points
leta grep "^main$\|^Main$" -k function,method

# 3. Trace what main calls
leta calls --from main --max-depth 2

# 4. Find key classes
leta grep "Repository$\|Service$\|Handler$" -k class -d

Understanding a Function

# 1. Get the high-level overview: what does it call?
leta calls --from process_request

# 2. Who calls this function?
leta calls --to process_request

# 3. NOW read the implementation (with context from steps 1-2)
leta show process_request

# 4. Find all usages/references
leta refs process_request

Finding Interface Implementations

# 1. Find the interface
leta grep "Storage" -k interface -d

# 2. Find all implementations
leta implementations Storage

# 3. Look at a specific implementation
leta show FileStorage

Tips

1. Start with leta files to understand project structure before diving in.

2. Use -d flag with grep to see documentation - helps understand what symbols do.

3. Combine with ripgrep-like tools - use leta for "where is X defined/used?" and ripgrep-like tools for "where does string Y appear?"

4. Symbol formats are flexible - if SymbolName is ambiguous, qualify it with path:Symbol or Parent.Symbol.

5. Check workspace first - if commands fail, ensure you've run leta workspace add.

6. Don't redirect stderr (e.g., 2>/dev/null) - when a symbol is ambiguous, leta outputs disambiguation options to stderr showing how to qualify the symbol name. You need to see this to know how to fix the command.