Potpie — Spec-Driven Development for Large Codebases

Introduction

Potpie is an open-source AI development platform that builds a knowledge graph of your codebase to enable spec-driven development. It helps developers understand complex codebases, generate implementation specifications, and make changes with full context awareness across large projects.

What Potpie Does

• Builds a knowledge graph from your source code for deep context
• Answers questions about codebase architecture and implementation details
• Generates implementation specifications before writing code changes
• Provides specialized AI agents for debugging, testing, and code review
• Supports custom agent creation for project-specific workflows

Architecture Overview

Potpie parses your codebase into an abstract syntax tree and builds a graph representation capturing relationships between modules, classes, functions, and data flows. This knowledge graph powers RAG-based retrieval for AI agent conversations. The system uses multiple specialized agents that can be composed for complex multi-step development tasks.

Self-Hosting & Configuration

• Install via pip and run the indexer against your repository
• Configure LLM provider credentials for the AI agents
• Set indexing scope to include or exclude specific directories
• Deploy the web dashboard for team-wide codebase exploration
• Customize agent behaviors through configuration files

Key Features

• Knowledge graph that captures code relationships beyond text search
• Spec-first workflow ensuring changes are planned before implementation
• Multiple specialized agents (debug, test, review, explain)
• Works with any programming language through AST parsing
• Self-hosted with full control over your code and data

Comparison with Similar Tools

• Cursor — IDE-integrated AI, but no persistent knowledge graph
• Sourcegraph Cody — code search with AI, less focus on spec-driven flow
• Aider — terminal AI coding, no knowledge graph or spec workflow
• Continue — IDE extension, less structured approach to large codebases
• CodeRabbit — focused on PR review, not codebase exploration

FAQ

Q: Which programming languages are supported? A: Potpie supports major languages through tree-sitter parsing including Python, TypeScript, Java, Go, and Rust.

Q: Does it send my code to external services? A: Code stays local during indexing. Only relevant context snippets are sent to the configured LLM provider during queries.

Q: How large a codebase can it handle? A: The knowledge graph approach scales to repositories with hundreds of thousands of lines.

Q: Can I create custom AI agents? A: Yes. You can define custom agents with specific tools and instructions for your project needs.

Sources

• https://github.com/potpie-ai/potpie