potpie-ai /potpie

Context Graph for AI Native SDLC

★ 5,800⑂ 697👁 33⑃ 932● 171▤ 23
PythonApache-2.0Created 2024-08-12potpie.ai
Download: v2.0.1v2.0.1 ↓2.0.12026-08-31
+1
Daily
5,800
stars
697
forks
33
watchers
932
prs
171
issues
23
releases

README

Potpie turns your codebase and software development lifecycle into a living 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.

!Potpie context graph demo

 Install and setup Potpie

 Step 1: install the CLI through PyPI with uv or pip:

bash
uv tool install potpie


or:

bash
python3 -m pip install --user potpie


 [!NOTE]
 uv tool install potpie is recommended for CLI installs because global
 mutation of Python packages is generally not recommended.

 Step 2: Run the Potpie setup wizard

bash
potpie setup


The setup wizard provisions local config, storage, the daemon, a default pot, and
agent skills. It also lets you choose integrations and the coding harness Potpie
should configure.

!Potpie setup wizard

 Step 3: Open your configured harness

Potpie is already integrated into your selected harness.
You can start using Potpie with the repo of your choice.

Open your previously selected harness and ask it to use Potpie for the repo.
!Potpie in OpenAI Codex


 [!NOTE]
 You don't need to run a separate manual ingest command. The CLI registers
 sources and the configured agent can ingest or update project context when the
 task requires it.

You can view your context graph in the web UI:

bash
potpie ui


This will open a graph explorer in your browser.
!Potpie web UI

 Basic CLI user checklist

The main CLI commands are:

| Command | Purpose |
| --- | --- |
| potpie setup | Run first-time local setup for config, daemon, default pot, and agent skills. |
| potpie login | Sign in to Potpie for account-backed and managed features. |
| potpie github login / potpie linear login | Connect source integrations you want agents to use. |
| potpie status | Show context readiness for the active pot, including daemon, graph, and skill checks. |
| potpie auth status | Show configured integration auth status. |
| potpie auth status --verify | Verify integration credentials with lightweight API checks. |
| potpie doctor | Run local diagnostics for daemon, backend capabilities, and skill drift. |
| potpie source add repo . | Register the current repo as a source for the resolved pot. |
| potpie pot list / potpie pot use  | List pots and choose the active workspace. |
| potpie resolve "" | Pull the context an agent should read before doing a task. |
| potpie search "" | Look up a specific file, workflow, bug, decision, or convention. |
| potpie record --type  --summary "" | Write a durable project learning. |
| potpie graph ... | Use lower-level graph reads, quality checks, proposals, and commits. |
| potpie ui | Open the local graph explorer served by the daemon. |
| potpie skills install --agent  | Install or refresh Potpie guidance for an agent harness. |

Examples:

bash
potpie setup --repo . --agent claude
potpie github login
potpie auth status
potpie status
potpie source add rep

Top issues

Discussions

Latest release

v2.0.1 v2.0.1 2026-08-31
v2.0.1

Potpie v2.0.1 strengthens the local-first Potpie architecture with a unified Context Engine runtime, cleaner CLI and daemon boundaries, a public context-graph runtime, and more reliable local agent workflows.

This release also publishes potpie-context-engine v0.2.0, consolidating the Context Engine under the potpie_context_engine namespace and introducing typed contracts for local and daemon execution.

 Highlights

 Unified Context Engine runtime

Potpie now uses one importable Context Engine, one Potpie-owned resource manager, and matching typed contracts for in-process an

Snapshot: 2026-11-16T09:23:14Z · Data license Apache-2.0 · JSON