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.
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.
- 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.
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.
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 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.
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.