App | Documentation | API Reference | Chat with 🥧 Repo

Prompt-To-Agent: Create custom engineering agents for your code

Potpie is an open-source platform that creates AI agents specialized in your codebase, enabling automated code analysis, testing, and development tasks. By building a comprehensive knowledge graph of your code, Potpie's agents can understand complex relationships and assist with everything from debugging to feature development.

📚 Table of Contents

• 🥧 Why Potpie?
• 🤖 Our Prebuilt Agents
• 🛠️ Tooling
• 🚀 Getting Started
• 💡 Use Cases
• 🛠️ Custom Agents
• 🗝️ Accessing Agents via API Key
• 🎨 Make Potpie Your Own
• 🤝 Contributing
• 📜 License
• 💪 Contributors

🥧 Why Potpie?

• 🧠 Deep Code Understanding: Built-in knowledge graph captures relationships between code components
• 🤖 Pre-built & Custom Agents: Ready-to-use agents for common tasks + build your own
• 🔄 Seamless Integration: Works with your existing development workflow
• 📈 Flexible: Handles codebases of any size or language

🔌 VSCode Extension

Bring the power of Potpie's AI agents directly into your development environment with our VSCode extension:

• 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 with our Slack integration:

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

👉 Install the Potpie Slack App: Here

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

🛠️ Potpie's Tooling System

Potpie provides a set of tools that agents can use to interact with the knowledge graph and the underlying infrastructure:

• get_code_from_probable_node_name: Retrieves code snippets based on a probable node name.
• get_code_from_node_id: Fetches code associated with a specific node ID.
• get_code_from_multiple_node_ids: Retrieves code snippets for multiple node IDs simultaneously.
• ask_knowledge_graph_queries: Executes vector similarity searches to obtain relevant information.
• get_nodes_from_tags: Retrieves nodes tagged with specific keywords.
• get_code_graph_from_node_id/name: Fetches code graph structures for a specific node.
• change_detection: Detects changes in the current branch compared to the default branch.
• get_code_file_structure: Retrieves the file structure of the codebase.

🚀 Getting Started

Prerequisites

• Docker installed and running
• Git installed (for repository access)
• Python 3.11+ (required for uv and dependencies)
• uv - Fast Python package installer (install via curl -LsSf https://astral.sh/uv/install.sh | sh)

Potpie UI

An easy to use interface to interact with your Agents

Initialize the UI Submodule

To initialize the submodule:

git submodule update --init

1. Navigate to the potpie-ui Directory

cd potpie-ui

2. Update the Main Branch and Checkout

git checkout main
git pull origin main

3. Set Up the Environment

Create a .env file in the potpie-ui directory and copy the required configuration from .env.template.

cp .env.template .env

4. Build the Frontend

pnpm build

5. Start the Application

pnpm start

Setup Steps

Install uv

• Install uv package manager:

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

• Ensure ~/.local/bin is in your PATH

1. Prepare Your Environment

   • Create a .env file based on the .env.template

   • Add the following required configurations:

     isDevelopmentMode=enabled
     ENV=development
     POSTGRES_SERVER=postgresql://postgres:mysecretpassword@localhost:5432/momentum
     NEO4J_URI=bolt://127.0.0.1:7687
     NEO4J_USERNAME=neo4j
     NEO4J_PASSWORD=mysecretpassword
     REDISHOST=127.0.0.1
     REDISPORT=6379
     BROKER_URL=redis://127.0.0.1:6379/0
     CELERY_QUEUE_NAME=dev
     defaultUsername=defaultuser
     PROJECT_PATH=projects #repositories will be downloaded/cloned to this path on your system.
     {PROVIDER}_API_KEY=sk-proj-your-key #your provider key e.g. ANTHROPIC_API_KEY for Anthropic
     INFERENCE_MODEL=ollama_chat/qwen2.5-coder:7b #provider model name
     CHAT_MODEL=ollama_chat/qwen2.5-coder:7b #provider model name

     INFERENCE_MODEL and CHAT_MODEL correspond to the models that will be used for generating knowledge graph and for agent reasoning respectively. These model names should be in the format of provider/model_name format or as expected by Litellm. For more information, refer to the Litellm documentation.
     

   • Install dependencies using uv:

     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:
  ```bash
  # Options: github, gitlab, gitbucket
  CODE_PROVIDER=github
  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 start.sh
   ./start.sh

   Windows

   ./start.ps1

   This will:

   • Start required Docker services
   • Wait for PostgreSQL to be ready
   • Apply database migrations
   • Start the FastAPI application
   • Start the Celery worker

Optional: Phoenix Tracing Setup (Local Only)

To monitor LLM traces and agent operations with Phoenix in local development:

phoenix serve

Run this in a new terminal to start the Phoenix server. Traces will be available at http://localhost:6006 (default). Phoenix tracing is automatically initialized when Potpie starts, but you need to run phoenix serve separately to view the traces. Note: This setup is for local development only.

3. Stop Potpie

   To stop all Potpie services:

   ./stop.sh

   Windows

   ./stop.ps1

   This will gracefully stop:

   • The FastAPI application
   • The Celery worker
   • All Docker Compose services

4. Authentication Setup (Skip this step in development mode)

   curl -X POST 'http://localhost:8001/api/v1/login' \
     -H 'Content-Type: application/json' \
     -d '{
       "email": "your-email",
       "password": "your-password"
     }'
   # Save the bearer token from the response for subsequent requests
   

5. Initialize Repository Parsing

   # For development mode:
   curl -X POST 'http://localhost:8001/api/v1/parse' \
     -H 'Content-Type: application/json' \
     -d '{
       "repo_path": "path/to/local/repo",
       "branch_name": "main"
     }'
   
   # For production mode:
   curl -X POST 'http://localhost:8001/api/v1/parse' \
     -H 'Content-Type: application/json' \
     -d '{
       "repo_name": "owner/repo-name",
       "branch_name": "main"
     }'
   # Save the project_id from the response
   

6. Monitor Parsing Status

   curl -X GET 'http://localhost:8001/api/v1/parsing-status/your-project-id'
   # Wait until parsing is complete
   

7. View Available Agents

   curl -X GET 'http://localhost:8001/api/v1/list-available-agents/?list_system_agents=true'
   # Note down the agent_id you want to use

8. Create a Conversation

   curl -X POST 'http://localhost:8001/api/v1/conversations/' \
     -H 'Content-Type: application/json' \
     -d '{
       "user_id": "your_user_id",
       "title": "My First Conversation",
       "status": "active",
       "project_ids": ["your-project-id"],
       "agent_ids": ["chosen-agent-id"]
     }'
   # Save the conversation_id from the response
   

9. Start Interacting with Your Agent

   curl -X POST 'http://localhost:8001/api/v1/conversations/your-conversation-id/message/' \
     -H 'Content-Type: application/json' \
     -d '{
       "content": "Your question or request here",
       "node_ids":[]
     }'

10. View Conversation History (Optional)

curl -X GET 'http://localhost:8001/api/v1/conversations/your-conversation-id/messages/?start=0&limit=10'

💡 Use Cases

• Onboarding: For developers new to a codebase, the codebase QnA agent helps them understand the codebase and get up to speed quickly. Ask it how to setup 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.

🛠️ Custom Agents Upgrade ✨

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

• System Instructions: Define the agent's task, goal, and expected output
• Agent Information: Metadata about the agent's role and context
• Tasks: Individual steps for job completion
• Tools: Functions for querying the knowledge graph or retrieving code

🗝️ Accessing Agents via API Key

You can access Potpie Agents through an API key, enabling integration into CI/CD workflows and other automated processes. For detailed instructions, please refer to the Potpie API documentation.

• Generate an API Key: Easily create an API key for secure access.
• Parse Repositories: Use the Parse API to analyze code repositories and obtain a project ID.
• Monitor Parsing Status: Check the status of your parsing requests.
• Create Conversations: Initiate conversations with specific agents using project and agent IDs adn get a conversation id.
• Send Messages: Communicate with agents by sending messages within a conversation.

🎨 Make Potpie Your Own

Potpie is designed to be flexible and customizable. Here are key areas to personalize your own deployment:

Effortless Agent Creation:

Design custom agents tailored to your specific tasks using a single prompt. Utilize the following API to create your custom agents:

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

Read more about other custom agent APIs to edit and delete your custom agents in our documentation.

Tool Integration

Edit or add tools in the app/modules/intelligence/tools directory for your custom agents. Initialise the tools in the app/modules/intelligence/tools/tool_service.py file and include them in your agent.

🤝 Contributing

We welcome contributions! To contribute:

1. Fork the repository
2. Create a new branch (git checkout -b feature-branch)
3. Make your changes
4. Commit (git commit -m 'Add new feature')
5. Push to the branch (git push origin feature-branch)
6. Open a Pull Request

See Contributing Guide for more details.

📜 License

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

💪 Thanks To All Contributors

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