<img src="https://github.com/potpie-ai/potpie/raw/v2.0.0/assets/logo_light.svg"  alt="Potpie AI logo" />

Potpie

Potpie turns your entire codebase into a knowledge graph - a structural index of every file, class, and function, capturing all their relationships and what each part of the code does in context of everything else. AI agents built on this graph can reason about your code with the precision of someone who wrote it - from debugging to feature development.

Quick Start

Prerequisites

• Docker installed and running
• Git installed
• Python 3.11+ with uv

Installation

1. Clone the repository

bash git clone https://github.com/potpie-ai/potpie.git cd potpie

1. Configure your environment

bash cp legacy/.env.template legacy/.env

Edit .env with the following required values:

```bash # App & Environment isDevelopmentMode=enabled ENV=development defaultUsername=defaultuser

# AI / LLM Configuration LLM_PROVIDER=openai # openai | ollama | anthropic | openrouter OPENAI_API_KEY=sk-proj-your-key CHAT_MODEL=gpt-4o INFERENCE_MODEL=gpt-4o-mini

# Database POSTGRES_SERVER=postgresql://postgres:mysecretpassword@localhost:5432/momentum NEO4J_URI=bolt://127.0.0.1:7687 NEO4J_USERNAME=neo4j NEO4J_PASSWORD=mysecretpassword

# Redis & Background Jobs REDISHOST=127.0.0.1 REDISPORT=6379 BROKER_URL=redis://127.0.0.1:6379/0 CELERY_QUEUE_NAME=dev

# Project & Repo Management PROJECT_PATH=projects ```

CHAT_MODEL and INFERENCE_MODEL are used for agent reasoning and knowledge graph generation respectively. Model names follow the provider/model_name format as expected by LiteLLM.

💡 Using Ollama instead? Set LLM_PROVIDER=ollama and use CHAT_MODEL=ollama_chat/qwen2.5-coder:7b and INFERENCE_MODEL=ollama_chat/qwen2.5-coder:7b.

See .env.template for the full list of optional configuration (logging, feature flags, object storage, email, analytics, etc.).

1. Install dependencies

bash curl -LsSf https://astral.sh/uv/install.sh | sh uv sync

1. Start all services

bash chmod +x legacy/scripts/start.sh ./legacy/scripts/start.sh

This will start Docker services, apply migrations, start the FastAPI app, and start the Celery worker.

1. Health Check

bash curl -X GET 'http://localhost:8001/health'

1. Check parsing status

bash curl -X GET 'http://localhost:8001/api/v1/parsing-status/your-project-id'

To stop all services:

./legacy/scripts/stop.sh

Now set up Potpie Frontend

Clone the UI repo separately (it is no longer a submodule of this repository):

git clone https://github.com/potpie-ai/potpie-ui.git
cd potpie-ui

cp .env.template .env

pnpm build && pnpm start

Optional: durable agent runtime with Hatchet

By default agents run on Celery. Potpie can optionally run allowlisted agents (the debug agent first) on a self-hosted Hatchet for durable execution — fully opt-in, reusing the existing potpie_postgres container (no RabbitMQ).

One command — boots infra + Hatchet + API + Celery + the Hatchet agent worker:

cd legacy && make dev-hatchet

This runs with AGENT_TASK_BACKEND=hatchet, so agents in HATCHET_AGENT_ALLOWLIST (default debugging_agent) dispatch to Hatchet while everything else stays on Celery.

Piecemeal / alongside your usual start:

make hatchet-up      # boot Hatchet (engine :7077, dashboard :8080) + write .env.hatchet.local
make hatchet-worker  # run the Hatchet agent worker
make hatchet-down    # stop only the Hatchet services

Dashboard: http://localhost:8080 (admin@example.com / Admin123!!). Enable via .env (see the Hatchet block in .env.template):

AGENT_TASK_BACKEND=hatchet               # celery (default) | hatchet
HATCHET_AGENT_ALLOWLIST=debugging_agent  # comma-separated agent ids routed to Hatchet

HATCHET_CLIENT_* (token/host) are generated into .env.hatchet.local by make hatchet-up — no manual setup for local dev. If Hatchet is selected but unavailable, those runs fail closed with HTTP 503 (no silent fallback). Design notes: docs/hatchet-durable-agent-runtime-plan.md.

How it works?

Potpie parses your repository into a knowledge graph stored in Neo4j - capturing every file, function, class, and the relationships between them. Agents read directly from this graph to answer questions and complete tasks grounded in your actual code.

Architecture

• FastAPI serves as the API layer - all requests enter through localhost:8001 with CORS, Logfire tracing, and optional Sentry error tracking.
• Firebase Auth handles production authentication. In development mode a dummy user is created locally - no Firebase needed.
• Celery Worker with Redis as the broker handles async repo parsing - cloning, AST extraction, and knowledge graph construction run entirely in the background.
• Hatchet (optional) is a swappable durable runtime for allowlisted agent runs (the debug agent first) — see Optional: durable agent runtime with Hatchet above.
• Conversation Service manages chat sessions and agent memory across multi-turn interactions.
• Agent Router dispatches prompts to the correct pre-built or custom agent based on intent.
• Tool Service exposes callable functions to agents - code search, file fetch, knowledge graph queries, web tools, and more.
• Neo4j Knowledge Graph stores your codebase as a property graph - functions, classes, files, imports, and call relationships - the backbone of every agent's context.
• PostgreSQL stores users, projects, conversations, and message history.

GitHub Authentication

Set GITHUB_AUTH_MODE to app, pat, or none to select the method.

Self-Hosted Git Providers

For self-hosted Git servers (e.g., GitBucket, GitLab, etc.), configure:

  uv sync

This will create a .venv directory and install all dependencies from pyproject.toml

GitHub Authentication Setup

Potpie supports multiple authentication methods for accessing GitHub repositories:

For GitHub.com Repositories:

Option 1: GitHub App (Recommended for Production) - Create a GitHub App in your organization - Set environment variables: bash GITHUB_APP_ID=your-app-id GITHUB_PRIVATE_KEY=your-private-key

Option 2: Personal Access Token (PAT) Pool - Create one or more GitHub PATs with repo scope - Set environment variable (comma-separated for multiple tokens): bash GH_TOKEN_LIST=ghp_token1,ghp_token2,ghp_token3 - Potpie will randomly select from the pool for load balancing - Rate Limit: 5,000 requests/hour per token (authenticated)

Option 3: Unauthenticated Access (Public Repos Only) - No configuration needed - Automatically used as fallback for public repositories - Rate Limit: 60 requests/hour per IP (very limited)

For Self-Hosted Git Servers (GitBucket, GitLab, etc.):

  Set the following environment variables:


  CODE_PROVIDER=github   # Options: github, gitbucket
  CODE_PROVIDER_BASE_URL=http://your-git-server.com/api/v3
  CODE_PROVIDER_TOKEN=your-token

Important: GH_TOKEN_LIST tokens are always used for GitHub.com, regardless of CODE_PROVIDER_BASE_URL.

1. Start Potpie

To start all Potpie services:

bash chmod +x legacy/scripts/start.sh ./legacy/scripts/start.sh

This will: - Start required Docker services - Wait for PostgreSQL to be ready - Apply database migrations - Start the FastAPI application - Start the Celery worker

**Optional: Logfire Tracing Setup**

  To monitor LLM traces and agent operations with Pydantic Logfire:

  1. Get a Logfire token from https://logfire.pydantic.dev
  2. Add it to your `.env` file:
  ```bash
  LOGFIRE_TOKEN=your_token_here
  ```
  3. Tracing is automatically initialized when Potpie starts. View traces at https://logfire.pydantic.dev

  **Note:** Set `LOGFIRE_SEND_TO_CLOUD=false` in your `.env` to disable sending traces to Logfire cloud.

1. Stop Potpie

To stop all Potpie services:

bash ./legacy/scripts/stop.sh

Windows

powershell ./stop.ps1

This will gracefully stop: - The FastAPI application - The Celery worker - All Docker Compose services

Potpie's Prebuilt Agents

Potpie offers a suite of specialized codebase agents for automating and optimizing key aspects of software development:

Debugging Agent Automatically analyzes stacktraces and provides step-by-step debugging guidance specific to your codebase - not generic advice.	Codebase Q&A Agent Answers questions about your codebase and explains functions, features, and architecture from first principles.
Code Generation Agent Generates code for new features, refactors existing code, and suggests optimizations grounded in your actual codebase.	Spec Agent Generates detailed software specifications, PRDs, and architecture documents grounded in your codebase.

Custom Agents

With Custom Agents, you can design personalized tools that handle repeatable tasks with precision. Define:

• System Instructions - The agent's task, goal, and expected output
• Tasks - Individual steps for job completion
• Tools - Functions for querying the knowledge graph or retrieving code

curl -X POST "http://localhost:8001/api/v1/custom-agents/agents/auto" \
     -H "Content-Type: application/json" \
     -d '{"prompt": "An agent that takes stacktrace as input and gives root cause analysis and proposed solution as output"}'

Read more in our documentation.

Use Cases