potpie-ai / potpie

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 • **Clone the repository** • **Configure your environment** Edit with the following required values: > ** ** and ** ** are used for agent reasoning and knowledge graph generation respectively. Model names follow the format as expected by LiteLLM. > **💡 Using Ollama instead?** Set and use and . See for the full list of optional configuration (logging, feature flags, object storage, email, analytics, etc.). • **Install dependencies** • **Start all services** This will start Docker services, apply migrations, start the FastAPI app, and start the Celery worker. • **Health Check** • **Check parsing status** To stop all services: Now set up Potpie Frontend --- 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 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** | , | Production | | **PAT Pool** | | Development / Higher rate limits | | **Unauthenticated** | No configuration required | Public repositories only (60 req/hr) | Set to , , or 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 directory and install all dependencies from 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: **Option 2: Personal Access Token (PAT) Pool** • Create one or more GitHub PATs with scope • Set environment variable (comma-separated for multiple tokens): • 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**: tokens are always used for GitHub.com, regardless of . • **Start Potpie** To start all Potpie services: 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: • Get a Logfire token from https://logfire.pydantic.dev • Add it to your file: • Tracing is automatically initialized when Potpie starts. View traces at https://logfire.pydantic.dev **Note:** Set in your to disable sending traces to Logfire cloud. • **Stop Potpie** To stop all Potpie services: **Windows** 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 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…