FastCode

Prerequisites

• Python 3.12 or higher
• Git

Step-by-Step Guide

1. undefinedClone FastCodeundefined

   git clone https://github.com/HKUDS/FastCode.git
   cd FastCode
   

2. undefinedInstall Dependenciesundefined

   undefinedOption A: Using uv (Recommended)undefined

   # Install uv
   pip install uv
   # create new env with uv
   uv venv --python=3.12
   source .venv/bin/activate
   
   # Install dependencies with uv
   uv pip install -r requirements.txt
   

   undefinedOption B: Using pipundefined

   pip install -r requirements.txt
   

3. undefinedConfigure Environmentundefined

   cp env.example .env
   nano .env  # or use your preferred editor
   

   Add your API keys:

   OPENAI_API_KEY=your_openai_api_key_here
   MODEL=gpt-5.2
   BASE_URL=https://api.openai.com/v1
   

4. undefinedLaunch FastCodeundefined

   # Web UI (Recommended)
   python web_app.py --host 0.0.0.0 --port 5000
   
   # Or use the CLI
   python main.py query --repo-path /path/to/your/repo --query "Your question here"
   

Prerequisites

• Python 3.12 or higher
• Git

Step-by-Step Guide

1. undefinedClone FastCodeundefined

   git clone https://github.com/HKUDS/FastCode.git
   cd FastCode
   

2. undefinedInstall Dependenciesundefined

   undefinedOption A: Using uv (Recommended)undefined

   # Install uv
   pip install uv
   # create new env with uv
   uv venv --python=3.12
   source .venv/bin/activate
   
   # Install dependencies with uv
   uv pip install -r requirements.txt
   

   undefinedOption B: Using pipundefined

   pip install -r requirements.txt
   

3. undefinedConfigure Environmentundefined

   cp env.example .env
   nano .env  # or use: open -e .env
   

   Add your API keys:

   OPENAI_API_KEY=your_openai_api_key_here
   MODEL=gemini-3-flash
   BASE_URL=https://...
   

4. undefinedLaunch FastCodeundefined

   # Web UI (Recommended)
   python web_app.py --host 0.0.0.0 --port 5000
   
   # Or use the CLI
   python main.py query --repo-path /path/to/your/repo --query "Your question here"
   

undefinedNote for Apple Silicon (M1/M2/M3): All dependencies are compatible with ARM architecture.

Prerequisites

• Python 3.12 or higher
• Git

Step-by-Step Guide

1. undefinedClone FastCodeundefined

   git clone https://github.com/HKUDS/FastCode.git
   cd FastCode
   

2. undefinedInstall Dependenciesundefined

   undefinedOption A: Using uv (Recommended)undefined

   # Install uv
   pip install uv
   # create new env with uv
   uv venv --python=3.12
   .venv\Scripts\activate
   
   # Install dependencies with uv
   uv pip install -r requirements.txt
   

   undefinedOption B: Using pipundefined

   pip install -r requirements.txt
   

3. undefinedConfigure Environmentundefined

   copy env.example .env
   notepad .env
   

   Add your API keys:

   OPENAI_API_KEY=your_openai_api_key_here
   MODEL=qwen/qwen3-coder-30b-a3b-instruct
   BASE_URL=https://api.openai.com/v1
   

4. undefinedLaunch FastCodeundefined

   # Web UI (Recommended)
   python web_app.py --host 0.0.0.0 --port 5000
   
   # Or use the CLI
   python main.py query --repo-path C:\path\to\your\repo --query "Your question here"
   

undefinedTroubleshooting:undefined

• If you get SSL errors: pip install --upgrade certifi
• For permission errors, run Command Prompt as Administrator
• If faiss-cpu fails to install: pip install faiss-cpu --no-cache-dir
• If you run ./run_nanobot.sh (bash script) on Windows, use Git Bash or WSL, and keep .sh files in LF line endings. This repo enforces LF for *.sh via .gitattributes, but older clones may need a one-time re-checkout.

Integrate FastCode into your tools with the comprehensive REST API:

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

The API provides all features available in the Web UI. Visit http://localhost:8000/docs for interactive API documentation.

undefinedKey API Endpoints:undefined

# 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

undefinedExample Usage:undefined

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']}")

FastCode can run as an MCP (Model Context Protocol) server, allowing AI coding assistants like Cursor, Claude Code, and Windsurf to use FastCode’s repo-level code understanding capabilities directly.

Setup

Add the following to your MCP configuration:

Before configuring MCP, make sure FastCode dependencies are installed in the local uv virtual environment:

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

The MCP server should be launched with .venv/bin/python, and it needs OPENAI_API_KEY, MODEL, and BASE_URL.

undefinedCursor (~/.cursor/mcp.json):

{
  "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-..."
      }
    }
  }
}

undefinedClaude Code (claude_desktop_config.json):

{
  "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-..."
      }
    }
  }
}

Or via claude mcp add (ensure the same env vars are available in your shell):

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

undefinedSSE transport (for remote / shared deployments):

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

Available Tools

code_qa Parameters

How It Works

1. undefinedAuto-detection: For each repo in repos, FastCode checks if it’s already indexed. If yes, it skips indexing entirely.
2. undefinedAuto-clone: If a repo is a URL and not yet on disk, FastCode clones it to ./repos/ and indexes it.
3. undefinedMulti-turn: When multi_turn is enabled (default), previous Q&A context from the same session_id is used for query rewriting and answer generation. The session_id is returned in each response — pass it back in subsequent calls to continue the conversation.
4. undefinedMulti-repo: Pass multiple repos to repos and FastCode will search across all of them, using LLM-based repository selection to find the most relevant code.

Usage Example

In Cursor or Claude Code, simply ask:

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

or

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

The AI assistant will call code_qa with the URL, FastCode will clone and index the repo (if needed), and return a detailed answer with source references.

For follow-up questions, the assistant reuses the same session_id automatically:

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

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

1. Unified Configuration (.env)

All API keys and model settings are centralized in the .env file, shared by both services:

# ===== 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

The API key is automatically injected into the Nanobot container via docker-compose.yml environment variables — no need to duplicate it in nanobot_config.json.

2. FastCode Core Configuration

• config/config.yaml — FastCode retrieval and indexing settings

3. Nanobot Configuration (nanobot_config.json)

run_nanobot.sh auto-generates this file. You only need to configure Feishu credentials and the systemPrompt here; API keys and model settings are managed centrally via .env.

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

Nanobot receives Feishu messages via a WebSocket long-lived connection — no public IP or webhook required.

1. Create an App

Go to the Feishu Open Platform → Create a Custom Enterprise App → Note the App ID (cli_xxx) and App Secret.

2. Enable Bot Capability

Navigate to App Settings → App Features → Enable the “Bot” capability.

3. Add Permissions

Add the following permissions under Permission Management:

4. Configure Event Subscriptions

⚠️ Note the order: You must start Nanobot to establish the WebSocket connection first, then configure event subscriptions in the Feishu admin console.

1. Enter appId and appSecret in nanobot_config.json, then start the service (./run_nanobot.sh)
2. Verify the log shows connected to wss://msg-frontier.feishu.cn, confirming a successful connection
3. Go back to the Feishu admin console → Events & Callbacks → Select “Receive events via long-lived connection” → Save
4. Add event: im.message.receive_v1 (Receive messages)

5. Publish the App

Go to Version Management → Create a version → Submit for review (internal enterprise apps can be self-approved) → Once published, you can chat with the bot in Feishu.

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

On startup, Nanobot automatically registers the following tools via the FASTCODE_API_URL environment variable: