Python AST analysis tools for Claude Code CLI.
Claude AST provides tools for analyzing Python code structure using the Abstract Syntax Tree (AST). It helps Claude understand code at a deeper level than text-only analysis allows.
- Variable usage analysis (track definitions and references)
- Code unit analysis (functions, methods, classes with complexity metrics)
- Integration with Claude Code CLI
# Install from PyPI
pip install claude-ast
# Register with Claude Code
claude extension add claude-astOnce installed, you can use the tools directly in Claude Code:
# Analyze variables in the current file
/analyze-variables
# Analyze variables in a specific file
/analyze-variables file_path=path/to/file.py
# Filter variables by scope
/analyze-variables file_path=path/to/file.py scope=function_name
# Get JSON output for LLMs
/analyze-variables file_path=path/to/file.py format=json
# Analyze code units
/analyze-units file_path=path/to/file.py
# Analyze units with minimum complexity
/analyze-units file_path=path/to/file.py min_complexity=5
# Filter units by type
/analyze-units file_path=path/to/file.py type=method
Claude AST provides a standalone command-line interface with flexible output formats:
# Show help
claude-ast --help
# Analyze variables in a file
claude-ast variables path/to/file.py
# Filter variables by scope or name
claude-ast variables path/to/file.py --scope function_name
claude-ast variables path/to/file.py --variable var_name
# Output formats for variables
claude-ast variables path/to/file.py --compact # Human-friendly compact format
claude-ast variables path/to/file.py --json # JSON format for LLMs/tools
# Analyze code units in a file
claude-ast units path/to/file.py
# Filter units by type, parent, or complexity
claude-ast units path/to/file.py --type method
claude-ast units path/to/file.py --parent ClassA
claude-ast units path/to/file.py --min-complexity 5
# Output formats for units
claude-ast units path/to/file.py --compact # Human-friendly compact format
claude-ast units path/to/file.py --json # JSON format for LLMs/toolsYou can also use the library programmatically:
from claude_ast import parse_code, analyze_variables, analyze_code_units
# Parse code into AST
code = "def hello(): x = 1; print(x)"
tree, module = parse_code(code)
# Analyze variables (optional filters)
variables = analyze_variables(tree, code)
filtered_vars = analyze_variables(tree, code, variable_name="x", scope="hello")
# Analyze code units (optional filters)
units = analyze_code_units(tree, code)
filtered_units = analyze_code_units(tree, code, unit_type="function", min_complexity=2)
# Access the analysis results
for scope_name, scope_vars in variables.items():
for var_name, var in scope_vars.items():
print(f"{var_name}: {len(var.definitions)} definitions, {len(var.references)} references")
for name, unit in units.items():
print(f"{name} ({unit.type}): complexity {unit.complexity}")
if unit.dependencies:
print(f"Dependencies: {', '.join(unit.dependencies)}")Claude AST provides multiple output formats to meet different needs:
Detailed formatting with Markdown-compatible output for terminal display.
Condensed output for quicker scanning at the command line. Use with --compact flag.
Machine-readable format for integration with other tools or LLMs. Use with --json flag.
{
"function_name": {
"var_name": {
"definitions": 1,
"references": 2,
"value": "initial_value",
"type": "int"
}
}
}# Clone the repository
git clone https://github.com/yourusername/claude-ast.git
cd claude-ast
# Create and activate virtual environment with uv (recommended)
uv venv
source .venv/bin/activate
# Install development dependencies
uv pip install -e ".[dev]"
# Run tests
pytestWe recommend using uv for Python environment management as it provides faster dependency resolution and installation.
MIT