Skip to main content

FastAST

High-performance Codebase-Memory Engine (AST → Graph → Retrieval) for AI coding agents.

License: Apache-2.0 Version: 0.2.0 Language: Rust + Python Model Context Protocol Database: SQLite WAL

FastAST equips AI coding agents (Claude Code, Cursor, Codex, Windsurf, and SWE-bench harnesses) with fast, local, deterministic repository memory across 9 languages:

  1. Multi-Language AST Extraction: Parses source files with compiled Rust Tree-Sitter grammars to extract declarations, signatures, docstrings, imports, and call sites.
  2. Persistent Code Graph: Stores normalized symbols and confidence-weighted relationships (calls, imports, defines, inherits) in a local SQLite WAL database (.fastast.db).
  3. 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.
  4. Structural Similarity & Community Clustering: Detects near-duplicate code via MinHash + LSH and discovers cohesive architectural modules via Louvain modularity clustering.
  5. Agent-Native CLI & MCP Server: Exposes identical capabilities via the fastast CLI, Python API, and fastast-mcp stdio 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.sh or cd 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 --json for structured agent automation (returning standardized results, meta, and error fields).


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 (PathTraversalError on escapes) and enforce a 10 MB file size cap.
  • Concurrency & Locking: Atomic .fastast.lock with PID liveness checks, automatic stale lock reclamation, and SQLite busy_timeout = 15000 ms.
  • Self-Healing DB: Automatic PRAGMA quick_check verification; corrupt databases are safely backed up and rebuilt.
  • Configuration: Supports .fastastrc.json or 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

  1. 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, and SIMILAR_TO relations.
    • 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.
  2. Explore (/explore): Tri-panel file navigator, bounded code snippets with syntax highlighting, omission indicators, and focus symbol inspection.
  3. Architecture (/architecture): Visual technical blueprint of the 7-layer engine pipeline.
  4. Evidence Retrieval (/evidence): Token-budgeted semantic search with instant JSON evidence bundle export for AI coding agents.
  5. Index Coverage (/coverage): Multi-language breakdown across all 9 supported languages.
  6. Louvain Clusters (/communities): Architectural modularity inspection ($Q=0.82$) and subsystem peer symbol drill-down.
  7. 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)

Source distribution for fastast 0.2.0
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)

Table of built distributions (wheels) for fastast 0.2.0
File Actions
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 log

Release 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 log

Release 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 log

Release 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 log

Release 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 log

Release 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 log

Security 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.

Select from 6 files

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 log

A 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.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page