The Problem
Large codebases present a context problem for AI-assisted development. Teams struggle to maintain consistent understanding across thousands of files, and AI agents typically lack structural knowledge of code relationships, class hierarchies, and function dependencies beyond superficial pattern matching.
What This Does
Potpie constructs a knowledge graph from your codebase, indexing every file, class, and function with their relationships. The app/modules/intelligence/ directory contains the agent framework - over 100 agent-related files covering chat agents, system agents (codegenagent, debugagent, specgen/), and custom agents. The app/modules/codeprovider/ module handles repository integration with providers for GitHub, GitLab, and local repos. The graph structure enables agents to reason about code context rather than operating on isolated snippets. Database migrations in app/alembic/versions/ track schema evolution through 30+ migrations, supporting features like project ID support, search indexing, and citation tracking.
How To Use It
Setup: Clone with submodules required: git clone --recurse-submodules https://github.com/potpie-ai/potpie.git. Environment configuration lives in .env.template - copy to .env and set LLMPROVIDER, OPENAIAPIKEY, CHATMODEL, INFERENCEMODEL, and database/Redis values. Dependencies install via uv sync (.python-version file present).
Configuration: Required env vars are documented in .env.template. The app uses Flask (per tech stack analysis) with FastAPI based on the health check endpoint structure. AI provider selection is configured via LLMPROVIDER (openai | ollama | anthropic | openrouter).
Running it: Start all services with ./scripts/start.sh. This initiates Docker services, applies alembic migrations, starts the FastAPI app, and launches the Celery worker. Health check: curl -X GET 'http://localhost:8001/health'. Parsing status: curl -X GET 'http://localhost:8001/api/v1/parsing-status/your-project-id'.
Real-World Use
A team onboarding new engineers can use Potpie to generate context-aware code suggestions. For example, importing the knowledge graph allows an agent to answer "Where is the user authentication logic handled?" by traversing the graph rather than searching file contents. The app/modules/auth/ module provides API key and SSO provider infrastructure that agents can reference. Integration points exist through the API router (app/api/router.py) and event bus (app/modules/eventbus/) for real-time updates.
Code Health & Issues
Tests: 14 test files present; CI configured via .github/workflows/test.yml License: Apache 2.0 present in repo root Secrets: .env.template included but no actual secrets in repo Dependency hygiene: .python-version file specifies Python 3.11+; uv used for dependency management Structural organization: Clear module separation under app/modules/ (auth, codeprovider, conversations, intelligence, integrations, billing) Missing: No obvious code health red flags; tests/CI/license/lockfile all present where expected
The Bottom Line
Potpie delivers a functional knowledge graph implementation with sensible module organization and operational infrastructure (Docker, migrations, CI). It's well-suited for teams needing AI agents to reason across large codebases, particularly where spec-driven development or complex legacy systems require consistent code context. The learning curve involves configuring the knowledge graph and agent pipelines, but the existing agent framework under app/modules/intelligence/ provides substantial scaffolding. Teams already invested in AI tooling around code understanding will find the most value here.