Potpie

Potpie is an open-source platform that creates AI agents specialized in your codebase. Build a comprehensive knowledge graph of your code and let agents handle everything 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.ai Frontend

cd potpie-ui

cp .env.template .env

pnpm build && pnpm start

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:

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

🤖 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 debugging steps specific to your codebase. Docs
• Codebase Q&A Agent: Answers questions about your codebase and explains functions, features, and architecture. Docs
• Code Changes Agent: Analyzes code changes, identifies affected APIs, and suggests improvements before merging. Docs
• Integration Test Agent: Generates integration test plans and code for flows to ensure components work together properly. Docs
• Unit Test Agent: Automatically creates unit test plan and code for individual functions to enhance test coverage. Docs
• LLD Agent: Creates a low level design for implementing a new feature by providing functional requirements to this agent. Docs
• Code Generation Agent: Generates code for new features, refactors existing code, and suggests optimizations. Docs

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 : Help developers new to a codebase understand and get up to speed quickly. Ask it how to set up a new project, how to run the tests, etc.

  We tried to onboard ourselves with Potpie to the AgentOps codebase and it worked like a charm: Video here.

• Codebase Understanding : Answer questions about any library you're integrating, explain functions, features, and architecture.

  We used the Q&A agent to understand the underlying working of a feature of the CrewAI codebase that was not documented in official docs: Video here.

• Low Level Design : Get detailed implementation plans for new features or improvements before writing code.

  We fed an open issue from the Portkey-AI/Gateway project to this agent to generate a low level design for it: Video here.

• Reviewing Code Changes : Understand the functional impact of changes and compute the blast radius of modifications.

• Debugging : Get step-by-step debugging guidance based on stacktraces and codebase context.

• Testing : Generate contextually aware unit and integration test plans and test code that understand your codebase's structure and purpose.

Extensions & Integrations

VSCode Extension

Bring the power of Potpie's AI agents directly into your development environment.

• Direct Integration : Access all Potpie agents without leaving your editor
• Quick Setup : Install directly from the VSCode Marketplace
• Seamless Workflow : Ask questions, get explanations, and implement suggestions right where you code

Slack Integration

Bring your custom AI agents directly into your team's communication hub.

• Team Collaboration : Access all Potpie agents where your team already communicates
• Effortless Setup : Install and configure in under 2 minutes. Docs
• Contextual Assistance : Get answers, code solutions, and project insights directly in Slack

👉 Install the Potpie Slack App: Here

API Access

Access Potpie Agents through an API key for CI/CD workflows and automation. See the API documentation.

Tool Integration

Edit or add tools in app/modules/intelligence/tools and initialize them in app/modules/intelligence/tools/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 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 🥂