quickast 0.3.1

Instant codebase intelligence for AI coding agents. AST-powered symbol index with call graphs, route maps, and live file watching.

QuickAST

AST-powered codebase index for Python, JavaScript, and Markdown.

QuickAST parses your codebase, builds a SQLite index of every symbol, call relationship, import, API route, and documentation section, then keeps it current with automatic file watching.

Installation

pip install quickast

Then navigate to any Python project and build the index:

cd /path/to/your/project
quickast init

Install from source (alternative)

git clone https://github.com/virobit/quickast.git
cd quickast
pip install -e .

Editable mode (-e) means changes to the cloned source take effect immediately without reinstalling.

Upgrading

pip install --upgrade quickast

Or if installed from source:

cd quickast
git pull

What It Does

QuickAST gives you a persistent, queryable index of your codebase:

$ quickast query create_user           # Find where a symbol is defined
  function  app/users.py:45  def create_user(name: str, email: str) -> dict

$ quickast callers-of create_user      # What calls this function?
  app/api.py:112  in handle_signup
  tests/test_users.py:23  in test_create

$ quickast callees create_user         # What does this function call?
  L46  validate_email (method)
  L48  save_record (method)

$ quickast impact create_user          # Transitive dependency chain
  Upstream callers (3): handle_signup, register_endpoint, ...
  Downstream callees (5): validate_email, save_record, ...

Queries return in milliseconds from the SQLite index. No re-parsing, no scanning.

Quick Start

Start the file watcher (optional)

quickast watch              # Foreground (see output, Ctrl+C to stop)
quickast watch --daemon     # Background (frees your terminal)
quickast watch --nice       # Lower CPU priority (nice 10)
quickast watch --debounce 5 # Wait 5s before re-indexing (default: 2s)
quickast stop               # Stop the background watcher

For heavy workloads (AI agents writing many files), combine flags to reduce system impact:

quickast watch --daemon --nice --debounce 5

Check if the watcher is running:

cat .quickast.pid        # Show the watcher's process ID
ps -p $(cat .quickast.pid) -o pid,cmd   # Verify the process is alive

Re-indexes any file you save. The index stays current without manual rebuilds.

Commands

Command	What It Does
quickast init	Build the index for the current project
quickast watch [options]	Start the file watcher (--daemon, --nice, --debounce N)
quickast stop	Stop the background watcher
quickast query <name>	Find where a symbol (function/class/method) is defined
quickast search <pattern>	Search symbols (use % wildcards: %user%, %auth%)
quickast refs <name>	Find all files that import a symbol
quickast file <path>	List all symbols defined in a file
quickast callees <name>	What does function X call?
quickast callers-of <name>	What calls function X?
quickast impact <name> [depth]	Transitive impact analysis (upstream + downstream)
quickast routes [--type TYPE]	List API routes (REST, CLI commands, pages)
quickast route <path>	Find a specific route handler
quickast changes [hours]	Files changed recently (default: 24 hours)
quickast summary <path>	Module overview (symbol counts, top definitions)
quickast docs <query>	Full-text search across indexed markdown documentation
quickast docs list [dir]	List all indexed markdown files
quickast docs sections <file>	Show heading structure of a markdown file
quickast js-files [search <name>]	List JavaScript symbols (classes, functions, methods)
quickast js-files classes	List only JavaScript classes
quickast callbacks	List callback wirings (set_*_callback, on_* patterns)
quickast stats	Index statistics

What Gets Indexed

• Python symbols — Every function, class, and method with full signatures, docstrings, and line numbers
• Call graph — Every function call with caller/callee context (who calls X, what does X call)
• Callback wirings — set_*_callback() and on_* keyword argument patterns
• Imports — Every import statement (which files use module X)
• API routes — FastAPI, Flask, and Click decorator patterns
• Router mounts — include_router() calls with prefix tracking
• JavaScript symbols — Classes, methods, functions, arrow functions, getters, setInterval/setTimeout (regex-based)
• Markdown documentation — Heading hierarchy with parent-child relationships, plus full-text search (FTS5)
• File metadata — Line counts, modification times, file sizes

Capabilities

Feature	Description
Persistent SQLite index	Index once, query instantly — no re-parsing on each lookup
Call graph	Trace callers and callees across the entire codebase
Callback wiring detection	Finds set_*_callback() and on_* keyword patterns
Transitive impact analysis	See the full upstream/downstream dependency chain at any depth
API route map	Automatically detects REST endpoints, CLI commands, page routes, and router mounts
JavaScript indexing	Regex-based extraction of classes, methods, functions, arrow functions, timers
Markdown FTS	Full-text search across documentation with heading hierarchy
Cross-type search	search command queries Python symbols, JS symbols, and doc headings in one call
Live file watching	File watcher re-indexes on save — index stays current
Incremental indexing	Only re-indexes files that changed since the last build
Framework detection	Recognizes FastAPI, Flask, and Click patterns out of the box

Using QuickAST with AI Agents

With Claude Code

Add this to your project's CLAUDE.md:

## Code Index

This project has a QuickAST index. Query it before grepping:

\`\`\`bash
quickast query <name>         # Find symbol definitions
quickast search %keyword%     # Fuzzy search (Python + JS + docs)
quickast callers-of <name>    # Who calls this?
quickast callees <name>       # What does this call?
quickast file <path>          # What's in this file?
quickast impact <name>        # Full dependency chain
quickast routes               # API surface map
quickast docs <query>         # Full-text search in markdown docs
quickast js-files             # JavaScript symbols
quickast callbacks            # Callback wirings
\`\`\`

Always query the index first. Only fall back to grep for string literals,
comments, or config values that aren't in the AST.

With Other AI Tools

QuickAST is a standard CLI tool. Any AI agent that can run shell commands can use it.

How It Works

1. Parse — Uses Python's ast module for .py files, regex patterns for .js files, and heading extraction for .md files
2. Extract — Pulls symbols, imports, call relationships, callback wirings, route decorators, router mounts, JS classes/functions, and markdown headings
3. Store — Writes everything to a SQLite database (.quickast.db) with FTS5 for documentation search
4. Watch — The file watcher uses watchdog to detect changes and re-index modified files
5. Query — The CLI reads from SQLite, returning results in under 1ms

The index is a single .quickast.db file. Add it to .gitignore — it can be rebuilt in seconds.

Supported File Types

Extension	Parser	What Gets Extracted
.py	Python ast module	Symbols, calls, imports, routes, callbacks
.js	Regex patterns	Classes, methods, functions, arrow functions, timers
.md	Heading extraction	Section hierarchy, full-text search content

Configuration

QuickAST automatically excludes common non-source directories:

• venv, .venv, env, .env
• __pycache__, .git, node_modules
• .mypy_cache, .pytest_cache, .tox, .nox
• dist, build, .eggs

Requirements

• Python: 3.10+
• OS: Linux, macOS
• Dependencies: watchdog (for file watching)

No external parsing libraries — QuickAST uses Python's built-in ast module for Python files and regex patterns for JavaScript files.

License

MIT

Running Tests

Tests are in the cloned repo, not in the pip install. You must run them from inside the quickast directory.

git clone https://github.com/virobit/quickast.git
cd quickast
python3 -m venv venv
source venv/bin/activate
pip install -e ".[dev]"    # Installs pytest and pytest-cov
pytest tests/ -v           # Run from inside the quickast directory

All tests should pass. The tests cover Python/JS/Markdown parsing, callback detection, router mount tracking, multi-file-type indexing, incremental builds, and all query types using temporary project directories — no external dependencies or network access required.

Contributing

Contributions welcome. Please open an issue first to discuss what you'd like to change.

Disclaimer

QuickAST is provided "as is", without warranty of any kind, express or implied, including but not limited to the warranties of merchantability, fitness for a particular purpose, and noninfringement. In no event shall the authors or copyright holders be liable for any claim, damages, or other liability, whether in an action of contract, tort, or otherwise, arising from, out of, or in connection with the software or the use or other dealings in the software.

QuickAST performs read-only analysis of your source code using Python's built-in ast module. It does not modify, execute, or transmit your code. The SQLite index is stored locally in your project directory.

This project is in early development. APIs and CLI behavior may change between versions.