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

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

2. Configure your environment

   cp .env.template .env

   Edit .env with the following required values:

   # 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.).

3. Install dependencies

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

4. Start all services

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

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

5. Health Check

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

6. Check parsing status

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

To stop all services:

./scripts/stop.sh

Now set up Potpie Frontend

cd potpie-ui

cp .env.template .env

pnpm build && pnpm start

---

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

Method	Configuration	Best For
GitHub App	GITHUB_APP_ID, GITHUB_PRIVATE_KEY	Production
PAT Pool	GH_TOKEN_LIST=ghp_token1,ghp_token2	Development / Higher rate limits
Unauthenticated	No configuration required	Public repositories only (60 req/hr)

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:

  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):

  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.

2. Start Potpie

   To start all Potpie services:

   chmod +x scripts/start.sh
   ./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:

   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.

3. Stop Potpie

   To stop all Potpie services:

   ./scripts/stop.sh

   Windows

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

Onboarding Get new developers productive in hours, not weeks. Potpie maps your architecture, entry points, and setup flows so anyone can hit the ground running.	Codebase Q&A Ask anything about your codebase - functions, data flows, design decisions. Get precise answers grounded in your actual code, not guesses.
Debugging Paste a stacktrace. Get a root-cause analysis and step-by-step fix path pinpointed to your code - not generic troubleshooting advice.	Code Review Before you merge, understand the blast radius of your changes. Potpie surfaces affected APIs, downstream impacts, and potential regressions.
Test Generation Generate unit and integration tests that understand your code structure - not boilerplate. Covers edge cases your manual tests would miss.	Feature Planning Turn a requirement or open issue into a low-level implementation plan - with component breakdown, API surface, and suggested code structure.

Extensions & Integrations

VSCode Extension Use Potpie's AI agents directly inside your editor - no tab switching, no copy-pasting. Ask questions, get explanations, and ship code without leaving VSCode. Agents understand your open repo instantly Works with any codebase - local or remote

Slack Integration Bring Potpie into your team's Slack workspace. Debug code, answer codebase questions, and get project insights - all in threads your team already uses. Set up in under 2 minutes Works with your custom configured agents

API Access Integrate Potpie into CI/CD pipelines and automation workflows via API key. Trigger agents programmatically to fit your existing DevOps setup.

Custom Tool Integration Extend Potpie's capabilities by building and registering your own tools. Add files to app/modules/intelligence/tools/ and register them in tool_service.py.

Community & Support

• GitHub Issues. Best for: bugs and errors you encounter using Potpie.
• Discord. Best for: sharing your projects and hanging out with the community.
• Email Support. Best for: problems with your setup or infrastructure.

See the Contributing Guide for more details.

License

This project is licensed under the Apache 2.0 License - see the LICENSE file for details.

Contributors

Thanks for spending your time helping build Potpie. Keep rocking 🥂

Want to contribute? Read the Contributing Guide to get started.