Potpie: A Context Graph for AI Agents That Knows Your Repository's History, Decisions, and Workflows

What Potpie Actually Solves

Potpie addresses a specific pain: AI coding agents often work with incomplete context. A model might know general coding patterns, but it does not know your repository's internal conventions, past decisions, or why a piece of code exists. Potpie builds a 'living context graph' that indexes code, structure, decisions, source history, team knowledge, and engineering workflows. The intended users are engineers and teams who rely on AI agents like Claude Code or OpenAI Codex to answer questions, plan changes, debug failures, and write code. Instead of pasting snippets into a prompt, you ask the agent to use Potpie, which pulls the relevant context from the graph. The project is Python-based, Apache-2.0 licensed, and currently in a v2.0.0 release, indicating a maturation from earlier betas.

The Mechanism: CLI-First, Daemon, and Graph

Potpie's architecture is explicitly CLI-first, designed for both humans and agents. The core idea is that you install a CLI, run a setup wizard, and the CLI registers sources. The daemon then serves a local graph explorer and presumably manages the indexing. The README states you do not need a separate manual ingest command; the CLI registers sources and the configured agent can ingest or update project context when the task requires it. This is a notable design choice: the agent triggers ingestion on demand, which keeps the graph fresh but also means the first request might be slower as indexing happens. The graph itself is not just code symbols; it includes decisions, source history, and team knowledge, which are typically stored in issue trackers and documents. The `potpie resolve` command pulls the context an agent should read before doing a task, and `potpie search` looks up specific files, workflows, bugs, decisions, or conventions. This suggests a query layer over a structured graph, not just a vector store.

Getting Started: Real Commands and Setup Flow

Installation is straightforward via PyPI. The README recommends `uv tool install potpie`, but `python3 -m pip install --user potpie` also works. After installation, you run `potpie setup`. This wizard provisions local config, storage, the daemon, a default pot, and agent skills. A 'pot' appears to be a workspace or project context bucket. You can specify a repo and agent directly: `potpie setup --repo . --agent claude`. Then you connect integrations with `potpie github login` or `potpie linear login`. To verify credentials, use `potpie auth status --verify`. The `potpie status` command shows context readiness for the active pot, including daemon, graph, and skill checks. To register a repository, you run `potpie source add repo .`. For daily use, `potpie resolve` and `potpie search` are the primary query commands. You can also record durable project learnings with `potpie record --type decision --summary "..."`, which writes to the graph. The `potpie ui` command opens a local graph explorer in the browser. This setup is entirely local, which has privacy benefits but also operational overhead.

Integrations and Harness Support: The Good and the Gaps

Potpie supports four integrations: GitHub, Linear, Jira, and Confluence. GitHub indexing covers repositories, pull requests, issues, reviews, and source history. Linear covers teams, issues, projects, and documents. Jira covers projects, issues, status, and changelog context. Confluence covers spaces, pages, runbooks, and decisions. For coding harnesses, Potpie has skills for Claude Code, OpenAI Codex, Cursor, and OpenCode. The README says more are coming and invites tickets for new ones. This is a clear limitation: if your team uses JetBrains IDEs, VS Code Copilot, or other agents, you cannot use Potpie's skills directly. You could still use the CLI manually, but the agent integration is the core value. The documentation likely explains how to install skills, but the README only shows `potpie skills install --agent <agent>`. The breadth of integrations is reasonable for a v2.0.0 project, but the harness list is narrow.

Operational Considerations: Daemon, Config, and Skill Drift

Potpie runs a local daemon, which means it is a persistent background process. The `potpie doctor` command runs diagnostics for daemon, backend capabilities, and skill drift. 'Skill drift' is an interesting term: it suggests that the instructions installed into your agent harness can become out of sync with the Potpie version, and you need to refresh them. This is a maintenance burden. The setup wizard provisions local config and storage, but the README does not specify where these live or how to back them up. The `potpie graph` command offers lower-level graph reads, quality checks, proposals, and commits. This implies that the graph is not just a passive index; you can propose changes and commit them, which sounds like a versioned knowledge base. However, the README does not explain the graph commit workflow in detail. The daemon also serves the web UI, so you need to keep it running to use the graph explorer. For teams that prefer stateless tools, this is a consideration.

Limitations and Failure Modes

The most obvious limitation is the local-first architecture. You must run a daemon and manage config, storage, and skills. This is not a hosted SaaS; Potpie is a self-hosted tool. For teams without the operational capacity to run a daemon, this could be a burden. Another limitation is the narrow harness support. If you use an agent not in the list, you lose the seamless integration. The README also notes that you do not need a manual ingest command, but that means the agent decides when to ingest. If the agent fails to trigger ingestion, the graph might be stale. The `potpie status` command checks context readiness, but it is up to you to run it. There is also the question of scale. The README does not mention performance on large monorepos or how the graph handles millions of files. The v2.0.0 release notes are not included in the material, so we cannot confirm any performance improvements. Finally, the graph includes decisions and team knowledge from tools like Confluence and Linear, but if your team does not use those tools, those parts of the graph will be empty.

Alternative Approach: Repo Maps vs. Living Graphs

A common alternative to Potpie is a static repository map or a code search tool like Sourcegraph. Sourcegraph indexes code and provides search and navigation, but it does not integrate decisions, issue history, or team knowledge into a graph. Potpie's differentiator is the 'living' aspect: it ingests source history, PRs, issues, and documents, and it lets you record durable learnings with `potpie record`. This is a fundamental difference in approach. Sourcegraph is a search engine; Potpie is a context graph that agents can query with `resolve` and `search`. Another alternative is to rely on the agent's built-in file reading, but that lacks the cross-referencing of code and metadata. Potpie's graph is meant to be a persistent, evolving knowledge base, whereas a repo map is a static snapshot. The trade-off is complexity: Potpie requires setup and maintenance, while a repo map is simpler but less informative.

Maintenance, Upgrade Cost, and License

Potpie is licensed under Apache-2.0, which is permissive and allows commercial use, modification, and distribution with attribution. This is a positive for adoption, as there are no copyleft restrictions. The project is actively maintained, with a v2.0.0 release in July 2026, following betas in June. The maintenance cost comes from the daemon and skill drift. You need to run `potpie doctor` periodically and refresh skills with `potpie skills install --agent <agent>`. Upgrades are likely via `uv tool upgrade potpie`, though the README does not specify. The setup wizard provisions config and storage, but you must ensure backups if you care about the graph's durability. The CLI is the primary interface, so any breaking changes in v2.0.0 would affect scripts. The README points to docs for exhaustive commands, but the provided material does not include upgrade notes. The project's GitHub Actions test workflow suggests CI is in place, but we cannot verify test coverage or stability from the supplied material.

Editorial conclusion

Adopt Potpie if you work with AI coding agents like Claude Code or Codex and need them to answer questions, plan changes, or debug with project-specific context drawn from code, history, and issue trackers. Do not adopt it if you need a fully managed, hosted solution or if your team relies on a harness not listed, such as JetBrains or VS Code Copilot, since Potpie only ships skills for Claude Code, Codex, Cursor, and OpenCode. Before committing, verify that your integrations (GitHub, Linear, Jira, Confluence) are supported and that your team can run a local daemon and CLI, since Potpie is CLI-first and requires local setup. Also check the docs for the depth of graph quality checks and whether the v2.0.0 release notes address any known issues with large monorepos.

Official sources

1. Official documentation
2. Official README
3. Project repository
4. Release notes