Potpie: Detailed Introduction

[ikaijua]

Potpie: Detailed Introduction

A context layer for existing agents, organizing code, history, and team knowledge into a searchable graph.

• Audience: Teams and developers needing cross-file understanding, durable decisions, and context for existing agents.
• Cost: The repository is Apache-2.0; model and managed-service costs are separate.

Official account & key contributors on X

• Potpie (@potpiedotai)

Table of Contents

Getting started

1. What it is and who it is for
2. Access and setup: your first session

Usage and configuration

3. A concrete task and how to check it
4. Costs: software, models, and execution
5. Configuration and extensions

Limits and references

6. Permissions, data, and limitations
7. Frequently asked questions
8. Official references

Use the contents to jump to each section. If an in-page link does not respond, open it in a new tab.

[ikaijua]

What it is and who it is for

In one sentence: A context layer for existing agents, organizing code, history, and team knowledge into a searchable graph.

Who it suits: Teams and developers needing cross-file understanding, durable decisions, and context for existing agents.

What you can do:

• Query code structure, decisions, and workflows.
• Retrieve context for debugging and changes.
• Record durable project knowledge.

Where to start: Install the current CLI from the repository, then initialize it as described below.

Cost: The repository is Apache-2.0; model and managed-service costs are separate.

[ikaijua]

Access and setup: your first session

Install the current CLI from the repository:

uv tool install potpie
potpie setup
potpie status

Setup configures storage, a daemon, workspace, and agent integration. potpie ui opens the graph explorer. Verify status before using it from the host agent.

[ikaijua]

A concrete task and how to check it

Register a test repository and investigate one cross-module question.

potpie source add repo .
potpie resolve "what should I know before working in this repository?"
potpie search "authentication flow"

Trace token creation through validation, checking returned files and conventions against the current branch rather than trusting stale context.

[ikaijua]

Costs: software, models, and execution

Distinguish the open CLI, inference, and account-backed managed capabilities. Check applicable charges for models, integrations, and commercial Context Engine services.

Validate one repository before indexing extensive history and team documents.

[ikaijua]

Configuration and extensions

Integrations include GitHub, Linear, Jira, and Confluence; supported host agents receive instructions and skills.

Use potpie pot list and potpie pot use for workspaces and potpie record for durable learning. Check potpie auth status and avoid recording one project’s facts in another workspace.

[ikaijua]

Permissions, data, and limitations

Graphs and retrieval can omit or retain stale information; source, tests, and runtime behavior remain verification evidence.

Integrations can access code, issues, documents, and history. Scope authorizations to the workspace. CLI-first does not imply wholly offline processing.

[ikaijua]

Frequently asked questions

Does it replace my agent? It generally supplies context to an existing one.

Must I manually ingest? Current guidance lets the configured agent ingest or update when needed.

How do I troubleshoot? Start with potpie status, potpie doctor, and integration authorization.

[ikaijua]

Official references

• Repository
• Docs
• Architecture
• License