FastCode: Accelerating and Streamlining Your Code Understanding

| ⚡ High Performance | 💰 Cost Efficient | 🚀 Fast & Scalable |

Features • Quick Start • Installation • MCP Server • Documentation

FastCode is a token-efficient framework for comprehensive code understanding and analysis: delivering superior speed, exceptional accuracy, and cost-effectiveness for large-scale codebases and software architectures.

🚀 Superior Speed Advantage - Runs 3x faster than Cursor and 4x faster than Claude Code.

💰 Significant Cost Savings - Costs 55% less than Cursor and 44% less than Claude Code.

⚡ Highest Accuracy - Outperforms Cursor and Claude Code with the highest accuracy score.

• 2-4x Faster than competitors (Cursor/Claude Code)
• 44-55% Cost Reduction compared to alternatives
• Highest Accuracy Score across benchmarks
• Up to 10x Token Savings through smart navigation

• Large-Scale Repository Analysis - Handle massive codebases efficiently
• Multi-Language Support - Python, JavaScript, TypeScript, Java, Go, C/C++, Rust, C#
• Multi-Repository Reasoning - Cross-repo dependency analysis
• Small Model Support - Local model compatibility (qwen3-coder-30b)
• Graph-First Dual-Layer Architecture - Knowledge graph as the primary understanding layer, with retrieval augmentation as a secondary layer for implementation details

• MCP Server - Use FastCode directly through MCP integration (e.g., Cursor, Claude Code)
• Beautiful Web UI - Intuitive codebase exploration
• Flexible API - Easy workflow integration
• Smart Structural Navigation - Load only what you need

FastCode introduces a three-phase framework that transforms how LLMs understand and navigate codebases:

FastCode uses a two-layer architecture where the Knowledge Graph is always the primary source of understanding. Retrieval augmentation acts strictly as a secondary supplement — it is not the system center.

How augmentation is controlled:

• GraphAugmentedRetriever triggers only when graph nodes lack real summaries (abstract nodes exceed threshold)
• ContextBudget ensures graph content always gets priority in the context window (default 60% reserved for graph)
• ContextPacker assembles the final prompt with graph section first, retrieval appended only if budget allows
• Query intents explain, diff, and onboard use pure graph paths — augmentation applies only to graph_qa / hybrid_detail / unknown intents
• Current graph build is structurally strongest for Python projects. Other source extensions are still scanned and retained in repository metadata, but graph detail may remain sparse until symbol backends expand beyond the current Python-first AST path.

• Default package runtime: from fastcode import FastCode now resolves to the graph-first facade.
• Legacy escape hatch: from fastcode import LegacyFastCode is still available for rollback and compatibility debugging.
• Build path: graph_pipeline.build_graph() for full builds plus graph_pipeline.incremental_updater.incremental_update() for refresh.
• Query path: app.QueryRouter for single-repository graph-first answers, with bounded retrieval augmentation only when graph context is insufficient.
• Compatibility strategy: streaming, multi-repository, cache/session, and vector-store-heavy flows still delegate through the legacy runtime behind the facade until those surfaces are fully migrated.

• 🔍 Hierarchical Code Units — Advanced multi-level indexing spanning files, classes, functions, and documentation using AST-based parsing across 8+ programming languages

• 🔗 Hybrid Index — Seamlessly combines semantic embeddings with keyword search (BM25) for robust and precise code retrieval

• 📊 Multi-Layer Graph Modeling — Three interconnected relationship graphs (Call Graph, Dependency Graph, Inheritance Graph) enabling structural navigation across the entire codebase

Finding the right code without opening every file - at lightning speed

• ⚡ Two-Stage Smart Search — Like having a research assistant that first finds potentially relevant code, then ranks and organizes the best matches for your specific question.

• 📁 Safe File Browsing — Explores your project structure securely, understanding folder organization and file patterns without compromising security.

• 🌐 Following Code Connections — Traces how code pieces connect (up to 2 steps away), like following a trail of breadcrumbs through your codebase.

• 🎯 Code Skimming — Instead of reading entire files, FastCode just looks at the "headlines" - function names, class definitions, and type hints. This is like reading a book's chapter titles instead of every page, saving massive amounts of processing power.

Getting maximum insight while minimizing costs - automatically

• 📈 Budget-Aware Decision Making — Considers five key factors before processing: confidence level, query complexity, codebase size, resource cost, and iteration count. Like a cost-conscious financial advisor that weighs all options before making decisions.

• 🔄 Resource-Optimized Learning — Continuously adapts its approach in real-time, getting more efficient about what information to gather and when to stop. Think of it as an AI that maximizes value and becomes more cost-effective with every query.

• 🎯 Value-First Selection — Prioritizes high-impact, low-cost information first, like choosing the ripest fruit at the best price. This cost-optimized approach ensures you get maximum value for every token spent until the perfect stopping point is reached.

FastCode has been rigorously tested on four major benchmarks representing real-world software engineering challenges:

• ✅ Superior Accuracy — Consistently outperforms state-of-the-art baselines across all benchmarks

• ✅ 10x Token Efficiency — Achieves better results while using up to 90% fewer tokens

• ✅ Real-World Validation — Proven performance on actual production codebases and workflows

Get FastCode running in under 2 minutes:

# 1. Clone the repository
git clone https://github.com/HKUDS/FastCode.git
cd FastCode

# 2. Install dependencies
pip install -r requirements.txt

# 3. Configure your API keys
cp env.example .env
# Edit .env with your API keys

# 4. Launch the Web UI
python web_app.py --host 0.0.0.0 --port 5000

Open http://localhost:5000 and start asking questions about your code! 🎉

FastCode supports Linux, macOS, and Windows. Choose your platform below:

💡 Recommendation: We recommend using uv for faster and more reliable dependency installation.

The Web UI provides the most intuitive experience:

1. Launch the server:

   python web_app.py --host 0.0.0.0 --port 5000

2. Open your browser: Navigate to http://localhost:5000

3. Load a repository: Use the sidebar to index your codebase

4. Start asking questions:

   • "Where is the authentication logic implemented?"
   • "How does the payment processing flow work?"
   • "What files would be affected if I change the User model?"
   • "Explain the dependency between module A and module B"

For automation and scripting:

# Single repository query
python main.py query --repo-path /path/to/repo --query "Your question"

# Multi-repository query
python main.py query --repos /path/to/repo1 /path/to/repo2 --query "Your question"

# With custom model
python main.py query --repo-path /path/to/repo --query "Your question" --model gpt-4-turbo

# Start the API server
python api.py --host 0.0.0.0 --port 8000

# List available and loaded repositories
GET /repositories

# Load a repository from URL or local path
POST /load
{
  "source": "https://github.com/user/repo",
  "is_url": true
}

# Index the loaded repository
POST /index?force=false

# Load and index in one call
POST /load-and-index
{
  "source": "/path/to/repo",
  "is_url": false
}

# Load multiple existing indexed repositories
POST /load-repositories
{
  "repo_names": ["repo1", "repo2"]
}

# Index multiple repositories at once
POST /index-multiple
{
  "sources": [
    {"source": "https://github.com/user/repo1", "is_url": true},
    {"source": "/path/to/repo2", "is_url": false}
  ]
}

# Upload repository as ZIP file
POST /upload-zip
Content-Type: multipart/form-data
file: <zip_file>

# Upload and index in one call
POST /upload-and-index?force=false
Content-Type: multipart/form-data
file: <zip_file>

# Delete repositories and their indexes
POST /delete-repos
{
  "repo_names": ["repo1", "repo2"],
  "delete_source": true
}

# Get repository summary
GET /summary

# Query repository (single response)
POST /query
{
  "question": "How does authentication work?",
  "filters": null,
  "repo_filter": ["repo1"],
  "multi_turn": false,
  "session_id": null
}

# Query with streaming response (SSE)
POST /query-stream
{
  "question": "Explain the database schema",
  "multi_turn": true,
  "session_id": "abc123"
}

# Start a new conversation session
POST /new-session?clear_session_id=old_session

# List all conversation sessions
GET /sessions

# Get conversation history
GET /session/{session_id}

# Delete a conversation session
DELETE /session/{session_id}

# Health check
GET /health

# Get system status
GET /status?full_scan=false

# Clear cache
POST /clear-cache

# Get cache statistics
GET /cache-stats

# Refresh index cache
POST /refresh-index-cache

# Unload current repository
DELETE /repository

import requests

# Start a session and query
response = requests.post("http://localhost:8000/load-and-index", json={
    "source": "https://github.com/user/repo",
    "is_url": True
})

# Query the repository
response = requests.post("http://localhost:8000/query", json={
    "question": "Where is the main entry point?",
    "multi_turn": False
})

result = response.json()
print(result["answer"])
print(f"Tokens used: {result['total_tokens']}")

git clone https://github.com/HKUDS/FastCode.git
cd FastCode
uv venv --python=3.12
source .venv/bin/activate
uv pip install -r requirements.txt

{
  "mcpServers": {
    "fastcode": {
      "command": "/path/to/FastCode/.venv/bin/python",
      "args": ["/path/to/FastCode/mcp_server.py"],
      "env": {
        "MODEL": "gpt-5.2",
        "BASE_URL": "https://api.openai.com/v1",
        "OPENAI_API_KEY": "sk-..."
      }
    }
  }
}

{
  "mcpServers": {
    "fastcode": {
      "command": "/path/to/FastCode/.venv/bin/python",
      "args": ["/path/to/FastCode/mcp_server.py"],
      "env": {
        "MODEL": "gpt-5.2",
        "BASE_URL": "https://api.openai.com/v1",
        "OPENAI_API_KEY": "sk-..."
      }
    }
  }
}

claude mcp add fastcode -- /path/to/FastCode/.venv/bin/python /path/to/FastCode/mcp_server.py

OPENAI_API_KEY=sk-... MODEL=gpt-5.2 BASE_URL=https://api.openai.com/v1 \
/path/to/FastCode/.venv/bin/python /path/to/FastCode/mcp_server.py --transport sse --port 8080

Use FastCode to analyze what this repository at /path/to/repo_name is for.

Use FastCode to analyze the authentication flow in https://github.com/user/my-project

Which files would be affected if I change the User model?

FastCode works with multiple LLM providers:

OPENAI_API_KEY=sk-...
MODEL=gpt-4
BASE_URL=https://api.openai.com/v1

OPENAI_API_KEY=sk-or-...
MODEL=google/gemini-flash-1.5
BASE_URL=https://openrouter.ai/api/v1

OPENAI_API_KEY=ollama
MODEL=qwen3-coder-30b_fastcode
BASE_URL=http://localhost:11434/v1

FastCode automatically detects and parses:

• 🐍 Python
• 📜 JavaScript / TypeScript
• ☕ Java
• 🦀 Rust
• 🐹 Go
• ⚙️ C / C++
• 💎 C#

FastCode can be integrated with a Feishu (Lark) bot via Nanobot, enabling conversational code repository queries directly within Feishu.

Feishu User ←→ Feishu Open Platform ←→ Nanobot (WebSocket) ←→ FastCode API
                                        (port 18791)            (port 8001)

• FastCode Container: Provides the code analysis REST API (port 8001)
• Nanobot Container: Connects to Feishu via WebSocket and invokes FastCode tools (port 18791)
• Both containers communicate over Docker's internal network — no public IP required

# One-command launch (automatically builds images and generates config on first run)
./run_nanobot.sh

# Subsequent runs auto-detect the current state:
# - Services running → show status + health check
# - Services stopped → auto-restart
# - Images not found → auto-build and start

# ===== Shared API Configuration =====
OPENAI_API_KEY=sk-or-v1-xxx        # Shared by both services
BASE_URL=https://openrouter.ai/api/v1

# ===== FastCode Model (Code Analysis) =====
MODEL=google/gemini-3-flash-preview

# ===== Nanobot Model (Agent Reasoning / Feishu Conversations) =====
NANOBOT_MODEL=minimax/minimax-m2.1

{
  "channels": {
    "feishu": {
      "enabled": true,
      "appId": "cli_xxxxxxxxx",
      "appSecret": "your_app_secret"
    }
  }
}

services:
  fastcode:          # FastCode API (port 8001)
    build: .
    volumes:
      - ./.env:/app/.env:ro
      - ./config:/app/config:ro
      - ./data:/app/data
      - ./repos:/app/repos

  nanobot:           # Nanobot Gateway (port 18791 → 18790)
    build: ./nanobot
    command: ["gateway"]
    volumes:
      - ./nanobot_config.json:/root/.nanobot/config.json:ro
    environment:
      - FASTCODE_API_URL=http://fastcode:8001
      # API key and model injected from .env
      - NANOBOT_PROVIDERS__OPENROUTER__API_KEY=${OPENAI_API_KEY}
      - NANOBOT_AGENTS__DEFAULTS__MODEL=${NANOBOT_MODEL}
    depends_on:
      - fastcode

Chat with the bot in Feishu:

User: https://github.com/user/repo
Bot:  ✓ Repository loaded and indexed (152 files, 3847 code elements)

User: How is the authentication logic implemented in this project?
Bot:  This project uses JWT for authentication... [detailed analysis]

User: Which files would be affected by changes to the User model?
Bot:  The following 8 files would be affected... [impact analysis]

FastCode uses a novel scouting-first approach that fundamentally differs from traditional code reasoning systems:

Question → Load Files → Search → Load More Files → Search Again → ... → Answer
💸 High token cost from repeated file loading

Question → Build Semantic Map → Navigate Structure → Load Targets → Answer
💰 Minimal token cost with precise targeting

Query: "How does user authentication work in this application?"

FastCode Process:

1. 🗺️ Scouts for authentication-related structures
2. 🔍 Identifies auth.py, middleware.py, user_model.py
3. 📊 Traces dependencies between these files
4. 📖 Loads only relevant functions
5. ✅ Provides comprehensive answer

Query: "What would break if I change the User model schema?"

FastCode Process:

1. 🗺️ Locates User model definition
2. 🔗 Traces all imports and usages
3. 📊 Maps dependency graph
4. 📖 Loads affected code sections
5. ✅ Lists all impacted files and functions

We welcome contributions! FastCode is built for the community, by the community.

• 🐛 Report Bugs - Found an issue? Let us know!
• 💡 Suggest Features - Have ideas? We'd love to hear them!
• 📝 Improve Documentation - Help others understand FastCode better
• 🔧 Submit Pull Requests - Code contributions are always welcome

FastCode is released under the MIT License. See LICENSE for details.

Thanks for visiting ✨ FastCode!