reducethemtokens: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Commands

# Install for development
pip install -e ".[dev]"          # core + test deps

# Run tests
pytest tests/                    # all tests (~0.3s)
pytest tests/test_extractor.py   # single file
pytest tests/ -k "test_python"   # single test by name

# Build and publish
python -m build
twine upload dist/*

# Use the CLI from source
rtt index .
rtt install .

Architecture

The pipeline is: extractor → formatter → CLI/installer.

Data model (rtt/__init__.py)

Three dataclasses flow through everything: Symbol (name, kind, signature, children), FileIndex (path, language, imports, symbols), RepoIndex (list of FileIndex). CompareReport is only used by rtt compare.

Extraction (rtt/extractor.py)

extract_repo() is the main entry point. It walks the directory, calls _extract_file() per file, applies include/exclude/no_tests filters, then optionally trims to a token budget via _trim_to_budget().

_extract_file() parses with tree-sitter and delegates to language-specific functions (_extract_python_symbol, _extract_js_symbol, etc). Import extraction is separate from symbol extraction and only captures top-level imports - imports inside function bodies are intentionally excluded.

Language modules (rtt/languages/)

Each module (python_lang.py, javascript_lang.py, etc.) provides extract_fn_signature() and extract_class_signature() - functions that format a tree-sitter node into a readable signature string. Adding a new language means adding a module here, registering it in languages/__init__.py and languages/registry.py, and adding extraction logic in extractor.py.

JS/TS edge cases

Two patterns require special handling in _iter_toplevel_nodes():

1. IIFE wrappers (function($){...})(jQuery) - handled by _iter_js_iife_body()
2. Bare block statements { function foo(){} } - tree-sitter parses these as ERROR or statement_block nodes; children are yielded transparently