# Potpie: a context graph for AI coding agents, installed from PyPI

> Potpie indexes a repository plus GitHub, Linear, Jira and Confluence into a graph that agents query before they plan or write code. It is a CLI-first Python tool, and the setup wizard does most of the work.

**potpie-ai/potpie** — Context Graph for AI Native SDLC. Potpie turns your codebase and software development lifecycle into a living context graph for AI agents.

- Repository: https://github.com/potpie-ai/potpie
- Website: https://potpie.ai
- Stars: 5,736 · Forks: 681
- Language: Python
- License: Apache-2.0
- Published: 2026-08-08 · Updated: 2026-08-18 · Language: en
- Canonical page: https://hysenlabs.com/projects/potpie-ai-potpie

## The problem Potpie targets: agents that do not know your repository

A coding agent dropped into an unfamiliar repository reads files and guesses. It does not know that the payments service was split out last year, that migrations are reviewed by one person, or that a particular module is frozen. Potpie's premise is that this missing context lives in places a model never sees: commit history, pull request discussion, issue trackers, runbooks and internal conventions. The README describes the project as turning "your codebase and software development lifecycle into a living context graph for AI agents", and the CLI exposes that graph through commands like potpie resolve and potpie search.

The audience is narrow but real. It is a team already using an agent harness (Claude Code, OpenAI Codex, Cursor, OpenCode) on a codebase large enough that repository knowledge is not obvious from the file tree. A solo developer on a small project will not get much from it. The project is published as version 2.0.1 in pyproject.toml with the classifier "Development Status :: 3 - Alpha", so treat the surface as moving.

## CLI-first architecture: a daemon, pots, and graph-backed skills

The README states plainly that "Potpie's current architecture is CLI-first", and that the CLI is designed to be used by both humans and agents. The distribution installs two entry points, declared in pyproject.toml: potpie, which maps to potpie.cli.main:main, and potpie-daemon, which maps to potpie.daemon.__main__:main. The daemon is what serves the local graph explorer and, per the Makefile comments, can run in-process so that code changes are live on the next invocation.

The unit of work is a pot, a workspace that resolves sources and skills. potpie source add repo . registers the current directory as a source for the resolved pot; potpie pot list and potpie pot use <id-or-name> switch between them. Integrations are the input side: GitHub for repositories, pull requests, issues, reviews and source history; Linear for teams, issues, projects and documents; Jira for projects, issues, status and changelog context; Confluence for spaces, pages, runbooks and decisions. The output side is agent skills, installed into a harness so the agent knows to call Potpie rather than read the repository blind.

The data flow has an unusual property worth noting: the README says you do not run a separate manual ingest command. Registration happens through the CLI, and "the configured agent can ingest or update project context when the task requires it". That means freshness depends on the agent deciding to refresh, not on a scheduled job. For a team that wants a predictable index timestamp, that is a design trade-off, not a feature.

## Installing the potpie CLI from PyPI and running the setup wizard

Installation is from PyPI. The README recommends uv for CLI installs, with a note that global mutation of Python packages is generally not recommended:

```bash
uv tool install potpie
```

The alternative given is a user-level pip install, which avoids touching the system interpreter:

```bash
python3 -m pip install --user potpie
```

After install, the setup wizard provisions local config, storage, the daemon, a default pot, and agent skills. It also prompts for integrations and for the coding harness Potpie should configure. The README shows a non-interactive form where both the repository and the harness are passed as flags:

```bash
potpie setup --repo . --agent claude
```

Once setup finishes, you open the harness you selected and ask it to use Potpie for the repository. There is no manual ingest step to run. To see what was built, potpie ui opens the graph explorer served by the daemon in your browser. A first real use is to ask for orientation before touching code:

```bash
potpie source add repo .
potpie resolve "what should I know before working in this repository?"
```

The first command registers the current directory as a source for the resolved pot. The second pulls the context an agent should read before doing a task. If the graph is empty or the daemon is not running, resolve is where the gap shows up first.

## What potpie status, doctor and auth status actually check

The CLI has a diagnostic layer, and it is more specific than a health endpoint. potpie status reports context readiness for the active pot, covering the daemon, the graph, and skill checks. potpie doctor runs local diagnostics for the daemon, backend capabilities, and skill drift. Skill drift is the interesting one: harnesses update their instruction formats, and an installed skill can fall out of date without anyone noticing. potpie skills install --agent <agent> refreshes that guidance.

Authentication is split. potpie login signs in for account-backed and managed features, while potpie github login and potpie linear login connect individual source integrations. potpie auth status shows what is configured, and potpie auth status --verify goes further with lightweight API checks against those credentials. That distinction matters in practice: a stored token can look present and still be revoked, and only the verify path will tell you.

There is also a write path. potpie record --type <type> --summary "<summary>" writes a durable project learning, and the README's example records a decision rather than a fact. This is how a team feeds conventions into the graph that no source integration would ever capture. potpie graph exposes lower-level reads, quality checks, proposals and commits for people who want to inspect or repair the graph directly.

## Limitations: alpha status, a pinned context engine, and a daemon you have to run

The most concrete constraint is in pyproject.toml. The package depends on potpie-context-engine[all]==0.2.0, an exact pin, and requires Python >=3.12,<3.15. An exact pin on the engine that does the indexing work means you cannot take a newer engine without waiting for a Potpie release, and the [all] extra pulls a wide dependency set into the same environment. The Makefile's own CLI target narrows the interpreter range further to >=3.12,<3.14, so the development path and the published distribution do not agree on supported Python versions. That is a small thing that will waste an afternoon.

Second, this is not a hosted product you point at a URL. There is a local daemon, local config and local storage, and the graph explorer is served by that daemon. The README does not document a remote-only mode, and it does not document rollback of a graph commit or a way to undo potpie record. If you need an audit trail of every write to the context graph, the README is silent on that.

Third, the integrations are the ceiling. GitHub, Linear, Jira and Confluence are listed; anything else is not. A team whose decisions live in Slack threads, a wiki the project does not index, or a self-hosted tracker gets a graph with holes, and the agent will answer confidently from the parts it has.

Finally, the classifier is Alpha and the release line moved fast: v2.0.0b1, then v2.0.0b3 six days later, then v2.0.0 nine days after that. The last push to the default branch was on 2026-06-18. The repository is not archived, but the README's command table is the contract you are building on, and it can change between minor versions.

## How Potpie differs from plain code search and from repo-wide indexing tools

The obvious alternative is not another context graph. It is the tooling already in the editor: ripgrep for text, a language server for symbol resolution, and the agent's own file-reading loop. That stack answers "where is this function called". It does not answer "why was this split into two services", because the answer is in a pull request from eighteen months ago, not in the code. Potpie's difference is that it ingests the discussion layer, not just the syntax layer, and stores it as a graph you can query with potpie search "authentication flow" or resolve before a task.

A second comparison is against retrieval over embeddings of source files. That approach indexes what the code says and returns similar-looking chunks. Potpie's graph is typed: sources, pots, skills, and recorded decisions with a --type field. A decision record is retrievable as a decision, not as a passage that happens to contain the word. The cost is that someone has to record the decisions, and the README gives no automation for that.

A third is the harness's own project-instruction file, the CLAUDE.md-style document many teams keep. That file is hand-written, short, and always in context. Potpie installs skills into the harness instead, so the guidance is refreshed by potpie skills install --agent <agent> and backed by a queryable graph. The trade-off is a running daemon and a local store versus a text file that costs nothing to maintain.

## Licence, maintenance and the cost of keeping the graph current

Potpie is licensed under Apache-2.0, declared both in the README and in pyproject.toml with license-files = ["LICENSE"]. Apache-2.0 permits commercial use and modification and includes a patent grant, but it also carries notice and attribution obligations when you redistribute. If you fork the CLI and ship it internally, read the LICENSE file rather than assuming the short form covers you. Nothing here is legal advice.

The upgrade cost is concentrated in two places. The exact potpie-context-engine==0.2.0 pin means upgrading Potpie upgrades the engine, so a version bump can change how the graph is built, not just how it is displayed. And the skills installed into your harness are versioned artifacts: potpie doctor reports skill drift, and potpie skills install --agent <agent> is the repair command. Budget for re-running the wizard's integration choices when a new source type lands.

The ongoing operational cost is the graph itself. Every integration is a credential to rotate (potpie auth status --verify is the check), and every recorded decision is a small piece of maintenance. A graph that nobody writes to slowly becomes a snapshot of the repository as it was on setup day, and an agent reading a stale graph is worse than an agent reading the current files.

## Conclusion

Adopt Potpie if your team already runs Claude Code, Codex, Cursor or OpenCode and loses time re-explaining repository conventions, and if you can connect GitHub, Linear, Jira or Confluence as sources. Skip it if you want a hosted service with no local daemon, or if you only need single-file code search, where a plain grep or language server is cheaper. Before rolling it out, run potpie doctor and potpie auth status --verify on one repository, confirm the graph the daemon builds matches what your team believes about the codebase, and check whether the PyPI package's potpie-context-engine[all]==0.2.0 pin conflicts with anything already in your environment.

## FAQ

### What is Potpie AI?

Potpie is an open source Python CLI that turns a codebase and its software development lifecycle into a context graph for AI agents. It indexes code, structure, decisions, source history, team knowledge and engineering workflows so agents can answer questions, plan changes, debug failures and write code with project-specific context.

### How do I install the Potpie CLI?

The README gives two options: uv tool install potpie, which it recommends for CLI installs, or python3 -m pip install --user potpie. After installing, run potpie setup to provision local config, storage, the daemon, a default pot and agent skills.

### Which coding harnesses and integrations does Potpie support?

The README lists GitHub, Linear, Jira and Confluence as integrations, and Claude Code, OpenAI Codex, Cursor and OpenCode as coding harnesses. The setup wizard lets you choose which integrations to connect and which harness Potpie should configure.

### Do I need to run a separate ingest command after setup?

No. The README states you do not need to run a separate manual ingest command, because the CLI registers sources and the configured agent can ingest or update project context when the task requires it.

### What Python versions does Potpie require?

pyproject.toml declares requires-python >=3.12,<3.15 and classifies the package for Python 3.12, 3.13 and 3.14. The Makefile's CLI install target narrows its own range to >=3.12,<3.14.

### How do I check whether Potpie is working correctly?

The README lists potpie status for context readiness of the active pot, including daemon, graph and skill checks, and potpie doctor for local diagnostics covering the daemon, backend capabilities and skill drift. For integrations, potpie auth status --verify runs lightweight API checks against the configured credentials.

## Sources

- [Official documentation](https://potpie.ai)
- [Official README](https://github.com/potpie-ai/potpie#readme)
- [Project repository](https://github.com/potpie-ai/potpie)
- [Release notes](https://github.com/potpie-ai/potpie/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/potpie-ai-potpie