Potpie is an open-source, Apache-2.0 licensed Python tool that turns a codebase and its software development lifecycle into a living context graph for AI coding agents, and it is built for developers and engineering teams whose agents need project-specific context to answer questions, plan changes, debug failures, and write code.

What it is

Potpie indexes a repository's code, structure, decisions, source history, team knowledge, and engineering workflows into a context graph, then serves that graph to AI agents running inside the coding harnesses developers already use. It is distributed on PyPI as the potpie package and installs a CLI, a local daemon, and a browser-based graph explorer, so the ecosystem it lives in is Python developer tooling alongside AI agent frameworks and retrieval-augmented generation stacks. The project describes itself as a context graph for an AI-native SDLC, and its topics place it among agents, AI agent frameworks, knowledge graphs, and generative AI developer tools.

The concrete problem it solves is context loss between an agent and a real project. Generic agents do not know a team's conventions, past decisions, review history, or issue tracker, and the usual workaround is repeatedly pasting context into prompts or running a separate manual ingest step. Potpie replaces that manual ingestion: once sources are registered, the configured agent ingests or updates project context when the task requires it, and commands such as potpie resolve "what should I know before working in this repository?" pull the material an agent should read before starting work.

Key capabilities

• Builds a living context graph from code, structure, decisions, source history, team knowledge, and engineering workflows, viewable in a local graph explorer opened with potpie ui.
• Runs a first-time wizard, potpie setup, that provisions local config, storage, the daemon, a default pot, and agent skills, and lets the user choose integrations and the coding harness to configure.
• Serves pre-task context through potpie resolve "" and targeted lookups through potpie search "" for a specific file, workflow, bug, decision, or convention.
• Persists durable project learnings with potpie record --type --summary "
  ", for example a decision to prefer the Potpie CLI for graph work.
• Exposes lower-level graph operations through potpie graph for reads, quality checks, proposals, and commits.
• Installs or refreshes agent guidance with potpie skills install --agent , keeping skill definitions aligned with the active harness.
• Reports readiness and health with potpie status for daemon, graph, and skill checks on the active pot, potpie doctor for daemon, backend capability, and skill drift diagnostics, and potpie auth status --verify for integration credential checks.

Who uses it and how

• Teams already working inside a supported coding harness. Potpie is integrated into the selected harness, and the workflow is to open that harness and ask it to use Potpie for a given repository.
• Repositories registered as sources. potpie source add repo . registers the current repository for the resolved pot, after which the agent ingests or updates context on demand instead of on a manual schedule.
• Engineers juggling several projects. Pots act as workspaces, listed with potpie pot list and selected with potpie pot use, with potpie status reporting context readiness for whichever pot is active.
• Teams that want agent context drawn from their issue tracker and review history. The GitHub integration indexes repositories, pull requests, issues, reviews, and source history, while the Linear integration indexes teams, issues, and projects.
• Individuals or teams that need account-backed and managed features, which are reachable after potpie login rather than from the local-only path.

Getting started

Install the CLI from PyPI with uv tool install potpie, which the README recommends because it avoids globally mutating Python packages, or with python3 -m pip install --user potpie. Then run potpie setup to provision local configuration, storage, the daemon, a default pot, and agent skills; the exhaustive command list lives at docs.potpie.ai.

How it compares

No paid products that this project replaces are listed in the facts, and no comparable tools are named either, so Potpie stands alone in this registry. Its GitHub and Linear integrations and its support for harnesses such as OpenAI Codex and Claude are the reference points available rather than a competitive set.

When to use it — and when not to

A self-hoster runs a local daemon with its own config and storage, and must keep integrations authenticated and agent skills in sync, which potpie status, potpie doctor, and potpie auth status --verify exist to police; teams that want a fully hosted, zero-install experience, or that do not use coding agents at all, should not pick it. The project is Apache-2.0 licensed and actively pushed, but it carries 109 open issues and an integrations table that the provided README excerpt cuts off mid-entry, so integration breadth should be verified before committing to it.

uv tool install potpie

python3 -m pip install --user potpie

potpie setup

potpie ui

potpie setup --repo . --agent claude
potpie github login
potpie auth status
potpie status
potpie source add repo .
potpie resolve "what should I know before working in this repository?"
potpie search "authentication flow"
potpie record --type decision --summary "Prefer the Potpie CLI for graph work"