FastAST
High-performance Codebase-Memory Engine (AST → Graph → Retrieval) for AI coding agents.
FastAST equips AI coding agents (Claude Code, Cursor, Codex, Windsurf, and SWE-bench harnesses) with fast, local, deterministic repository memory across 9 languages:
- Multi-Language AST Extraction: Parses source files with compiled Rust Tree-Sitter grammars to extract declarations, signatures, docstrings, imports, and call sites.
- Persistent Code Graph: Stores normalized symbols and confidence-weighted relationships (
calls,imports,defines,inherits) in a local SQLite WAL database (.fastast.db). - Hybrid Retrieval & Token-Bounded Evidence: Combines dense semantic embeddings, SQLite FTS5 BM25, and structural graph signals to return compact evidence bundles within a strict token budget.
- Structural Similarity & Community Clustering: Detects near-duplicate code via MinHash + LSH and discovers cohesive architectural modules via Louvain modularity clustering.
- Agent-Native CLI & MCP Server: Exposes identical capabilities via the
fastastCLI, Python API, andfastast-mcpstdio server.
Detailed Specifications: Architecture (
docs/ARCH.md) · Technical Specification (docs/SPEC.md)
Install
Install from PyPI
pip install fastast
Or install from source with Python >= 3.10 and Rust >= 1.70:
git clone https://github.com/iabdullaheqbal/fastAST.git
cd fastAST
pip install .
Verify the installation:
fastast --version
fastast-mcp --version
Interactive Graph Explorer Web UI
Launch the interactive 2D/3D Architecture Graph Explorer in any codebase with a single command:
# Starts local engine and automatically opens the Graph Explorer in your browser:
fastast ui
# Or specify a custom port:
fastast ui --port 4200
Note: The compiled Graph Explorer frontend is pre-bundled directly inside the package. End users do not need Node.js or npm installed. For frontend development, run
./start_ui.shorcd ui && npm run dev.
For editable local development:
pip install -e .
Quick Start
1. Scan & Index a Repository
# Preview admitted repository files and language breakdown
fastast scan .
fastast scan . -L python,rust
# Index repository into .fastast.db (incremental via xxHash3 / SHA-256 + mtime)
fastast index .
fastast index . --force
2. Query Codebase Memory & Evidence
Retrieve ranked symbols, bounded code snippets, and 1-hop graph context within a strict token budget:
# Hybrid retrieval (Dense Semantic + BM25 + graph heuristics)
fastast query "handle_request"
# Retrieve a token-bounded evidence bundle for conceptual or symbol queries
fastast evidence "database connection recovery" --max-tokens 1024
# Choose ranking mode: hybrid (default), semantic, rrf, bm25, or heuristic
fastast query "user authentication" --ranking semantic --limit 3
3. Inspect File Outlines, Snippets & Symbols
# Structural file outline (classes, methods, functions, line spans) without full file dumps
fastast outline python/fastast/indexer.py
# Extract a bounded code snippet around a symbol or line range
fastast snippet "index_repository"
fastast snippet -f python/fastast/db.py --start 1 --end 40
# Search symbol declarations by name, kind, or language
fastast symbols "RetrievalEngine"
fastast symbols "Config" -L python --kind class
4. Trace Call Hierarchy & Graph Neighborhoods
# Inspect inbound callers and outbound callees
fastast calls "index_repository"
# Multi-hop bounded graph neighborhood traversal
fastast graph "RetrievalEngine" --depth 2 --direction both
5. Code Similarity & Architectural Communities
# Find near-duplicate or structurally similar symbols (MinHash + LSH)
fastast similar "handle_request" --min-sim 0.5
# List cohesive functional modules detected via Louvain modularity clustering
fastast communities
fastast community "RetrievalEngine"
6. Diagnostics & Background Watcher
# Verify database integrity, schema version, lock state, and index coverage
fastast doctor .
fastast doctor . --full --clean-locks
# Watch repository for file changes and incrementally re-index
fastast watch .
JSON Mode: Every CLI subcommand supports
--jsonfor structured agent automation (returning standardizedresults,meta, anderrorfields).
MCP Setup
fastast-mcp is a native Model Context Protocol server communicating over stdio JSON-RPC 2.0.
Claude Code
Register FastAST using the Claude CLI:
Model Context Protocol (MCP) Setup
FastAST exposes its core codebase-memory engine over a standards-compliant Model Context Protocol (MCP) JSON-RPC 2.0 server supporting stdio (primary) and SSE/HTTP transports.
Run Command
# Direct Python module invocation
python3 -m fastast.mcp
# Or via FastAST CLI
fastast mcp
# Or SSE transport on custom port
fastast mcp --transport sse --port 4200
1. Cursor IDE
Add to .cursor/mcp.json or user ~/.cursor/mcp.json:
{
"mcpServers": {
"fastast": {
"command": "python3",
"args": ["-m", "fastast.mcp"],
"cwd": "${workspaceFolder}",
"env": {
"PYTHONPATH": "${workspaceFolder}/python"
}
}
}
}
2. VS Code (Official MCP / Continue / Cline)
Add to .vscode/mcp.json:
{
"servers": {
"fastast": {
"type": "stdio",
"command": "python3",
"args": ["-m", "fastast.mcp"],
"env": {
"PYTHONPATH": "${workspaceFolder}/python"
}
}
}
}
Or for Continue (~/.continue/config.json):
{
"experimental": {
"modelContextProtocolServers": [
{
"transport": {
"type": "stdio",
"command": "python3",
"args": ["-m", "fastast.mcp"],
"env": {
"PYTHONPATH": "/path/to/fastast/python"
}
}
}
]
}
}
3. Claude Desktop
Add to claude_desktop_config.json (macOS: ~/Library/Application Support/Claude/claude_desktop_config.json, Linux: ~/.config/Claude/claude_desktop_config.json, Windows: %APPDATA%\Claude\claude_desktop_config.json):
{
"mcpServers": {
"fastast": {
"command": "python3",
"args": ["-m", "fastast.mcp"],
"cwd": "/path/to/repository",
"env": {
"PYTHONPATH": "/path/to/fastast/python"
}
}
}
}
4. Windsurf
Add to ~/.codeium/windsurf/mcp_config.json:
{
"mcpServers": {
"fastast": {
"command": "python3",
"args": ["-m", "fastast.mcp"],
"cwd": "${workspaceFolder}"
}
}
}
5. Zed
Add to ~/.config/zed/settings.json:
{
"context_servers": [
"fastast": {
"command": {
"path": "python3",
"args": ["-m", "fastast.mcp"]
}
}
]
}
Core MCP Tools Reference
| MCP Tool | Typed Inputs | Description |
|---|---|---|
fastast_index_status |
directory_path?: string |
Return current project/index status (idle / indexing / ready / error) + repository file, symbol, and edge metrics. |
fastast_search_symbols |
query: string, kind?: string, path?: string, community?: int, language?: string, limit?: int |
Search symbols across codebase with filters by kind, file path, community, or language. |
fastast_get_evidence |
query?: string, symbol?: string, file_path?: string, start_line?: int, end_line?: int, max_tokens?: int |
Compact, token-bounded evidence bundle or code slices for a symbol or location (never dumps whole files). |
fastast_graph_neighbors |
symbol: string, depth?: int, direction?: string, limit?: int |
Multi-hop neighborhood graph (nodes + confidence-weighted edges) for IDE/globe visualization. |
fastast_list_communities |
limit?: int, directory_path?: string |
List detected architectural communities from Louvain modularity clustering ($Q \approx 0.82$). |
fastast_community_detail |
community_id?: int, symbol?: string, limit?: int |
Detail, modularity metrics, sample files, and peer members of a specific community cluster. |
fastast_similar_symbols |
symbol: string, min_similarity?: float, limit?: int |
Structural near-duplicate clone detection using MinHash ($m=64$) + Locality-Sensitive Hashing. |
fastast_file_outline |
file_path: string, include_snippets?: bool |
Compact skeleton outline of classes, methods, functions, and key definition preview snippets. |
fastast_trigger_index |
directory_path?: string, force?: bool |
Start or re-trigger incremental repository indexing into SQLite symbol graph (.fastast.db). |
(Legacy tool aliases index_repository, query_symbols, retrieve_evidence, get_call_graph, get_file_outline, get_snippet, get_similar_symbols, list_communities, diagnose_repository are also preserved for backward compatibility).
Python API
import fastast
# 1. Index a repository
stats = fastast.index_repository(".")
# 2. Retrieve token-bounded evidence bundle for an agent query
bundle = fastast.retrieve_bundle(
"index_repository",
repo_root=".",
limit=5,
max_tokens=2048,
ranking_method="hybrid",
)
# 3. Inspect structural file outline or bounded snippet
outline = fastast.get_file_outline("python/fastast/indexer.py", repo_root=".")
snippet = fastast.get_snippet("index_repository", repo_root=".")
Architecture Summary
FastAST pairs a native Rust PyO3 extension (fastast._core) with an embedded SQLite WAL store and a Python retrieval/MCP layer:
[AI Agent: Claude Code / Cursor / CLI]
│
▼ (CLI or JSON-RPC stdio)
┌─────────────────────────┐
│ fastast / fastast-mcp │
└────────────┬────────────┘
│
┌───────────┴───────────┐
▼ (Index) ▼ (Query & Evidence)
┌───────────────┐ ┌───────────────────────────────┐
│ Discovery & │ │ Hybrid Retrieval Engine │
│ Rust AST Core │ │ • FTS5 BM25 + Dense Vectors │
│ (Tree-Sitter) │ │ • RRF & Graph Degree Scoring │
└───────┬───────┘ │ • MinHash/LSH & Louvain │
│ │ • Token-Bounded Materializer │
▼ └───────────────┬───────────────┘
┌─────────────────────────────────────┴───────────────┐
│ Local SQLite WAL Store (.fastast.db) │
│ files · symbols · edges · calls · imports │
│ symbols_fts · symbol_embeddings · symbol_similarity │
│ symbol_communities · schema_migrations │
└─────────────────────────────────────────────────────┘
Supported Languages
| Language | Extensions | Extracted Entities |
|---|---|---|
| Python | .py, .pyi, .pyw |
Classes, functions, async functions, methods, docstrings, imports, calls |
| TypeScript / TSX | .ts, .tsx, .mts, .cts |
Interfaces, types, enums, classes, functions, React components, calls |
| JavaScript / JSX | .js, .jsx, .mjs, .cjs |
Classes, functions, arrow functions, methods, React components, JSDoc |
| Rust | .rs |
Structs, enums, traits, impl blocks, functions, modules, macros, calls |
| Java | .java |
Packages, classes, interfaces, enums, records, constructors, methods |
| HTML | .html, .htm, .xhtml |
Semantic elements, IDs, classes, script/stylesheet links |
| CSS | .css |
Rulesets, selectors, media queries, keyframes, @import rules |
| JSON | .json, .jsonc |
Top-level keys, objects, arrays, dependency manifests |
| TOML | .toml |
Tables, arrays of tables, configuration keys, crate/package dependencies |
Operational Safety & Configuration
- Path Containment: All file reads validate canonical containment inside the repository root (
PathTraversalErroron escapes) and enforce a 10 MB file size cap. - Concurrency & Locking: Atomic
.fastast.lockwith PID liveness checks, automatic stale lock reclamation, and SQLitebusy_timeout = 15000ms. - Self-Healing DB: Automatic
PRAGMA quick_checkverification; corrupt databases are safely backed up and rebuilt. - Configuration: Supports
.fastastrc.jsonor environment variables (FASTAST_DB_NAME,FASTAST_MAX_TOKENS,FASTAST_DEFAULT_RANKING,FASTAST_LOG_LEVEL).
FastAST Lens — Interactive Web UI & 3D Globe Graph
FastAST includes FastAST Lens, a dark-theme developer workbench and 3D Codebase Planet visualization built with React, TypeScript, and Three.js based on the Google Stitch Obsidian Kinetic design system.
Key Screens
- Galaxy / Globe Graph (
/globe):- 3D Spherical Topology: AST nodes distributed on an interactive planetary sphere with dark glass core and atmospheric glow.
- Full Orbit & Zoom: Drag to rotate the globe from any angle; mouse wheel to zoom into clusters.
- Great-Circle Relational Arcs: Curved arcs represent
CALLS,IMPORTS,DEFINES,INHERITS, andSIMILAR_TOrelations. - Interactive Node Selection: Clicking any node highlights relational neighbors, projects a target beacon halo, and opens telemetry metrics in the right inspector.
- Louvain Modularity Sectors: Color-coded clustering grouping symbols by architectural subsystems.
- Explore (
/explore): Tri-panel file navigator, bounded code snippets with syntax highlighting, omission indicators, and focus symbol inspection. - Architecture (
/architecture): Visual technical blueprint of the 7-layer engine pipeline. - Evidence Retrieval (
/evidence): Token-budgeted semantic search with instant JSON evidence bundle export for AI coding agents. - Index Coverage (
/coverage): Multi-language breakdown across all 9 supported languages. - Louvain Clusters (
/communities): Architectural modularity inspection ($Q=0.82$) and subsystem peer symbol drill-down. - System & Engine (
/system): SQLite WAL integrity, lock manager, and diagnostic report (fastast doctor).
Running the FastAST UI & Backend
1. Start the FastAST API Server
# Start local REST API bridge (port 4200) with CORS enabled
fastast serve
# or with uv
uv run fastast serve --port 4200
2. Start the Frontend Dev Server
cd ui
npm install
npm run dev
Open http://localhost:5173 in your browser. API requests to /api/* are automatically proxied to http://127.0.0.1:4200.
3. Convenient Root Command
# Launch UI from root directory
npm run ui
Development & Testing
# Run the complete test suite
for f in tests/test_*.py; do
PYTHONPATH=python python3 "$f"
done
License
Licensed under the Apache License, Version 2.0.
Metadata
Release files for fastast 0.2.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| fastast-0.2.0.tar.gz | 703.6 kB | With provenance | Details for fastast-0.2.0.tar.gz |
Built distributions (wheels)
| File | Actions Reset | |||
|---|---|---|---|---|
| fastast-0.2.0-cp310-abi3-win_amd64.whl | CPython 3.10 | abi3 | Windows x86-64 | Details for fastast-0.2.0-cp310-abi3-win_amd64.whl |
| fastast-0.2.0-cp310-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl | CPython 3.10 | abi3 | Linux glibc 2.17+ x86-64 | Details for fastast-0.2.0-cp310-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl |
| fastast-0.2.0-cp310-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl | CPython 3.10 | abi3 | Linux glibc 2.17+ ARM64 | Details for fastast-0.2.0-cp310-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl |
| fastast-0.2.0-cp310-abi3-macosx_11_0_arm64.whl | CPython 3.10 | abi3 | macOS 11.0+ ARM64 | Details for fastast-0.2.0-cp310-abi3-macosx_11_0_arm64.whl |
| fastast-0.2.0-cp310-abi3-macosx_10_12_x86_64.whl | CPython 3.10 | abi3 | macOS 10.12+ x86-64 | Details for fastast-0.2.0-cp310-abi3-macosx_10_12_x86_64.whl |
Total release size: 14.9 MB
Release files / fastast-0.2.0.tar.gz
| Download URL | fastast-0.2.0.tar.gz |
|---|---|
| Size | 703.6 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
f3f7ea7f67ca0a1c974b181e73257b1ee83c6362834ca67670a5556f3bd17a7e
|
|
BLAKE2b-256 checksum How to use checksums |
b950c63adc425754f4ffce6a51e56e3b818ec7f5482526cf36b578e6e23b4c73
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 25, 2026.
Transparency logRelease files / fastast-0.2.0-cp310-abi3-win_amd64.whl
| Download URL | fastast-0.2.0-cp310-abi3-win_amd64.whl |
|---|---|
| Size | 2.8 MB |
| Tags | CPython 3.10 Windows x86-64 abi3 |
|
SHA-256 checksum How to use checksums |
915da4d99f4a8752f8d2e99c3c52d53a1302939ecabd80d085d740882218c205
|
|
BLAKE2b-256 checksum How to use checksums |
0709b01fb1d2f96468672dff416ee0f8ac3ac0221958c90be5265c369e4f08a1
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 25, 2026.
Transparency logRelease files / fastast-0.2.0-cp310-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
| Download URL | fastast-0.2.0-cp310-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl |
|---|---|
| Size | 2.9 MB |
| Tags | CPython 3.10 Linux glibc 2.17+ x86-64 abi3 |
|
SHA-256 checksum How to use checksums |
5b0003771ffa27b473fb7cc38a910dad882175a542f647ba63e6304d7b1810d2
|
|
BLAKE2b-256 checksum How to use checksums |
bc4623c32f23be6cddacb8c0e2961c0d445de7b2e6e55441d9c36bfa27876964
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 25, 2026.
Transparency logRelease files / fastast-0.2.0-cp310-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
| Download URL | fastast-0.2.0-cp310-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl |
|---|---|
| Size | 2.8 MB |
| Tags | CPython 3.10 Linux glibc 2.17+ ARM64 abi3 |
|
SHA-256 checksum How to use checksums |
275f6748bf209a417a832e95e60a95d5c943e221a2e09bd2db9c3baa36a05b44
|
|
BLAKE2b-256 checksum How to use checksums |
cb25a290701657099e9ae854404039d244b0e5cb6f5b81f613fea55edd2a775d
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 25, 2026.
Transparency logRelease files / fastast-0.2.0-cp310-abi3-macosx_11_0_arm64.whl
| Download URL | fastast-0.2.0-cp310-abi3-macosx_11_0_arm64.whl |
|---|---|
| Size | 2.8 MB |
| Tags | CPython 3.10 abi3 macOS 11.0+ ARM64 |
|
SHA-256 checksum How to use checksums |
7834f8458a646bd778294912f9d67a7414e947d2569a1154d96fb7fba32e489c
|
|
BLAKE2b-256 checksum How to use checksums |
a620d74af36f270b63f2ccfccc99f292a936667fdc14590b53cb031bb7c0fd7d
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 25, 2026.
Transparency logRelease files / fastast-0.2.0-cp310-abi3-macosx_10_12_x86_64.whl
| Download URL | fastast-0.2.0-cp310-abi3-macosx_10_12_x86_64.whl |
|---|---|
| Size | 2.8 MB |
| Tags | CPython 3.10 abi3 macOS 10.12+ x86-64 |
|
SHA-256 checksum How to use checksums |
5c0002165abf5f955b057f10e05f7ddd0108185ed6ebcd5c5c73a105beeed084
|
|
BLAKE2b-256 checksum How to use checksums |
643e7e776f0f6f875b629702d693633e55e38a7e7f8de573c4f519e08eaad1af
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 25, 2026.
Transparency logSecurity for fastast 0.2.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
All 6 files in this release have been uploaded with provenance metadata.
Attestation for fastast-0.2.0.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 25, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.