Metadata-Version: 2.4
Name: potpie
Version: 2.0.0b1
Summary: Potpie context-engine distribution.
Project-URL: Homepage, https://potpie.ai
Project-URL: Documentation, https://docs.potpie.ai
Project-URL: Source, https://github.com/potpie-ai/potpie
Project-URL: Issues, https://github.com/potpie-ai/potpie/issues
Author-email: Potpie AI <engineering@potpie.ai>
Maintainer-email: Potpie AI <engineering@potpie.ai>
License-Expression: Apache-2.0
License-File: LICENSE
Keywords: agents,ai,code-intelligence,developer-tools,knowledge-graph
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Framework :: FastAPI
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development
Requires-Python: <3.14,>=3.12
Requires-Dist: potpie-context-engine[all]==0.1.0b1
Description-Content-Type: text/markdown

<p align="center">
  <a href="https://potpie.ai?utm_source=github">
    <picture>
      <source media="(prefers-color-scheme: dark)" srcset="./assets/readme_logo_dark.svg" />
      <source media="(prefers-color-scheme: light)" srcset="./assets/readme_logo_light.svg" />
      <img src="./assets/logo_light.svg" alt="Potpie AI logo" />
    </picture>
  </a>
</p>

<p align="center">
  <a href="https://docs.potpie.ai"><img src="https://img.shields.io/badge/Docs-potpie.ai-111827?style=for-the-badge&logo=readthedocs&logoColor=white&labelColor=22c55e" alt="Docs"></a>
  <a href="https://github.com/potpie-ai/potpie/actions/workflows/test.yml"><img src="https://img.shields.io/github/actions/workflow/status/potpie-ai/potpie/test.yml?branch=main&style=for-the-badge&label=Tests&logo=githubactions&logoColor=white&labelColor=111827" alt="Tests"></a>
  <a href="https://discord.gg/ryk5CMD5v6"><img src="https://img.shields.io/badge/Discord-Join-5865F2?style=for-the-badge&logo=discord&logoColor=white&labelColor=111827" alt="Discord"></a>
  <a href="./LICENSE"><img src="https://img.shields.io/github/license/potpie-ai/potpie?style=for-the-badge&label=License&color=64748b&labelColor=111827" alt="Apache 2.0"></a>
</p>

[Potpie](https://potpie.ai) 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.

![](assets/context_graph.gif)

## Install and setup Potpie

### Step 1: install the CLI through [pypi](https://pypi.org/project/potpie/) 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.

![alt text](assets/wiz_screen.png)

### 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.
![alt text](assets/codex_potpie.png)


> [!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.
![alt text](assets/web_ui.png)

## 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 configured integration auth status. |
| `potpie status --verify` | Verify integration credentials with lightweight API checks. |
| `potpie status --host` | Check daemon, pot, graph, and skill readiness. |
| `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 <id-or-name>` | List pots and choose the active workspace. |
| `potpie resolve "<task>"` | Pull the context an agent should read before doing a task. |
| `potpie search "<query>"` | Look up a specific file, workflow, bug, decision, or convention. |
| `potpie record --type <type> --summary "<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 <agent>` | Install or refresh Potpie guidance for an agent harness. |

Examples:

```bash
potpie setup --repo . --agent claude
potpie github login
potpie status --host
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 context-engine CLI for graph work"
```

You can find an exhaustive list with more examples in our [docs](https://docs.potpie.ai).

## 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](https://github.com/potpie-ai/potpie/issues/new/choose).

### Integrations

| Tool | Description |
| --- | --- |
| ![GitHub][github-badge] | Index repositories, pull requests, issues, reviews and source history. |
| ![Linear][linear-badge] | Index teams, issues, projects and documents. |
| ![Jira][jira-badge] | Index projects, issues, status and changelog context. |
| ![Confluence][confluence-badge] | Index spaces, pages, runbooks and decisions. |

### Coding harnesses

| Tool | Description |
| --- | --- |
| ![Claude Code][claude-badge] | Install Potpie instructions and skills for Claude Code. |
| ![OpenAI Codex][codex-badge] | Install Potpie instructions and skills for OpenAI Codex. |
| ![Cursor][cursor-badge] | Install Potpie instructions and skills for Cursor. |
| ![OpenCode][opencode-badge] | Install Potpie skills for OpenCode. |

[github-badge]: https://img.shields.io/badge/GitHub-111827?style=flat-square&logo=github&logoColor=white
[linear-badge]: https://img.shields.io/badge/Linear-111827?style=flat-square&logo=linear&logoColor=white
[jira-badge]: https://img.shields.io/badge/Jira-111827?style=flat-square&logo=jira&logoColor=white
[confluence-badge]: https://img.shields.io/badge/Confluence-111827?style=flat-square&logo=confluence&logoColor=white
[claude-badge]: https://img.shields.io/badge/Claude%20Code-111827?style=flat-square&logo=anthropic&logoColor=white
[codex-badge]: https://img.shields.io/badge/OpenAI%20Codex-111827?style=flat-square&logo=openai&logoColor=white
[cursor-badge]: https://img.shields.io/badge/Cursor-111827?style=flat-square&logo=cursor&logoColor=white
[opencode-badge]: https://img.shields.io/badge/OpenCode-111827?style=flat-square&logo=opencode&logoColor=white

## 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`](./docs/context-graph/architecture.md).

## License

This project is licensed under the Apache 2.0 License. See [LICENSE](./LICENSE).


## Community & Support

- [GitHub Issues](https://github.com/potpie-ai/potpie/issues): bugs and repository-scoped requests
- [Discord](https://discord.gg/ryk5CMD5v6): community discussion and support
- [Docs](https://docs.potpie.ai): setup, product guides, and integration details

New contributions are always welcome. Read the [Contributing Guide](./.github/CONTRIBUTING.md)
to set up your environment, understand the workflow, and open a pull request.

<a href="https://github.com/potpie-ai/potpie/graphs/contributors">
  <img src="https://contributors-img.web.app/image?repo=potpie-ai/potpie" alt="Contributors" />
</a>
