Potpie: Context Graph for AI-Native SDLC
Turns your codebase and engineering workflow into a living context graph, so AI agents can answer, plan, and code with project-specific context.
- Source repo
- potpie-ai/potpie
- Stars
- ★ 5.7k
- Last updated
- today
- License
- Apache-2.0
- Primary language
- Python
- FA score
- 47/100 · Major gaps
At a glance
- How it runs
- Works with
- Universal · cross-platformChatGPT · Codex · Claude Code
- Cost
- Free software; you pay for model usage
- Setup effort
- Low · running in minutes
- You'll need
- Typical use
- An onboarding developer runs
potpie resolve "what should I know before working in this repository?"to get a quick overview of the codebase and shorten ramp-up time. - Not a fit if
- Users who prefer a GUI over a command-line workflow
- Teams needing integrations beyond GitHub, Linear, Jira, and Confluence
- Source review
- 47/100 · Major gaps 1 safety controls not found
What does this agent do, and when should you use it?
Potpie is an open-source, CLI-first tool that maps your codebase and software development lifecycle into a context graph for AI agents. It indexes code, structure, decisions, source history, team knowledge, and engineering workflows, and provides a potpie CLI, a background daemon, a web UI, and integrations with GitHub, Linear, Jira, and Confluence. After initial setup via potpie setup, users can connect their tools, register the current repo as a source, and have agents pull context with commands like potpie resolve and potpie search. Potpie also supports installing skills and guidance into coding harnesses such as Claude Code, OpenAI Codex, Cursor, and OpenCode. Agents ingest or update context on demand, so no manual pre-ingestion is required. The project is licensed under Apache 2.0 and offers documentation, a Discord community, and a contributing guide.
Potpie operates through a CLI and daemon: potpie setup provisions local config, storage, daemon, a default pot, and agent skills; potpie github login and potpie linear login establish integration auth; potpie source add repo . registers the current repo as a source. Then, potpie status checks context readiness, potpie resolve "<task>" pulls the context an agent should read before a task, potpie search "<query>" looks up specific files, workflows, bugs, decisions, or conventions, and potpie record --type <type> --summary "<summary>" writes durable project learnings. The web UI is launched with potpie ui to explore the graph, and lower-level graph operations (reads, quality checks, proposals, commits) are available via potpie graph. Finally, potpie skills install --agent <agent> installs or refreshes guidance for a harness. The end-to-end flow is: configure integrations → register source → agent ingests on demand → query or resolve to get context → use it in coding tasks.
- An onboarding developer runs
potpie resolve "what should I know before working in this repository?"to get a quick overview of the codebase and shorten ramp-up time. - An engineer about to modify a feature runs
potpie search "authentication flow"to locate relevant files, workflows, and decision records. - A team using Claude Code configures Potpie with
potpie setup --agent claudeso Claude automatically gets project context during coding. - A developer using OpenAI Codex asks the agent to use Potpie for a repo, leveraging graph data to plan changes.
- A team using Jira and Confluence benefits from Potpie indexing issues and pages, enabling agents to answer questions about project status.
- A team records decisions with
potpie record --type decision --summary "..."to persist knowledge for future agents and members.
How do you install or deploy this agent?
Install the CLI via PyPI with uv or pip:
uv tool install potpieor:
python3 -m pip install --user potpieThe first is recommended to avoid global Python package mutation. After installation, run potpie setup to launch the setup wizard.
How do you use this agent?
- Run
potpie setup; the wizard configures local config, storage, daemon, default pot, and agent skills, and lets you choose integrations and a coding harness. - Run
potpie github loginorpotpie linear loginto connect desired integrations. - In your repository, run
potpie source add repo .to register it as a source. - Use
potpie statusto check context readiness. - In your configured harness (e.g., Claude Code, Codex), ask it to use Potpie for the repo.
- Use
potpie resolve "<task>"orpotpie search "<query>"to retrieve context. - Run
potpie uito view the context graph in your browser.
What are this agent's strengths and limitations?
- Provides a unified context graph of code, decisions, and workflows, offering richer project context than fragmented RAG retrieval.
- CLI is designed for both humans and agents, with easy integration into multiple coding harnesses (Claude Code, Codex, Cursor, OpenCode).
- Supports popular tools like GitHub, Linear, Jira, and Confluence, indexing PRs, issues, and docs.
- Apache 2.0 license allows free use and modification, with official documentation and community support.
- CLI-first approach may have a learning curve for non-technical users or those preferring GUI.
- Current integrations are limited; custom integrations require waiting for official support or building your own.
- Requires Python environment and network access, which may not suit offline or restricted environments.
- As an emerging project, the ecosystem and third-party documentation may be less mature, relying on official docs and community.
How does this agent compare with similar options?
Key facts side by side with the most closely related agents.
| Agent | Source review | Form / cost | Stars | Updated | Language | Full support on |
|---|---|---|---|---|---|---|
| Potpie: Context Graph for AI-Native SDLC This agent | 47 · Major gaps | CLIFree + model costs | ★ 5.7k | today | Python | ChatGPT · Codex · Claude Code |
| Mnemon — Persistent Memory Engine for AI Agents | 74 · Some gaps | CLIFree | ★ 639 | today | Go | Codex · Claude Code |
| Open SWE | 68 · Some gaps | Self-hosted serviceFree + model costs | ★ 11k | today | Python | OpenAI API |
| Graphify – Turn Any Codebase into a Queryable Knowledge Graph | 64 · Some gaps | CLIFree | ★ 129k | 2d ago | Python | Codex · Claude Code |
How does FollowAgents rate this agent?
Why each dimension lost points
Evidence shows CLI requires user login and authorized integrations (e.g., GitHub, Linear), but least privilege principle or permission scope is not explicit. User confirmation exists (e.g., setup wizard, login commands) but detailed confirmation flows are not described. Data flow transparency is limited; README mentions indexing code and SDLC but not how data is transmitted or stored. Sensitive data handling is not explicit; though dependency security is addressed (e.g., CVE fixes), handling of API keys etc. is not described. External effects include starting daemon and installing skills, but impact scope is not stated. Rollback mechanism is not mentioned. Source attribution has authors and license, but publisher is unverified.
Self-consistency is good; README, pyproject, and test config align, but detailed error handling documentation is absent. Dependency availability has explicit versions and CVE fixes, but no availability guarantees. Failure messages are not detailed; only doctor command mentioned.
Target audience is clear (developers, AI agents), scenarios are diverse (answering, planning, debugging). Capability boundaries are not explicit, e.g., supported codebase size or languages. Trigger precision is not detailed, e.g., how resolve command decides context. Environment fit has Python version and OS support, but specific environment requirements are not stated.
Information architecture is clear with README, docs links, and architecture doc. Install notes are detailed with steps and commands. Naming is stable, but version 2.0.0 may conflict with Alpha status. Examples and FAQ have basic examples but no FAQ. Known limitations are not explicit. License is Apache-2.0, complete. Versioning changelog is absent. Maintenance responsibility has authors and contributing guide, but publisher is unverified.
Output usability has CLI commands and UI, but no output format examples. Marginal value is high, providing context graph. Cost-benefit is not detailed, but many dependencies may increase deployment cost.
Claim traceability is limited; README claims features but no evidence. Cross-source corroboration has test config and CI, but not independently verified. Fact-inference separation is not explicit; docs may mix.
- Not found in source: rollback or recovery pathBack up first, or work on a git branch or snapshot, so its changes can be undone.
- Publisher identity is unverified; be cautious about supply chain risks.
- No rollback mechanism is provided; updates or config changes may not be reversible.
- Sensitive data handling details are unclear; review data storage and transmission.
- Many dependencies, including large libraries like torch, increase deployment cost.
Recent releases
Latest entries from the project's GitHub Releases. Notes are quoted from upstream as written, not rewritten or tested by FollowAgents.
-
Release notes excerpt
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 …View on GitHub ↗ -
Release notes excerpt
Potpie v2.0.0 Potpie v2.0.0 introduces the new local-first Potpie architecture: a packaged CLI, local context engine, daemon workflow, and agent-facing context graph designed for installation and use outside the development repository. This release makes Potpie’s context graph available through the main potpie package and the potpie-context-engine package, giving users a cleaner way to install, set up, and validate local repository context, CLI workflows, and agent integrations. Highlights Local Context Engine and CLI …View on GitHub ↗ -
Release notes excerpt
v1.1.1 This release candidate focuses on improving the developer experience around @ file mentions and fuzzy file search. The main change is the backend foundation for fetching repository file structure before repo initialization. This supports a faster and more reliable @ file search experience, where users can type @ and fuzzy search file or directory names for mentions. The implementation is designed to work from local bare repositories and Git refs, avoiding GitHub API limits and making it suitable for very large repositories. Key Changes 1. Improved @ file fuzzy search foundation …View on GitHub ↗
FAQ
Is Potpie free to use?
potpie login may involve account-backed features; check official docs for any commercial terms.What permissions do I need for GitHub or Linear?
potpie github login or potpie linear login, you grant access to read repositories, PRs, issues, etc. The exact scope is shown during the authorization flow.How do I update Potpie?
uv tool upgrade potpie or pip install --upgrade potpie. Additionally, potpie skills install --agent <agent> refreshes agent skills.How does the context graph stay up to date?
potpie source add repo ., the configured agent ingests or updates project context when the task requires it, so no manual refresh is needed.