potpie

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:

uv tool install potpie

or:

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

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:

potpie ui

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

Basic CLI user checklist

The main CLI commands are:

Examples:

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"

You can find an exhaustive list with more examples in our docs.

Integrations and Coding Harnesses

Potpie supports a variety of integrations and coding harnesses, with more coming. If your team needs a new integration or harness, please raise a ticket.

Integrations

Coding harnesses

Architecture

Potpie's current architecture is CLI-first. CLI is designed to be used by both humans and agents. Read the deeper architecture notes in docs/context-graph/architecture.md.

License

This project is licensed under the Apache 2.0 License. See LICENSE.

Community & Support

• GitHub Issues: bugs and repository-scoped requests
• Discord: community discussion and support
• Docs: setup, product guides, and integration details

New contributions are always welcome. Read the Contributing Guide to set up your environment, understand the workflow, and open a pull request.