# API Access
Source: https://docs.potpie.ai/agents/api-access
Use the Potpie API to parse repositories, create conversations, and query your codebase programmatically.
## Before you begin
* A Potpie account
* An API key ,if you don't have one yet see [Generate an API Key](/tutorials/generate-api-key)
Every request to the Potpie API requires an `x-api-key` header.
***
## Step 1 : Parse a repository
Parsing builds the [context graph](/concepts/context-engine) for your repository. Every subsequent API call like creating conversations, sending messages requires a `project_id` from this step.
```bash theme={null}
curl -X POST http://localhost:8001/api/v2/parse \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"repo_name": "owner/repo",
"branch_name": "main"
}'
```
**Request fields**
GitHub repository in `owner/repo` format. Required for cloud usage.
Absolute path to a local repository. Only works when `isDevelopmentMode=enabled`. Use this instead of `repo_name` for local development.
Branch to parse. If omitted, defaults to `null`.
Specific commit SHA to parse. If omitted, parses the latest commit on the branch.
**Response**
```json theme={null}
{ "project_id": "", "status": "submitted" }
```
Save the `project_id` . You'll use it in every request from here on.
***
## Step 2 : Wait for parsing to complete
Parsing runs asynchronously. Poll the status endpoint until `status` is `ready` before creating a conversation.
```bash theme={null}
curl http://localhost:8001/api/v2/parsing-status/ \
-H "x-api-key: YOUR_API_KEY"
```
**Response**
```json theme={null}
{ "status": "ready", "latest": true }
```
Status progresses through the following stages in order:
`submitted` → `cloned` → `parsed` → `processing` → `inferring` → `ready`
If parsing fails at any stage, `status` becomes `error`.
Do not create a conversation until `status` is `ready`. Requests made before parsing completes will fail.
To manage conversations and messages as separate steps, continue to [Step 3](#step-3--create-a-conversation). To create a conversation and send a message in a single request, jump to [create conversation and send message in one call](#create-conversation-and-send-message-in-one-call).
***
## Step 3 : Create a conversation
A conversation connects your project to an agent. Choose the agent based on what you want to do.
```bash theme={null}
curl -X POST http://localhost:8001/api/v2/conversations/ \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"project_ids": [""],
"agent_ids": ["codebase_qna_agent"]
}'
```
**Available agents**
Answers questions about how your codebase works like architecture, logic, dependencies.
Generates and modifies code based on your instructions, with awareness of existing patterns in the repo.
Produces technical specifications from codebase context or a description of what you want to build.
Traces bugs through the codebase and suggests fixes with file paths and line references.
**Response**
The call returns a `conversation_id`. Use it in all subsequent message requests.
***
## Step 4 : Send a message
Send your question or instruction to the conversation. Responses stream by default.
```bash theme={null}
curl -X POST http://localhost:8001/api/v2/conversations//message/?stream=true \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"content": "How is authentication implemented?"
}'
```
**Streaming response** (`stream=true`, default)
Chunks are yielded as JSON objects as they arrive:
```json theme={null}
{ "content": "Authentication is handled in...", "citations": ["app/auth/service.py"], "tool_calls": [] }
```
**Non-streaming response** (`stream=false`)
The full response is returned once the agent finishes:
```json theme={null}
{
"content": "Authentication is implemented in...",
"citations": ["app/auth/service.py", "app/middleware/auth.py"],
"tool_calls": []
}
```
***
## Create conversation and send message in one call
For quick, one-off queries you can skip managing a `conversation_id` entirely. This endpoint creates the conversation and sends the first message in a single request. The conversation is hidden from the UI by default.
```bash theme={null}
curl -X POST http://localhost:8001/api/v2/project//message/ \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"content": "How is authentication implemented?",
"agent_id": "codebase_qna_agent"
}'
```
**Request fields**
The project ID returned from parsing.
Whether to hide the conversation from the web UI. Defaults to `true`.
The message to send.
The agent to use. Defaults to `codebase_qna_agent`.
Optional array of node context objects to focus the query on specific code elements.
**Response**
```json theme={null}
{
"content": "Authentication is handled in...",
"citations": ["app/auth/service.py"],
"tool_calls": []
}
```
# Code Generation Agent
Source: https://docs.potpie.ai/agents/code-changes-agent
The Code Generation Agent reads your codebase's existing patterns and conventions before writing a single line, then generates code that fits naturally into what already exists.
If specific nodes are referenced in the query, it fetches their source code and appends it as code context.
## How It Works
### Understand the Task
The agent classifies every incoming task into one of five types:
* **New feature**
* **Modification**
* **Refactor**
* **Bug fix**
* **Multi-file change**
It extracts target files, classes, functions, scope, and dependencies.
For multi-file or complex tasks, the agent upfront identifies all impacted files and determines the order in which changes need to happen, resolving dependencies across files before writing anything.
### Explore the Codebase
The agent reads the codebase before writing anything. It starts by finding where the relevant feature or functionality lives, then understands the directory layout and module organization.
It retrieves specific named classes or functions, maps all call relationships, and fetches full files or specific line ranges as needed. It reads multiple files simultaneously when working across related modules, and also performs grep style content searches to surface naming conventions, import patterns, and usage sites across the codebase.
If the task involves domain best practices not present in the repo, it retrieves external references to inform the implementation. If no relevant files are found through normal navigation, it falls back to a tag-based search across the graph.
### Analyze Patterns
Before writing, the agent captures exact indentation, import order, naming conventions, string literal formats, and docstring style from the existing codebase.
It maps every import that needs to change, identifies all impacted files including tests, and documents any database schema or API contract changes.
### Write Code
Changes are written into a dedicated branch created at the start of every session. The agent works against a live view of each file as it evolves, re-fetching the current state before every operation so line numbers are always accurate after prior inserts or deletes.
After every operation, it re-fetches to verify the change applied correctly.
### Review and Apply
The agent displays all changes as a unified diff for you to review. Until you confirm, no changes are written to disk.
PR creation only happens upon your explicit confirmation. Once confirmed, the agent applies the patches, commits the changes, pushes them to the remote repository, and opens a pull request on GitHub or GitLab in a single step.
***
## Next Steps
* See [Codebase Q\&A Agent](/agents/qna-agent) to ask questions about your codebase
* See [Debugging Agent](/agents/debugging-agent) to trace and fix issues
# Debugging Agent
Source: https://docs.potpie.ai/agents/debugging-agent
The Debugging Agent traces issues through the [context graph](/concepts/context-engine) from where they surface to where they originate, identifies the root cause, and returns a targeted fix.
For a bug report, it runs a structured investigation that follows the issue to its source and systematically evaluates every viable fix location before recommending the most appropriate resolution.
If specific nodes are referenced in the query, it fetches their source code and appends it as code context.
## How It Works
### Understand the Problem
The agent immediately separates the reported symptom from any suggested fix. The suggested fix are noted and only the observed symptom is carried forward into the investigation.
It documents the real problem, the debugging principles it will follow, and the success criteria. It then breaks the investigation into traceable tasks before any navigation begins.
### Explore and Hypothesize
The agent formulates candidate hypotheses for what could cause the symptom. Each hypothesis is tracked and marked confirmed or eliminated as the investigation progresses.
Navigation follows the same broad-to-narrow pattern as the Q\&A Agent, moving from finding where relevant functionality lives in the [context graph](/concepts/context-engine) -> understanding directory layout and module organization -> retrieving specific files, functions, and call relationships. It reads files directly by path with optional line ranges, reads multiple files simultaneously when tracing across modules, and searches file contents by pattern to follow state through code paths not fully captured in the graph.
### Identify Root Cause
The agent traces in both directions from the symptom.
**Upstream** it follows the call chain backward to find where bad state was first introduced. **Downstream** it identifies what consumes the code's output and what assumptions those consumers make.
Whenever a reported bug represents a broader category rather than a single isolated case, the agent treats it as a pattern, enumerates all sibling instances across the codebase, and evaluates each one to determine whether the same issue is present elsewhere.
### Generalize
The agent evaluates every candidate fix location before recommending one. Different types of fix locations are :
* A **origin fix** prevents bad state from being created. This is always the preferred approach.
* A **transformation fix** corrects the issue during normal data processing. This is acceptable.
* A **boundary fix** validates inputs at API or module boundaries. This is acceptable.
* A **symptom fix** patches the issue where the bug appears rather than where it originates. This should be avoided.
* A **consumer guard** adds defensive checks in every consumer. This is considered a red flag.
After this two validation tests are used to confirm the fix is applied at the correct location.
1. The **Spreading Knowledge Test** asks whether other parts of the code still need to know about the edge case after the fix. If yes, the fix is too far downstream.
2. The **Future Bug Test** asks whether a new caller would automatically benefit from the fix. If no, the fix is too shallow.
### Design and Implement
The fix targets the origin or transformation point, reusing existing utilities and helpers where they exist.
The agent explains the fix with file path and line citations. Before returning, it verifies that the generalized issue, all affected components, and the designed fix are fully addressed.
***
## Calling the Agent
```bash theme={null}
curl -X POST http://localhost:8001/api/v2/conversations/ \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"project_ids": ["proj_abc123"],
"agent_ids": ["debugging_agent"]
}'
```
Once you have a `conversation_id`, describe the issue:
```bash theme={null}
curl -X POST http://localhost:8001/api/v2/conversations/conv_xyz789/message/ \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"content": "The auth token resets on every redirect. Happens only on OAuth flows."
}'
```
***
## Next Steps
* See [Codebase Q\&A Agent](/agents/qna-agent) to ask questions about your codebase
* See [Code Generation Agent](/agents/code-changes-agent) to generate and modify code
# Codebase Q&A Agent
Source: https://docs.potpie.ai/agents/qna-agent
The Codebase Q\&A Agent answers questions about your codebase by navigating the [context graph](/concepts/context-engine) to find relevant code, trace dependencies, and return cited answers.
Before the agent runs, it prepares two pieces of context automatically. If specific nodes are referenced in the query, it fetches their source code and appends it as code context. It also fetches the full file structure of the project. Both are injected into context before the agent processes your message.
## How It Works
### Understand the Question
The agent classifies every incoming question into one of four types:
* **What** covers functionality and purpose
* **How** covers implementation and flow
* **Where** covers location and usage sites
* **Why** covers rationale and design decisions
It extracts key entities such as class names, function names, and modules to determine scope.
For complex or multi-part questions, the agent tracks what needs answering and breaks exploration into individual tasks before any navigation begins.
### Navigate the Codebase
The agent moves from broad to narrow, starting by finding where relevant functionality lives in the knowledge graph. It then understands directory layout and module organization, retrieves specific named classes or functions, and batch-fetches all relevant nodes collected so far.
From there it maps what calls the code and what the code calls, retrieving full files or specific line ranges as needed, and reading multiple files simultaneously when broad context is required. It also searches file contents directly by pattern to locate usage sites and definitions not reachable through the graph alone. If the question involves a third-party library, the agent retrieves external documentation to supplement its answer when required.
### Respond
Answers are structured using clear section headings such as Main Answer, Details, Code Examples, and Related Components.
They are grounded in the codebase with **file path and line number citations** where relevant, and all code snippets are presented in fenced blocks with appropriate language tags for clarity.
Before returning, the agent verifies that all aspects of the question are answered and all exploration tasks are complete.
## Calling the Agent
```bash theme={null}
curl -X POST http://localhost:8001/api/v2/conversations/ \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"project_ids": ["proj_abc123"],
"agent_ids": ["codebase_qna_agent"]
}'
```
Once you have a `conversation_id`, send your question:
```bash theme={null}
curl -X POST http://localhost:8001/api/v2/conversations/conv_xyz789/message/ \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"content": "How is authentication implemented?"
}'
```
## Next Steps
* See [Debugging Agent](/agents/debugging-agent) to trace and fix issues across the codebase
* See [Code Generation Agent](/agents/code-changes-agent) to generate and modify code
# Tools Reference
Source: https://docs.potpie.ai/agents/tools-reference
**Custom agents** access specialized tools across six categories: **Knowledge Graph**, **Code Access**, **External**, **Project Management**, **Integration**, and **Code Changes**. Assign tools per task at agent creation to control what the agent can access during execution.
## Tool Categories
| Category | Description |
| ----------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
| [Knowledge Graph](#knowledge-graph-tools) | Query and traverse the codebase by node, tag, name, or semantic meaning |
| [Code Access](#code-access-tools) | Retrieve file contents, directory structures, and analyzed code element breakdowns |
| [External](#external-tools) | Search the web and extract content from external URLs |
| [Project Management](#project-management-tools) | Track tasks, requirements, and manage session-based workflows |
| [Integration](#integration-tools) | Connect with external services like GitHub, Jira, Linear, and Confluence |
| [Code Changes](#code-changes-management-tools) | Manage code modifications through a session-based change tracking system. Available exclusively to the Code Agent |
## Knowledge Graph Tools
Query and traverse the [context graph](/concepts/context-engine) by node name, ID, tag, or semantic meaning. These tools identify relevant nodes and map the relationships between them.
`ask_knowledge_graph_queries`
Execute natural language queries against the [context graph](/concepts/context-engine) using **vector similarity search** over docstring [embeddings](/concepts/inference). The primary tool for semantic codebase search.
**Parameters:**
* `query` (string, required): Natural language or structured query
* `project_id` (string, required): Project to query
**Returns:** Matching nodes, relationships, and relevance scores
`get_code_from_probable_node_name`
Search for nodes using a probable name match. Use when the exact node name is unknown. Accepts `file_path:function_name` or `file_path:class_name` format.
**Parameters:**
* `name` (string, required): Probable node name to search for
* `project_id` (string, required): Project to search within
**Returns:** Code content and metadata for matching nodes
`get_code_from_node_name`
Retrieve code using the exact node name.
**Parameters:**
* `name` (string, required): Exact node name
* `project_id` (string, required): Project to search within
**Returns:** Code content and node metadata
`get_code_from_node_id`
Fetch the exact code content for a specific node ID.
**Parameters:**
* `node_id` (string, required): The exact node ID to retrieve
**Returns:** Complete code content, file path, and node metadata
`get_code_from_multiple_node_ids`
Retrieve code from multiple node IDs in a single request.
**Parameters:**
* `node_ids` (string\[], required): Array of node IDs to retrieve
**Returns:** Array of code contents and metadata for each node
`get_nodes_from_tags`
Retrieve all code nodes matching one or more specified tags or labels.
**Parameters:**
* `tags` (string\[], required): Tags to filter by
* `project_id` (string, required): Project to search within
**Returns:** All nodes matching the specified tags
`get_code_graph_from_node_id`
Retrieve the dependency graph for a specific node by its ID. Works best with Python, JavaScript, and TypeScript repositories.
**Parameters:**
* `node_id` (string, required): Node ID to retrieve the graph for
**Returns:** Dependency graph with related nodes and edge types
`get_code_graph_from_node_name`
Retrieve the dependency graph for a node by its name. Works best with `.py`, `.js`, and `.ts` files.
**Parameters:**
* `name` (string, required): Node name to retrieve the graph for
* `project_id` (string, required): Project to search within
**Returns:** Dependency graph with related nodes and edge types
`get_node_neighbours_from_node_id`
Retrieve the immediate neighboring nodes in the [context graph](/concepts/context-engine) for a given node ID.
**Parameters:**
* `node_id` (string, required): Node ID to retrieve neighbors for
**Returns:** List of neighboring nodes with relationship types
`intelligent_code_graph`
Generate a filtered, context-aware code graph. Useful for reducing graph size in larger codebases while preserving the most relevant relationships.
**Parameters:**
* `node_id` (string, required): Starting node for the graph
* `project_id` (string, required): Project to query
**Returns:** Filtered dependency graph optimized for context relevance
## Code Access Tools
Retrieve file contents, directory structures, and structured code element breakdowns.
`get_code_file_structure`
Retrieve the complete directory structure and file organization of a project.
**Parameters:**
* `project_id` (string, required): Project to retrieve structure for
* `path` (string, optional): Specific path to retrieve (returns full tree if omitted)
**Returns:** Hierarchical file and directory structure
`fetch_file`
Read file contents with line numbers.
**Parameters:**
* `file_path` (string, required): Path to the file
* `project_id` (string, required): Project containing the file
**Returns:** File contents with line numbers
`analyze_code_structure`
Extract classes, functions, imports, and structural elements from a file.
**Parameters:**
* `file_path` (string, required): File to analyze
* `project_id` (string, required): Project containing the file
**Returns:** Structured representation of all code elements in the file
## Code Changes Management Tools
Available exclusively to the **Code Agent**. A **Redis-backed session** tracks all modifications with a 24-hour expiration. Export changes before the session expires.
`add_file_to_changes`
Create a new file in the current session.
**Parameters:**
* `file_path` (string, required): Path for the new file
* `content` (string, required): File content
**Returns:** Confirmation with file path
`update_file_in_changes`
Replace the entire content of an existing file in the session.
**Parameters:**
* `file_path` (string, required): File to update
* `new_content` (string, required): Replacement content
**Returns:** Update confirmation
`delete_file_in_changes`
Mark a file for deletion in the current session.
**Parameters:**
* `file_path` (string, required): File to delete
**Returns:** Deletion confirmation
`update_file_lines`
Modify a specific line range within a file.
**Parameters:**
* `file_path` (string, required): File to modify
* `start_line` (integer, required): First line of the range
* `end_line` (integer, required): Last line of the range
* `new_content` (string, required): Replacement content
**Returns:** Update confirmation
`replace_in_file`
Find and replace text within a file, with regex support.
**Parameters:**
* `file_path` (string, required): File to search in
* `pattern` (string, required): Search pattern (supports regex)
* `replacement` (string, required): Replacement text
**Returns:** Count of replacements made
`insert_lines`
Insert lines at a specific position within a file.
**Parameters:**
* `file_path` (string, required): File to modify
* `line_number` (integer, required): Position to insert at
* `content` (string, required): Content to insert
**Returns:** Insertion confirmation
`delete_lines`
Remove a specific line range from a file.
**Parameters:**
* `file_path` (string, required): File to modify
* `start_line` (integer, required): First line to delete
* `end_line` (integer, required): Last line to delete
**Returns:** Deletion confirmation
`get_file_from_changes`
Retrieve the current content of a file from the session, including all pending changes.
**Parameters:**
* `file_path` (string, required): File to retrieve
**Returns:** Current file content with all pending changes applied
`list_files_in_changes`
List all files modified in the current session.
**Returns:** List of file paths with their change types (added, modified, deleted)
`search_content_in_changes`
Search across all modified files in the session.
**Parameters:**
* `query` (string, required): Search query
* `regex` (boolean, optional): Enable regex matching
**Returns:** Matching results with file paths and line numbers
`clear_file_from_changes`
Revert all pending changes for a specific file.
**Parameters:**
* `file_path` (string, required): File to revert
**Returns:** Revert confirmation
`clear_all_changes`
Discard all changes tracked in the current session.
**Returns:** Clear confirmation
`get_changes_summary`
Get an overview of all modifications tracked in the current session.
**Returns:** Summary including file count, line changes, and change types
`get_changes_for_pr`
Retrieve a summary of all code changes for a given conversation. Used in delegated PR flows to verify changes exist in the session before calling `create_pr_workflow`.
**Parameters:**
* `conversation_id` (string, required): Conversation ID where changes are stored
**Returns:** List of changed files with change types and counts
`export_changes`
Generate a patch file or changeset for applying all session modifications.
**Parameters:**
* `format` (string, default: `dict`): Export format: `dict`, `list`, `json`, or `diff`
**Returns:** Formatted changeset ready for application
`show_updated_file`
View a file with all pending changes applied.
**Parameters:**
* `file_path` (string, required): File to view
**Returns:** Complete file content with all changes applied
`show_diff`
Display a unified diff of pending changes in the session.
**Parameters:**
* `file_path` (string, optional): Specific file to diff. Shows all pending changes if omitted.
**Returns:** Unified diff output
`get_file_diff`
Get a line-by-line diff for a specific file.
**Parameters:**
* `file_path` (string, required): File to diff
**Returns:** Line-by-line diff for the specified file
`get_session_metadata`
Retrieve session information and statistics.
**Returns:** Session ID, conversation ID, file count, and created/updated timestamps. All session data expires after 24 hours.
## External Tools
Search the web and extract content from external URLs to supplement codebase knowledge with external documentation and resources.
`web_search_tool`
Search external documentation, resources, and references.
**Parameters:**
* `query` (string, required): Search query
* `num_results` (integer, default: `5`): Number of results to return
**Returns:** Search results with titles, URLs, and snippets
`webpage_extractor`
Extract text content from a specific URL.
**Parameters:**
* `url` (string, required): URL to extract content from
**Returns:** Extracted text content and page metadata
`bash_command`
Execute read-only shell commands. Available only when the repository manager is active in the deployment. Agents cannot run commands that modify files or perform destructive operations.
**Parameters:**
* `command` (string, required): Shell command to execute
**Returns:** Command output
**Permitted use cases:** `git status`, directory listings, system information queries, read-only diagnostics.
## Project Management Tools
Track tasks, requirements, and manage session-based workflows for complex multi-step agent operations.
`add_todo`
Create a todo item to track work in the current session.
**Parameters:**
* `title` (string, required): Title of the todo item
* `description` (string, optional): Additional detail about the task
**Returns:** Todo ID and creation confirmation
`update_todo_status`
Update the completion status of an existing todo item.
**Parameters:**
* `todo_id` (string, required): ID of the todo to update
* `status` (string, required): New status: `pending`, `in_progress`, or `done`
**Returns:** Updated todo with new status
`get_todo`
Retrieve a specific todo item by ID.
**Parameters:**
* `todo_id` (string, required): ID of the todo to retrieve
**Returns:** Todo details including title, description, status, and notes
`read_todos`
List all todo items tracked in the current session.
**Returns:** All todo items with their statuses and notes
`add_todo_note`
Append a note to an existing todo item.
**Parameters:**
* `todo_id` (string, required): ID of the todo to update
* `note` (string, required): Note content to append
**Returns:** Updated todo with the new note
`get_todo_summary`
Get an overview of all todo items and their statuses in the current session.
**Returns:** Todo counts by status and a summary of pending and completed work
`add_requirements`
Store requirements or constraints for the current agent session.
**Parameters:**
* `requirements` (string, required): Requirements content to store
**Returns:** Confirmation of stored requirements
`get_requirements`
Retrieve requirements from the current session.
**Returns:** Stored requirements content
`delete_requirements`
Remove requirements from the current session. Available exclusively to the **Code Agent**.
**Returns:** Deletion confirmation
## Integration Tools
Connect with external services like GitHub, Jira, Linear, and Confluence to extend agent capabilities beyond the codebase.
### GitHub Tools
`github_tool`
Fetch GitHub issues and pull requests with full details including diffs.
**Parameters:**
* `repo` (string, required): Repository in `owner/repo` format
* `issue_or_pr_number` (integer, required): Issue or PR number to fetch
**Returns:** Title, description, status, assignee, labels, and diff (for PRs)
`code_provider_tool`
Read file contents from a repository.
**Parameters:**
* `repo` (string, required): Repository in `owner/repo` format
* `file_path` (string, required): Path to the file
**Returns:** File contents
`code_provider_create_branch`
Create a new branch from an existing branch or commit.
**Parameters:**
* `repo` (string, required): Repository in `owner/repo` format
* `branch_name` (string, required): Name for the new branch
* `source_branch` (string, required): Branch or commit to create from
**Returns:** Branch creation confirmation
`code_provider_update_file`
Modify file contents and commit the change.
**Parameters:**
* `repo` (string, required): Repository in `owner/repo` format
* `file_path` (string, required): Path to the file
* `content` (string, required): New file content
* `commit_message` (string, required): Commit message
**Returns:** Commit SHA and update confirmation
`code_provider_create_pr`
Create a pull request with a title, description, and reviewers.
**Parameters:**
* `repo` (string, required): Repository in `owner/repo` format
* `title` (string, required): PR title
* `head` (string, required): Source branch
* `base` (string, required): Target branch
* `body` (string, optional): PR description
**Returns:** PR URL and number
`code_provider_add_pr_comment`
Add a comment to a pull request or a specific line within it.
**Parameters:**
* `repo` (string, required): Repository in `owner/repo` format
* `pr_number` (integer, required): PR number
* `body` (string, required): Comment content
* `file_path` (string, optional): File path for inline comment
* `line` (integer, optional): Line number for inline comment
**Returns:** Comment URL and ID
### Linear Tools
`get_linear_issue`
Fetch detailed information about a Linear issue.
**Parameters:**
* `issue_id` (string, required): Issue ID or key (e.g. `ABC-123`)
**Returns:** Title, description, status, assignee, team, priority, URL, and timestamps
`update_linear_issue`
Update properties of a Linear issue.
**Parameters:**
* `issue_id` (string, required): Issue ID or key
* `input` (object, required): Fields to update — title, description, status, priority, assignee, team, or labels
**Returns:** Updated issue confirmation
### Jira Tools
`create_jira_issue_tool`
Create a new Jira issue in a project.
**Parameters:**
* `project_key` (string, required): Project key (e.g. `ENG`)
* `summary` (string, required): Issue title
* `description` (string, optional): Issue description
* `issue_type` (string, optional): Issue type (Bug, Task, Story)
* `priority` (string, optional): Priority level
**Returns:** Issue key and URL
`get_jira_issue_tool`
Fetch details for a Jira issue.
**Parameters:**
* `issue_key` (string, required): Issue key (e.g. `ENG-123`)
**Returns:** Title, description, status, assignee, priority, comments, and attachments
`update_jira_issue_tool`
Update fields on a Jira issue.
**Parameters:**
* `issue_key` (string, required): Issue key
* `fields` (object, required): Fields to update — description, assignee, priority, etc.
**Returns:** Update confirmation
`search_jira_issues_tool`
Search Jira issues using JQL.
**Parameters:**
* `jql` (string, required): JQL query string
* `max_results` (integer, optional): Maximum results to return
**Returns:** Matching issues with key, title, status, and assignee
`add_jira_comment_tool`
Add a comment to a Jira issue.
**Parameters:**
* `issue_key` (string, required): Issue key
* `body` (string, required): Comment content
**Returns:** Comment ID and URL
`transition_jira_issue_tool`
Move a Jira issue to a new status.
**Parameters:**
* `issue_key` (string, required): Issue key
* `transition` (string, required): Target status name (e.g. `In Progress`, `Done`)
**Returns:** Transition confirmation
`link_jira_issues_tool`
Create a link between two Jira issues.
**Parameters:**
* `inward_issue` (string, required): Source issue key
* `outward_issue` (string, required): Target issue key
* `link_type` (string, required): Link type — blocks, relates to, duplicates, clones
**Returns:** Link creation confirmation
`get_jira_projects_tool`
List all accessible Jira projects.
**Returns:** Project keys, names, and types
`get_jira_project_details_tool`
Get metadata for a specific Jira project.
**Parameters:**
* `project_key` (string, required): Project key
**Returns:** Project name, description, lead, issue types, and statuses
`get_jira_project_users_tool`
List members of a Jira project.
**Parameters:**
* `project_key` (string, required): Project key
**Returns:** User list with names and account IDs
### Confluence Tools
`get_confluence_spaces_tool`
List all accessible Confluence spaces.
**Returns:** Space keys, names, and types (global/personal)
`get_confluence_page_tool`
Retrieve a Confluence page by ID.
**Parameters:**
* `page_id` (string, required): Confluence page ID
**Returns:** Title, body content, version, space, and creator
`get_confluence_space_pages_tool`
List all pages in a Confluence space.
**Parameters:**
* `space_key` (string, required): Space key (e.g. `DOCS`)
**Returns:** Page list with titles, IDs, and creation dates
`search_confluence_pages_tool`
Search Confluence content using CQL.
**Parameters:**
* `cql` (string, required): CQL query string
* `limit` (integer, optional): Maximum results to return
**Returns:** Matching pages with title, space, and excerpt
`create_confluence_page_tool`
Create a new Confluence page.
**Parameters:**
* `space_key` (string, required): Space to create the page in
* `title` (string, required): Page title
* `content` (string, required): Page content (Markdown auto-converted to storage format)
* `parent_id` (string, optional): Parent page ID
**Returns:** Page ID and URL
`update_confluence_page_tool`
Update an existing Confluence page. Automatically increments version number.
**Parameters:**
* `page_id` (string, required): Page ID to update
* `title` (string, optional): New title
* `content` (string, optional): New content
**Returns:** Update confirmation with new version number
`add_confluence_comment_tool`
Add a comment to a Confluence page.
**Parameters:**
* `page_id` (string, required): Page ID
* `body` (string, required): Comment content
**Returns:** Comment ID and confirmation
### Change Detection
`change_detection`
Detect code changes in the current branch compared to the default branch and retrieve updated function details.
**Parameters:**
* `base_branch` (string, default: `main`): Branch to compare against
* `target_branch` (string, optional): Branch or commit to compare (defaults to current)
* `project_id` (string, required): Project to analyze
**Returns:** Changed files with diff information and impact analysis
# Ask
Source: https://docs.potpie.ai/build-flow/ask-a-question
**Potpie's Q&A interface**
![Completed response with citations]()
**Ask** answers questions about your codebase by navigating the [context graph](/concepts/context-engine) to find exactly what you need to know.
When a question involves a third-party library, it retrieves external documentation via `web search` if required. Follow-up questions in the same session retain full context from what came earlier
To start using Ask, see the [Explore Your Codebase tutorial](/tutorials/explore-your-codebase).
## How It Navigates
Prior to generating a response, Ask first classifies the question by type: **what** something does, **how** it works, **where** it lives, or **why** it was built that way.
Complex questions are broken into components and addressed one after other.
Beyond the knowledge graph, Ask reads files directly by path with optional line ranges, reads multiple files at once when broad context is needed, and searches file contents by pattern to pinpoint exact usage sites and definitions.
## How It Responds
Answers are structured with headers, code snippets, and citations to exact file locations. File paths are shown relative to the repository root. Every requirement for the question raised is verified before the response is returned.
## Using the API
For local workflows, start with the [CLI Overview](/cli/reference), parse the repository, and then query the graph directly from the terminal.
## Example uses
Understanding how authentication works before building a protected endpoint.
Mapping every dependency before touching a core service.
# Build a Feature
Source: https://docs.potpie.ai/build-flow/build-a-feature
**Potpie's code generation interface**
![Final review before PR]()
Potpie reads existing patterns, conventions, and dependencies from the [context graph](/concepts/context-engine) before initiating a line of code.
It maps the request against what already exists, generates a **specification** and architecture plan, and presents every change as a reviewable **diff**. The code it produces fits naturally into what already exists.
See [Make Code Changes](/tutorials/make-code-changes) for a complete walkthrough from writing code to opening a pull request.
## How It Works
Build starts by probing **clarifying questions** to lock-in the scope to generate a **specification** covering every file that needs to be created or modified.
During exploration, it reads files directly by path with optional line ranges, reads multiple files simultaneously when working across related modules, and performs **grep-style content searches** to identify naming conventions, import patterns, and existing usage across the codebase.
It then produces a **plan** showing what changes, in what order, and how new components relate to existing ones. Code is presented as a **diff** for every file touched.
Based upon the complexity of what's being built, Potpie automatically determines whether a **single agent** can handle the full task or whether **specialized subagents** should split the research and coding work.
## What It Produces
Every change is shown as a diff. Once approved, Potpie creates the **pull request**.
Nothing is generated speculatively. If a referenced file cannot be located in the codebase, Build is instructed to request clarification rather than fabricate code or assumptions that do not exist.
## Example uses
Updating authentication middleware across all protected routes.
Migrating a module with full dependency mapping before touching a line.
# Debug
Source: https://docs.potpie.ai/build-flow/debug-an-issue
**Potpie's bug investigation interface**
![Bug analysis and targeted fix]()
When a reported issue is received, it traverses the [context graph](/concepts/context-engine) across every affected component to determine the true origin of the problem.
It isolates the root cause to a specific file and line of code, and then returns a precise targeted fix, grounded in the actual implementation.
If you intend to trace an issue to its origin across the knowledge graph and get a fix at the source rather than a symptom patch, follow the [Trace and Fix Bugs tutorial](/tutorials/trace-and-fix).
## How It Investigates
User-reported symptoms and suggested fixes are treated as starting points for investigation, not conclusions. The goal is to find the real issue, which could often be upstream of where the problem surfaces.
It reads files directly by path with optional line ranges, reads multiple files simultaneously when tracing across modules, and searches file contents by pattern to follow state through code paths to their origin.
Once the origin is found, Debug evaluates where the fix should live. A fix at the source prevents the problem for every downstream caller automatically. A fix at the symptom only handles one path. Debug always identifies which type of fix it's applying and why.
For straightforward issues it runs end to end within a single agent, but delegates specialized subagents for problems spanning multiple services .
## Eight-step methodology
Potpie applies an **eight step methodology** to every issue:
Confirms the reported behavior against the codebase, identifies every component involved, and establishes what the correct behavior should be at the point of failure.
Traverses the relevant code paths in the [context graph](/concepts/context-engine) and generates candidate explanations for the failure.
Pins the failure to a specific file and line, identifying the exact instruction that introduces the faulty state.
Checks whether the same defect pattern appears elsewhere in the codebase.
Generates a targeted fix scoped to the **root cause**.
Evaluates the fix against edge cases and traces potential side effects through the [context graph](/concepts/context-engine).
Produces the corrected code with exact file paths and line references.
Validates the fix against the original failure and checks for regressions.
## What It Returns
The result is a root cause traced to its true origin, a clearly mapped path from origin to symptom, and a fix that resolves the underlying generalized issue rather than only the specific reported instance.
## Using the API
For local workflows, start with the [CLI Overview](/cli/reference), parse the repository, and then inspect the relevant graph slice before debugging through it.
## Example uses
Tracing a null pointer exception to its origin across service and data layers.
Tracing a memory leak in a long-running service to its source across object lifecycle and dependency chains.
# Forge
Source: https://docs.potpie.ai/build-flow/forge
As code generation becomes inexpensive, the constraint shifts from writing speed to architectural judgment. **Forge** is built for that constraint. Engineers define outcomes, boundaries, and invariants upfront, and agents handle implementation with full repository awareness and respect for existing patterns.
## Specification first
Before generating anything, Forge probes for:
* The desired outcome and scope
* Constraints and invariants the implementation must satisfy
* System boundaries and interface definitions
* Failure modes and validation strategies
This shifts the work from writing a code to reasoning about the system behaviour. Agents handle the implementation only once the **specification** is locked.
## Repository context
Forge reads the [context graph](/concepts/context-engine) for established abstraction layers, dependency direction rules, naming conventions, shared domain models, and prior architectural decisions. When introducing new functionality, Forge:
* Reuses existing abstractions
* Avoids duplicating domain logic
* Respects dependency boundaries
* Aligns with current error handling and testing patterns
Forge integrates seamlessly as it generates code with full repository context.
## Get Access
Forge is part of Potpie's enterprise offering. Reach out to learn more or explore the full set of [specialist agents](/build-flow/specialists).
# Overview
Source: https://docs.potpie.ai/build-flow/overview
With Potpie, developers can interact with their codebase in three distinct ways, via-asking questions, generating code, and debugging issues.
Every interaction mode operates on the same underlying knowledge graph, ensuring that every response is grounded in a consistent, structured understanding of the system.
## How It Works
Every interaction in Potpie, flows through a unified interface.
For every query, it includes the full conversation history, the active project context, and any specific files or nodes referred by the user.
Prior to any reasoning, the agent retrieves the actual source code associated with those references and loads it into context, thereby ensuring that all responses are grounded in real code rather than abstract summaries or descriptions.
Based upon the complexity of the task, Potpie either operates as a single agent or delegates execution to specialized subagents.
This orchestration is determined by the nature and scope of the request itself, not by any manual user configuration.
## Three Modes
**Ask** : for understanding the codebase. It answers questions about how something works, where something lives, what something does, and why something was built the way it was.
**Build** : for making changes. It reads existing patterns and conventions from the knowledge graph prior to writing a single line, and then generates code that matches the style and structure of the codebase.
**Debug** : for tracing issues. It follows a problem from where it surfaces back to where it originates, identifies the root cause in the graph, and returns a targeted fix.
# Recipe
Source: https://docs.potpie.ai/build-flow/recipe
**Recipe** is Potpie's durable workflow layer for orchestrating agents in production. While individual agents execute specialized tasks, Recipes define how those tasks are coordinated over time, with state management, retry policies, and failure handling built in.
## Triggers
| Trigger | When it runs |
| ------------ | ------------------------------------------------------------------------------------ |
| Scheduled | Time based execution on defined intervals via cron expressions or calendar schedules |
| Event driven | Repository changes, incident alerts, deployment events, or external system signals |
| Conditional | Adapts at runtime based on the outcome of prior steps or external conditions |
## Composability
Recipes orchestrate both predefined Potpie agents and custom agents:
* **Predefined agents** bring structured capabilities for code analysis, debugging, validation, Q\&A, and deployment checks
* **Custom agents** handle domain specific logic or internal business rules
## Integrations
Workflows span systems through built-in connections. Recipes connect across source control, CI/CD pipelines, observability platforms, ticketing systems, cloud infrastructure APIs, and internal data services. Potpie provides predefined, standardized integrations.
## Get Access
Recipe is part of Potpie's enterprise offering. Reach out to learn more.
# Specialists
Source: https://docs.potpie.ai/build-flow/specialists
**Specialists** are purpose-built agents designed to execute narrowly defined functions with precision and accountability rather than act as general conversational assistants. Their behavior is testable, measurable, and reproducible across runs.
## Available specialists
| Agent | What it does |
| --------------- | ----------------------------------------------------------------------------------------------------------------------- |
| Q\&A Agent | Retrieves and grounds answers in verified source material across large repositories |
| Debugging Agent | Traverses service relationships, analyzes diffs, validates contracts, and reproduces failures in sandboxed environments |
| Code Agent | Generates implementation ready code changes with full awareness of repository structure, patterns, and dependencies |
## Model compatibility
Specialists run consistently across all foundation model variants.As models improve, agents get better automatically without any changes to your workflows. The orchestration layer handles the differences between models so your outputs stay consistent and predictable.
## Composability
Specialists can be combined and orchestrated together without losing their individual precision. They work with your existing tools, respect access controls, and produce outputs you can trust in production.
## Get Access
Specialists are part of Potpie's enterprise offering. Reach out to learn more.
# Trace
Source: https://docs.potpie.ai/build-flow/trace
**Trace** is Potpie's incident investigation agent. It uses your [context graph](/concepts/context-engine) as the structural model of **expected system behavior** and investigates failures against that model.
When a failure surfaces, Trace uses the encoded structure of your codebase to **define the investigative scope** immediately, rather than reconstructing it through manual exploration.
## What Trace does
| | |
| ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Call graph traversal** | The **call graph** is traversed from the affected service outward. Every upstream caller and downstream dependency is mapped before a single log is read. |
| **Contract validation** | Logged requests are validated against `API` and `schema` contracts defined in code. A changed response shape or a silently diverged API surfaces as a `contract violation` with the affected path. |
| **Historical baseline** | The current repository state is compared with earlier states to identify structural changes and dependency regressions from the last stable version. |
| **Log analysis** | Provide a log snippet or file. Trace cross-references it against the knowledge graph and constrains the relevant entries to the `call paths` and services already in scope. |
Together, these steps estimate **blast radius** before a fix is applied. This eliminates the **grep tax** , the time spent manually searching for context during an incident.
When a latency spike appears in a service, Trace evaluates `contract compliance`, `dependency health`, scaling policies, and recent diffs in a single view. Deviations surface as `contract violations`, `dependency regressions`, or `invalid execution paths`, expressed in terms of impact and causality. Teams move directly from detection to remediation.
## Hypothesis tree
When logs do not establish causality, Trace shifts to structured hypothesis exploration. Instead of following one theory, it builds a **branching investigation tree** where each node is a concrete, testable hypothesis such as **configuration regression** , a **contract mismatch** Using historical baselines, Trace prioritizes promising branches, allocates effort accordingly, and eliminates weak paths early.
## Get Access
Trace is part of Potpie's enterprise offering. Reach out to learn more or explore the full set of [specialist agents](/build-flow/specialists).
# Context Commands
Source: https://docs.potpie.ai/cli/context-commands
Task-oriented context retrieval and durable learning commands: resolve, search, and record.
These commands are the smallest stable user-facing surface for interacting with Potpie's context engine.
## Command Family
| Command | Purpose |
| ---------------- | ---------------------------------------------------------------- |
| `potpie resolve` | Pull a bounded context package for a task. |
| `potpie search` | Run a narrow follow-up lookup against known entities or phrases. |
| `potpie record` | Persist a durable project learning back into the graph. |
Internally, these are treated as the core context contract. New use cases tend to become new option values rather than brand-new top-level commands.
## `potpie resolve`
```bash theme={null}
potpie resolve [OPTIONS] TASK
```
Pulls the context an agent or developer should read before starting work.
### Arguments
| Argument | Type | Description |
| -------- | ----- | --------------------------------------- |
| `task` | `str` | The task to pull context for. Required. |
### Options
| Option | Type | Description |
| ----------- | ----- | ------------------------------------------------------------------- |
| `--intent` | `str` | Work intent. Defaults to `feature`. |
| `--include` | `str` | Comma-separated include families to constrain the returned context. |
| `--mode` | `str` | Retrieval mode: `fast`, `balanced`, `verify`, or `deep`. |
| `--pot` | `str` | Pot to resolve against. |
### Examples
```bash theme={null}
potpie resolve "what should I know before working in this repository?"
potpie resolve "trace the authentication flow" --intent debug --mode deep
potpie resolve "prepare for a refactor of billing webhooks" --include code,history,decisions
```
## `potpie search`
```bash theme={null}
potpie search [OPTIONS] QUERY
```
Use this when you already know the rough phrase, entity, workflow, bug, or convention you need to narrow down.
### Arguments
| Argument | Type | Description |
| -------- | ----- | -------------------------------------- |
| `query` | `str` | Phrase or entity to look up. Required. |
### Options
| Option | Type | Description |
| ----------- | ----- | ---------------------- |
| `--include` | `str` | Include-family filter. |
| `--pot` | `str` | Pot to search. |
### Examples
```bash theme={null}
potpie search "authentication flow"
potpie search "deploy rollback runbook"
potpie search "rate limiter middleware" --include code,docs
```
## `potpie record`
```bash theme={null}
potpie record [OPTIONS]
```
Writes a durable project learning back into the context system.
### Options
| Option | Type | Description |
| ----------- | ----- | ----------------------------------------------------------------- |
| `--type` | `str` | Record type such as `fix`, `decision`, or `preference`. Required. |
| `--summary` | `str` | The durable learning to persist. Required. |
| `--scope` | `str` | Scope in `key:value` form, for example `service:inventory-svc`. |
| `--pot` | `str` | Pot to write into. |
### Examples
```bash theme={null}
potpie record --type decision --summary "Prefer the context-engine CLI for graph work"
potpie record --type fix --summary "Invoice retries depend on Stripe webhook idempotency" --scope service:billing
potpie record --type preference --summary "Use feature flags for staged rollouts" --scope team:platform
```
## When To Use Which
| Need | Command |
| --------------------------------------------------------- | --------- |
| "I am about to work on X. Give me the bounded context." | `resolve` |
| "I know the name or phrase. Narrow it down." | `search` |
| "This is important enough to keep in the project memory." | `record` |
## Typical Flow
```bash theme={null}
potpie resolve "debug intermittent webhook failures" --intent debug --mode verify
potpie search "stripe retry handler"
potpie record --type fix --summary "Webhook retries fan into the async retry worker" --scope service:payments
```
# Graph & Operations
Source: https://docs.potpie.ai/cli/graph-and-operations
Daemon, services, ledger, graph workbench, timeline, backend, skills, and cloud command families.
This page covers the operational and low-level command families that sit below the higher-level setup and context flows.
## Runtime Operations
### `potpie daemon`
Controls the local daemon lifecycle.
| Command | Purpose |
| ----------------------- | ---------------------------- |
| `potpie daemon start` | Start the detached daemon. |
| `potpie daemon status` | Show daemon status. |
| `potpie daemon logs` | Tail or inspect daemon logs. |
| `potpie daemon restart` | Restart the daemon. |
| `potpie daemon stop` | Stop the daemon. |
### `potpie service`
Controls supporting services used by the daemon environment.
| Command | Purpose |
| ----------------------- | -------------------------- |
| `potpie service up` | Start supporting services. |
| `potpie service down` | Stop supporting services. |
| `potpie service status` | Inspect service status. |
| `potpie service logs` | Inspect service logs. |
### `potpie backend`
Controls graph backend profiles and readiness.
| Command | Purpose |
| ------------------------------ | ---------------------------- |
| `potpie backend list` | List backend profiles. |
| `potpie backend status` | Show current backend status. |
| `potpie backend use ` | Select a backend profile. |
| `potpie backend doctor` | Run backend diagnostics. |
## Event Ledger
```bash theme={null}
potpie ledger COMMAND
```
| Command | Purpose |
| ---------------------------- | ---------------------------------------------------------- |
| `potpie ledger status` | Show current ledger binding and availability. |
| `potpie ledger query` | Inspect ledger event history without advancing the cursor. |
| `potpie ledger use` | Bind a managed or self-hosted event ledger. |
| `potpie ledger disconnect` | Clear the current ledger binding. |
| `potpie ledger pull` | Pull new events from the ledger. |
| `potpie ledger sources list` | List available ledger source connectors. |
## Graph Workbench
`potpie graph` is the low-level graph surface. This is where reads, search, proposals, commits, inbox review, quality checks, and bulk mutation flows live.
### Top-level graph commands
| Command | Purpose |
| ------------------- | -------------------------------------------------------------- |
| `catalog` | Discover contract versions, views, mutation ops, and ontology. |
| `read` | V2-style graph reads over named views. |
| `search-entities` | Resolve entities and claims before a write. |
| `mutate` | Legacy wrapper over propose + commit. |
| `mutation-template` | Emit a schema-only skeleton for `graph propose`. |
| `nudge` | Deterministic event-to-action policy engine. |
| `status` | Show graph readiness and status. |
| `describe` | Describe graph structures or views. |
| `neighborhood` | Read a local neighborhood around an entity or claim. |
| `propose` | Stage graph mutations. |
| `commit` | Commit proposed graph mutations. |
| `history` | Inspect graph mutation history. |
| `inspect` | Inspect graph internals or payloads. |
| `export` | Export graph data. |
| `import` | Import graph data. |
| `repair` | Run repair flows. |
### Important read/write helpers
#### `potpie graph read`
Use this for structured reads over a subgraph and named view.
Important options:
| Option | Description |
| ------------------------------------- | --------------------------------------------- |
| `--subgraph` | Canonical subgraph, for example `debugging`. |
| `--view` | Named view within that subgraph. |
| `--query` | Query text. |
| `--scope` | Scope filter in `key:value[,key:value]` form. |
| `--repo` / `--current` | Limit to a repo scope. |
| `--since`, `--until`, `--time-window` | Time filters. |
| `--depth`, `--direction` | Neighborhood traversal controls. |
| `--limit`, `--sort`, `--dedupe` | Result shaping. |
| `--format`, `--detail`, `--relations` | Output formatting controls. |
| `--pot` | Select a target pot. |
#### `potpie graph search-entities`
Use this before a write when you need exact entity or claim resolution.
Important options:
| Option | Description |
| ------------------------------------ | ------------------------------------------------------- |
| `--query` or `QUERY_ARG` | Entity or claim text to match. |
| `--type` | Entity label filter such as `Service`. |
| `--predicate` | Predicate filter. |
| `--subgraph` | Subgraph filter. |
| `--scope` | Scope filter. |
| `--truth` | Truth filter. |
| `--source-system`, `--source-family` | Source filters. |
| `--source-ref` | Exact source ref such as `github:owner/repo#issue/123`. |
| `--supporting-claims` | Include supporting claims in JSON output. |
#### `potpie graph mutation-template`
Print a schema-only mutation skeleton for `graph propose`.
Supported `--kind` values include:
* `bug-fix`
* `decision`
* `feature`
* `infra-snapshot`
* `preference`
* `preference-policy`
* `repo-baseline`
* `timeline-change`
* `timeline-event`
#### `potpie graph nudge`
Deterministic local event-to-action policy brain. It injects ranked context, prompts writes, or stays silent without calling a model.
| Option | Description |
| ----------- | --------------------------------------------------------------------------- |
| `--event` | Event type such as `session_start`, `pre_edit`, or `test_failed`. Required. |
| `--session` | Harness session id. Required. |
| `--path` | File path scope. |
| `--scope` | Scope filter. |
| `--query` | Symptom or intent text. |
| `--limit` | Max injected items, default `5`. |
| `--pot` | Pot target. |
### Inbox, quality, and bulk mutation flows
#### `potpie graph inbox`
| Command | Purpose |
| --------------- | ------------------------- |
| `add` | Add pending graph work. |
| `list` | List pending work items. |
| `show` | Inspect one work item. |
| `claim` | Claim an inbox item. |
| `mark-applied` | Mark an item as applied. |
| `mark-rejected` | Mark an item as rejected. |
| `close` | Close an inbox item. |
#### `potpie graph quality`
| Command | Purpose |
| ---------------------- | ----------------------------------- |
| `summary` | High-level quality summary. |
| `duplicate-candidates` | Find likely duplicates. |
| `stale-facts` | Detect stale facts. |
| `conflicting-claims` | Surface conflicting claims. |
| `orphan-entities` | Find orphaned entities. |
| `low-confidence` | Show low-confidence graph material. |
| `projection-drift` | Detect drift between projections. |
#### `potpie graph bulk`
| Command | Purpose |
| ------- | ------------------------------------------------------------ |
| `apply` | Apply many semantic mutations through propose/commit chunks. |
## Timeline Reads
### `potpie timeline recent`
Read recent project events from the active or current pot across repo sources.
| Option | Description |
| ------------------------------------- | -------------------------------------------- |
| `--query` | Query text |
| `--since`, `--until`, `--time-window` | Time filters |
| `--service` | Optional service scope |
| `--limit` | Result count, default `12` |
| `--format` | `auto`, `events`, `table`, `raw`, or `jsonl` |
| `--detail` | `compact` or `full` |
| `--relations` | `summary` or `full` |
| `--pot` | Pot target |
## Skills & Cloud
### `potpie skills`
| Command | Purpose |
| --------- | --------------------------------------------- |
| `list` | List installed skills for an agent and scope. |
| `install` | Install a skill or skill set. |
| `update` | Update skills. |
| `remove` | Remove one skill or all skills. |
| `status` | Show skill installation state. |
| `add` | Add a skill source. |
Common options:
* `--agent` defaults to `claude`
* `--scope` defaults to `global`
* `--path` overrides the target path
### `potpie cloud`
Managed profile and sync commands are present but still marked TODO-oriented.
| Command | Purpose |
| ------------------------------------------ | ------------------------------------------ |
| `potpie cloud login` | Authenticate managed profile access. |
| `potpie cloud status` | Inspect managed profile state. |
| `potpie cloud push --pot ` | Push pot state. |
| `potpie cloud pull --pot ` | Pull pot state. |
| `potpie cloud skills sync --agent ` | Sync managed skill catalog into a harness. |
# How to Use
Source: https://docs.potpie.ai/cli/how-to-use
Practical workflows for onboarding a project, retrieving context, debugging, and working with AI coding agents.
This page covers the common developer workflows you will use day-to-day with Potpie: onboarding a new repository, using context retrieval in your coding sessions, recording project memory, and working with source integrations.
If you have not yet installed the CLI and run first-time setup, start with [Installation](/cli/installation).
## The Core Workflow
Every Potpie session follows the same basic loop:
```mermaid theme={null}
flowchart LR
setup["setup or login"]
status["verify status"]
source["register sources"]
resolve["resolve context"]
work["work in harness"]
record["record learnings"]
setup --> status --> source --> resolve --> work --> record
record --> resolve
```
1. **Setup once** — `potpie setup --repo . --agent claude`
2. **Verify readiness** — `potpie status --host`
3. **Register your repo** — `potpie source add repo .`
4. **Resolve context before working** — `potpie resolve ""`
5. **Work in your harness** — the installed skill handles context calls automatically
6. **Record learnings** — `potpie record --type decision --summary "..."`
## Running the CLI
```bash theme={null}
potpie [--json] [--verbose] COMMAND [ARGS]...
```
Use `--json` to get machine-readable output for scripting or agent consumption:
```bash theme={null}
potpie resolve "billing webhook failures" --json | jq '.items'
```
Use `--verbose` or `-v` for full tracebacks when debugging CLI errors.
Every subcommand accepts `--help`:
```bash theme={null}
potpie resolve --help
potpie graph read --help
```
## Onboarding a Repository
When you start working with a new codebase, register it as a source in the active pot.
### 1. Confirm the active pot
```bash theme={null}
potpie pot info
```
After `potpie setup`, you will have a `default` pot already active. For a new project, you might create a dedicated pot:
```bash theme={null}
potpie pot create my-api --repo . --use
```
### 2. Register the repository
```bash theme={null}
potpie source add repo .
```
This records the repository path as a source for the active pot. It registers metadata — it does **not** scan or ingest the repository contents by itself.
Ingestion is demand-driven. When your AI harness calls `potpie resolve` or `potpie graph read`, the engine pulls the relevant project context on demand. You do not need a separate "index" command on the happy path.
### 3. Verify the source is registered
```bash theme={null}
potpie source list
potpie status --host
```
### 4. Register a GitHub remote (optional)
To let the engine pull PR history, code reviews, and source metadata from GitHub:
```bash theme={null}
potpie github login
potpie source add github potpie-ai/my-api
```
### Recommended onboarding sequence
```bash theme={null}
potpie setup --repo . --agent claude
potpie status --host
potpie github login
potpie source add repo .
potpie source add github my-org/my-api
potpie resolve "what should I know before working in this repository?"
potpie ui
```
## Retrieving Context for a Task
`potpie resolve` is the primary entry point for context retrieval. Call it with a natural-language description of your upcoming task, and it returns a scoped context package.
```bash theme={null}
potpie resolve TASK [OPTIONS]
```
### Basic usage
```bash theme={null}
potpie resolve "add rate limiting to the /api/payments endpoint"
```
### With intent
Use `--intent` to tell the engine what kind of work you are doing. It shapes which parts of the graph are prioritised.
| Intent | When to use |
| ------------------- | ----------------------------------------------- |
| `feature` (default) | Planning or building a new capability |
| `debug` | Investigating a failure or unexpected behaviour |
| `review` | Preparing for a code review or PR |
| `ops` | Infrastructure or operational context |
```bash theme={null}
potpie resolve "trace intermittent 500s in the checkout service" --intent debug
```
### With retrieval depth
Use `--mode` to control how deeply the engine reads the graph:
| Mode | Behaviour |
| ---------- | -------------------------------------------------------------------- |
| `fast` | Returns the most confident matches quickly. Good for frequent calls. |
| `balanced` | Default for most tasks. |
| `verify` | Cross-checks evidence before returning. |
| `deep` | Traverses full graph relationships. Use for complex debugging. |
```bash theme={null}
potpie resolve "trace all callers of AuthService.verify" --mode deep
```
### Constraining the context
Use `--include` to limit the retrieval to specific context families:
```bash theme={null}
potpie resolve "prepare for a refactor of billing webhooks" --include code,history,decisions
```
### JSON output for agent consumption
```bash theme={null}
potpie resolve "debug webhook failures" --json | jq '.items'
```
## Running a Narrow Search
Use `potpie search` when you know a specific phrase, file name, symbol, or entity and want a direct lookup rather than a full task context package.
```bash theme={null}
potpie search "rate limiter middleware"
potpie search "deploy rollback runbook"
potpie search "AuthService" --include code
```
`search` does not require a task description. It runs a narrow query against entity and claim indexes directly.
## Recording Project Memory
Use `potpie record` to save durable project learnings back into the graph. These recordings appear in future `resolve` results across sessions.
```bash theme={null}
potpie record --type TYPE --summary "SUMMARY" [--scope key:value]
```
### Record types
| Type | What to use it for |
| ------------ | ------------------------------------------------------- |
| `decision` | Architectural or process decisions the team has made |
| `fix` | A specific root cause and fix that should be remembered |
| `preference` | Team conventions and coding standards |
| `constraint` | Hard limits or non-negotiable requirements |
### Examples
```bash theme={null}
# Record an architectural decision
potpie record --type decision --summary "All new endpoints must use the shared rate-limiter middleware"
# Record a bug fix with service scope
potpie record --type fix \
--summary "Stripe webhook retries fan into the async retry worker, not the HTTP handler" \
--scope service:billing
# Record a team preference
potpie record --type preference \
--summary "Prefer feature flags for staged rollouts rather than direct config changes" \
--scope team:platform
```
### Scope keys
Use `--scope key:value` to associate a recording with a specific service, file, team, or feature. Scope is free-form `key:value` pairs separated by commas:
```bash theme={null}
--scope service:payments-api,env:production
```
## AI-Assisted Coding Workflow
When you run `potpie setup --repo . --agent claude`, Potpie installs a **skill** into Claude Code (or your chosen harness). This skill instructs the agent to call Potpie for context before editing code.
### What the agent does automatically
1. Before working on a task, the agent calls `potpie resolve ""`.
2. Potpie returns scoped context: relevant services, decisions, dependencies, and recent changes.
3. The agent reads this context and then proceeds with the task grounded in real project knowledge.
4. The agent may call `potpie search` for follow-up lookups or `potpie record` to capture important findings.
You do not need to intervene in this loop. Just open your harness and ask it to work on a task. The skill handles the context calls.
### Checking and refreshing skills
```bash theme={null}
potpie skills status --agent claude
potpie skills install --agent claude
```
### Updating skills after a Potpie upgrade
```bash theme={null}
potpie skills update --all --agent claude
```
## Debugging Workflows
For debugging tasks, use `--intent debug` with `resolve` and combine with `search` for follow-up entity lookups.
### Typical debug session
```bash theme={null}
# Get the relevant context for debugging
potpie resolve "intermittent 500s on POST /api/checkout" --intent debug --mode verify
# Look up the specific service handling checkout
potpie search "CheckoutService"
# Read the debugging subgraph for prior occurrences
potpie graph read --subgraph debugging --view prior_occurrences --scope service:checkout
# Read the recent timeline
potpie timeline recent --time-window 7d --service checkout
# After finding root cause, record the fix
potpie record --type fix \
--summary "Checkout 500s caused by missing retry logic on the inventory lock" \
--scope service:checkout
```
## Feature Development Workflow
For building new features, start with `resolve` to understand the codebase before touching code.
```bash theme={null}
# Get the feature context before starting
potpie resolve "add webhook signature validation to the payments integration" --intent feature
# Narrow down the relevant service
potpie search "PaymentsWebhookHandler"
# Read the graph for architecture topology
potpie graph read --subgraph architecture --view service_map
# After building, record any important decisions made
potpie record --type decision \
--summary "Webhook signatures validated using HMAC-SHA256, key stored in secrets manager" \
--scope service:payments
```
## Code Review Preparation
Before reviewing a PR, resolve context to understand the blast radius and relevant decisions:
```bash theme={null}
potpie resolve "review the webhook signature PR for payments service" --intent review
potpie search "payments webhook middleware"
potpie timeline recent --time-window 14d --service payments
```
## Working with Multiple Workspaces (Pots)
If you work on multiple projects or want to isolate context boundaries, use separate pots.
```bash theme={null}
# List all pots
potpie pot list
# Create a pot for a specific project
potpie pot create platform-api --repo /path/to/platform-api --use
# Add sources to it
potpie source add repo /path/to/platform-api
potpie source add github my-org/platform-api
# Switch back to the default pot
potpie use default
```
The repo-local `.potpie.toml` file can bind a repository to a specific pot automatically:
```bash theme={null}
potpie pot default set platform-api --repo current
```
After setting a default, running Potpie commands from that repository directory will automatically scope to `platform-api`.
## Source Ingestion
### Local repository
Local repo sources are registered with `potpie source add repo`. Context is pulled on demand via `resolve` and `graph read`.
### GitHub integration
Connect GitHub to let the engine index PRs, issues, code reviews, and source history:
```bash theme={null}
potpie github login
potpie source add github my-org/my-repo
```
### Linear integration
Connect Linear to let agents query issues, projects, and documents:
```bash theme={null}
potpie linear login
potpie linear ls # list workspaces
potpie pot linear-team diff-sync ENG # incremental sync
```
### Jira integration
```bash theme={null}
potpie jira login --email me@corp.com --api-token ATATT... --site-subdomain myteam
potpie jira ls
```
### Confluence integration
```bash theme={null}
potpie confluence login --email me@corp.com --api-token ATATT... --site-subdomain myteam
potpie confluence ls
potpie confluence select --key DOCS
```
## Viewing the Graph UI
Potpie includes a local graph explorer you can open in your browser:
```bash theme={null}
potpie ui
```
The explorer connects to the local daemon and lets you browse entities, claims, and relationships for the active pot.
```bash theme={null}
potpie ui --pot my-api # open against a specific pot
potpie ui --no-open # start the server without opening a browser
```
## Day-to-Day Quick Reference
| What you want to do | Command |
| ----------------------------- | ----------------------------------------------- |
| Resolve context before a task | `potpie resolve ""` |
| Run a narrow entity lookup | `potpie search ""` |
| Record a decision or finding | `potpie record --type decision --summary "..."` |
| Check host readiness | `potpie status --host` |
| Add a repository source | `potpie source add repo .` |
| Switch active workspace | `potpie use ` |
| Open the graph explorer | `potpie ui` |
| View recent project events | `potpie timeline recent --time-window 7d` |
| Install or refresh skills | `potpie skills install --agent claude` |
| Connect GitHub | `potpie github login` |
| Run diagnostics | `potpie doctor` |
## Next Steps
Complete command reference with all options, arguments, and exit codes.
Deep reference for `resolve`, `search`, and `record`.
Graph workbench, daemon, ledger, backend, skills, and cloud.
# Installation
Source: https://docs.potpie.ai/cli/installation
Install the Potpie CLI, run first-time setup, and verify your environment.
This page covers everything you need to go from zero to a working local Context Engine: prerequisites, installation, first-time setup, supported harnesses, and how to verify the installation.
## Prerequisites
| Requirement | Details |
| --------------------- | ------------------------------------------------------------- |
| **Python** | 3.12 or newer |
| **Package manager** | `uv` (recommended) or `pip` |
| **Operating system** | macOS, Linux, or WSL2 on Windows |
| **AI coding harness** | Claude Code, OpenAI Codex, Cursor, or OpenCode (at least one) |
`uv tool install` is recommended for CLI installs. It isolates the Potpie tool environment from your project Python environments and prevents version conflicts.
## Step 1: Install the CLI
### Using uv (recommended)
```bash theme={null}
uv tool install potpie
```
### Using pip
```bash theme={null}
python3 -m pip install --user potpie
```
After installation, confirm the CLI is available:
```bash theme={null}
potpie --version
```
You should see output like:
```
potpie-context-engine 2.x.x Python 3.12.x /path/to/potpie
```
If `potpie` is not found after a `pip` install, ensure `~/.local/bin` (or the equivalent `pip --user` scripts directory) is on your `PATH`.
## Step 2: Run First-Time Setup
```bash theme={null}
potpie setup
```
On a TTY, this launches an interactive wizard. You can also pass flags directly to skip prompts:
```bash theme={null}
potpie setup --repo . --agent claude
```
**What setup does:**
| Step | What happens |
| ------------------- | ------------------------------------------------------------------ |
| Daemon install | Installs and starts the local background daemon service |
| Config | Creates `~/.potpie/config.json` and sets defaults |
| Graph backend | Provisions the local graph/vector store (default: `falkordb_lite`) |
| Pot creation | Creates a local `default` pot and marks it active |
| Local auth | Initialises local identity (no cloud account needed) |
| Source registration | Registers the `--repo` path as a source for the default pot |
| Skills | Installs Potpie guidance into the configured `--agent` harness |
`potpie setup` is idempotent. You can re-run it safely. Each step is `ensure`-shaped: it skips what is already done and only fixes what is missing.
### Setup options
| Option | Type | Default | Description |
| --------------------------- | --------- | --------------- | ------------------------------------------------------------------------------- |
| `--repo` | `PATH` | `.` | Repository path to register during setup. |
| `--pot` | `NAME` | `default` | Name for the initial pot. |
| `--agent` | `HARNESS` | `claude` | AI coding harness to configure. One of `claude`, `codex`, `cursor`, `opencode`. |
| `--backend` | `PROFILE` | `falkordb_lite` | Graph backend profile. |
| `--dry-run` | flag | off | Preview setup steps without executing them. |
| `--yes`, `-y` | flag | off | Assume yes for all prompts (non-interactive). |
| `--daemon` / `--in-process` | flag | `daemon` | Detached daemon mode (default) or in-process mode. |
### Preview before running
To see exactly what setup will do without executing anything:
```bash theme={null}
potpie setup --dry-run
```
This returns a `SetupPreview` document listing each planned step, its owner, and whether it is a hard or soft dependency.
## Step 3: Verify the Installation
### Check integration auth status
```bash theme={null}
potpie status
```
### Check host readiness (daemon, pot, graph backend, skills)
```bash theme={null}
potpie status --host
```
You should see a readiness report grouped by component: `host`, `pot`, `graph_service`, `backend`, `ledger`, and `skills`.
### Run full local diagnostics
```bash theme={null}
potpie doctor
```
`doctor` checks daemon health, CLI install paths, backend profile, and capability readiness. It also surfaces recommended follow-up commands.
## Supported Agent Harnesses
Setup installs **skills** into your AI coding harness. Skills are CLI-managed recipes that teach your agent how to use the Context Engine before editing code.
| Harness | `--agent` value | Skills path (global) |
| ------------ | --------------- | -------------------------------------------- |
| Claude Code | `claude` | `~/.claude/skills//SKILL.md` |
| OpenAI Codex | `codex` | `~/.agents/skills//SKILL.md` |
| Cursor | `cursor` | `~/.cursor/skills//SKILL.md` |
| OpenCode | `opencode` | `~/.config/opencode/skills//SKILL.md` |
To install or refresh skills after setup:
```bash theme={null}
potpie skills install --agent claude
potpie skills status --agent cursor
```
Use `--scope project --path .` to install project-scoped skills that travel with a repository:
```bash theme={null}
potpie skills install --agent claude --scope project --path .
```
## Graph Backend Profiles
Potpie uses a pluggable `GraphBackend`. The default profile for Python ≥3.12 is `falkordb_lite` — an embedded local graph with vector search that requires no external services.
| Profile | When to use |
| --------------- | ----------------------------------------------------------------------------- |
| `falkordb_lite` | Default. Embedded FalkorDB Lite with vector search. Requires Python ≥3.12. |
| `embedded` | JSON-persisted local fallback. No Docker or external dependencies. |
| `neo4j` | Optional. Requires a running Neo4j instance. |
| `postgres` | Optional. Requires a running Postgres instance with the `pgvector` extension. |
| `in_memory` | Tests and conformance only. State is not persisted. |
To switch profiles after setup:
```bash theme={null}
potpie config set backend.profile embedded
potpie backend doctor
```
## Optional: Connect Integrations
Source integrations let agents query GitHub PRs, Linear issues, Jira tickets, and Confluence runbooks alongside code. These are **opt-in** and not required for local graph use.
```bash theme={null}
potpie github login # GitHub device flow
potpie linear login # Linear OAuth (PKCE)
potpie jira login # Jira Atlassian API token
potpie confluence login # Confluence Atlassian API token
```
Verify integration status:
```bash theme={null}
potpie status
potpie status --verify # lightweight live API check
```
## Optional: Managed Backend Login
By default, Potpie runs entirely locally. If you have a Potpie account or a compatible self-hosted backend, you can log in to access managed pots:
```bash theme={null}
potpie login
```
To point the CLI at a self-hosted or custom managed backend:
```bash theme={null}
potpie config set cloud.backend_url https://potpie.example.com
potpie login
```
After login, managed pots appear in the same `potpie pot list` and `potpie use` flows as local pots.
## Environment Variables
| Variable | Description |
| -------------------------- | ---------------------------------------------------------------------- |
| `CONTEXT_ENGINE_HOST_MODE` | Override host mode: `daemon` (default) or `in_process`. |
| `POTPIE_HOME` | Override the default config and data directory (default: `~/.potpie`). |
| `NO_COLOR` | Disable ANSI colour output. |
## Local File Paths
| Path | Description |
| ------------------------ | --------------------------------------------------------------------------------------- |
| `~/.potpie/config.json` | Main configuration file. |
| `~/.potpie/credentials/` | Stored integration tokens (GitHub, Linear, Jira, Confluence). |
| `~/.potpie/data/` | Local graph storage and ledger data. |
| `~/.potpie/skills/` | Installed agent skill bundles. |
| `.potpie.toml` | Repository-local pot routing config (repo root). Overrides the active pot when present. |
## Troubleshooting
### `potpie` not found after install
* With `uv`: run `uv tool list` to confirm it was installed, then check `which -a potpie`.
* With `pip --user`: ensure `~/.local/bin` is in your `PATH`.
### Daemon not starting
```bash theme={null}
potpie doctor
potpie daemon status
potpie daemon restart
```
### Backend not ready
```bash theme={null}
potpie backend doctor
potpie backend status
```
### Skills missing or outdated
```bash theme={null}
potpie skills status --agent claude
potpie skills install --agent claude
```
## Next Steps
Learn common workflows: onboarding a repo, resolving context for a task, debugging, and recording learnings.
Full reference for `setup`, `status`, `doctor`, `whoami`, `ui`, and `config`.
# Integrations & Auth
Source: https://docs.potpie.ai/cli/integrations-and-auth
Potpie account auth and provider integrations for GitHub, Linear, Jira, and Confluence.
Potpie separates **Potpie account auth** from **provider integration auth**.
* `potpie login` / `potpie logout` manage Potpie account credentials
* `potpie github`, `potpie linear`, `potpie jira`, and `potpie confluence` manage provider-specific access
* `potpie auth` is still present, but it is a deprecated alias surface
## Potpie Account Auth
### `potpie login`
```bash theme={null}
potpie login [OPTIONS]
```
Sign in through browser-based Firebase session flow or store an API key explicitly.
| Option | Type | Description |
| ----------------- | ----- | ------------------------------------------------------- |
| `--api-key`, `-k` | `str` | Potpie API key. Uses key auth instead of browser login. |
| `--url`, `-u` | `str` | Potpie API base URL, only used with `--api-key`. |
Examples:
```bash theme={null}
potpie login
potpie login --api-key "$POTPIE_API_KEY"
potpie login --api-key "$POTPIE_API_KEY" --url http://127.0.0.1:8001
```
### `potpie logout`
```bash theme={null}
potpie logout
```
Removes locally stored Potpie account credentials.
## Integration Status
Use the shared status command to inspect integration state:
```bash theme={null}
potpie status
potpie status --verify
```
`--verify` performs lightweight API checks instead of only showing stored auth state.
## GitHub
```bash theme={null}
potpie github COMMAND
```
| Command | Purpose |
| ---------------------- | ------------------------------------------------ |
| `potpie github login` | Authenticate with GitHub using device flow. |
| `potpie github logout` | Remove stored GitHub credentials. |
| `potpie github repos` | List GitHub repositories accessible to this CLI. |
## Linear
```bash theme={null}
potpie linear COMMAND
```
| Command | Purpose |
| ---------------------- | --------------------------------------------------------------- |
| `potpie linear login` | Authenticate with Linear via OAuth (PKCE). |
| `potpie linear logout` | Remove stored Linear credentials. |
| `potpie linear ls` | List connected Linear workspaces. |
| `potpie linear select` | Select a workspace and team, then fetch issues in the terminal. |
### Notable Options
`potpie linear login`
| Option | Description |
| --------- | -------------------------------------------- |
| `--force` | Re-authenticate the active Linear workspace. |
| `--add` | Add an additional Linear workspace. |
`potpie linear select`
| Option | Description |
| --------------- | ------------------------------ |
| `--org`, `-o` | Workspace URL key or name. |
| `--key`, `-k` | Linear team key. |
| `--limit`, `-n` | Max issue count, default `10`. |
## Jira
```bash theme={null}
potpie jira COMMAND
```
| Command | Purpose |
| -------------------- | ------------------------------------------------------------ |
| `potpie jira login` | Authenticate with Jira. |
| `potpie jira logout` | Remove stored Jira credentials. |
| `potpie jira ls` | List connected Jira sites or projects, depending on profile. |
| `potpie jira select` | Select a Jira project and fetch issues in the terminal. |
`potpie jira select`
| Option | Description |
| --------------- | ------------------------------ |
| `--key`, `-k` | Jira project key. |
| `--limit`, `-n` | Max issue count, default `10`. |
## Confluence
```bash theme={null}
potpie confluence COMMAND
```
| Command | Purpose |
| -------------------------- | ----------------------------------------------- |
| `potpie confluence login` | Authenticate with Confluence. |
| `potpie confluence logout` | Remove stored Confluence credentials. |
| `potpie confluence ls` | List connected Confluence spaces or instances. |
| `potpie confluence select` | Select a space and fetch pages in the terminal. |
`potpie confluence select`
| Option | Description |
| --------------- | ----------------------------- |
| `--key`, `-k` | Confluence space key. |
| `--limit`, `-n` | Max page count, default `10`. |
## Deprecated Surface: `potpie auth`
`potpie auth` still exists for backward compatibility.
### Current guidance
* use `potpie github`, `potpie linear`, `potpie jira`, or `potpie confluence`
* use `potpie status` for auth state
* avoid building new docs or scripts on top of `potpie auth`
# Introduction
Source: https://docs.potpie.ai/cli/introduction
What the Potpie Context Engine is, what problems it solves, and how it works.
Potpie turns your codebase and software development lifecycle into a **living context graph** for AI agents. Instead of sending an entire repository to a language model or relying on loose file summaries, the Context Engine builds a structured, queryable, project-specific memory that agents can read before they act.
Install the CLI, run first-time setup, and verify your environment in minutes.
Day-to-day workflows: onboarding a repo, resolving context, debugging, and recording learnings.
Complete command reference with all options, arguments, and exit codes.
Graph workbench, daemon, ledger, backend, skills, and cloud operations.
## The Problem
Most AI coding agents operate at the wrong resolution. They either ingest far too much — flooding the model with repository noise that dilutes precision and inflates cost — or far too little, relying on shallow summaries that drift from the actual codebase.
The result is the same in both cases: agents that produce plausible-sounding but project-unaware output.
The Context Engine addresses this by maintaining a **bounded, project-specific memory** for each workspace. Rather than re-reading the entire repository on every task, it surfaces only the context that is relevant to the work at hand, anchored to real source evidence and scoped to the active workspace.
## How It Works
The Context Engine is **CLI-first**. A local daemon hosts the services. The same services can run behind a managed backend API. The active workspace boundary is called a **pot**, and every operation is scoped to one.
```mermaid theme={null}
flowchart TB
actor["user or agent"]
cli["potpie CLI"]
host["Host shell (local daemon or managed API)"]
pots["Pot Management"]
graph["Graph Service"]
skills["Skill Manager"]
backend["GraphBackend"]
stores[("local or hosted stores")]
actor --> cli --> host
host --> pots
host --> graph
host --> skills
pots --> graph
graph --> backend --> stores
```
**The path every command takes:**
```
CLI → HostShell → service(s) → domain ports → backend / ledger
```
The CLI never queries databases directly. It routes through `HostShell`, which composes the services. Services use typed domain ports. Backend adapters implement those ports. This keeps the same command language working across local and managed deployments.
### Deployment Modes
| Mode | How to start | Storage | Auth |
| ----------- | -------------- | ---------------------------------------- | ------------------------- |
| **Local** | `potpie setup` | Local daemon + embedded graph backend | No cloud account required |
| **Managed** | `potpie login` | Hosted backend API + hosted graph/search | Potpie account required |
Local and managed pots use the same CLI surface. After `potpie login`, managed pots appear in the same `potpie pot list` and `potpie use` flows. The active pot determines where every command routes.
## Core Concepts
| Term | What it means |
| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Pot** | The workspace boundary. Every source, query, claim, and graph mutation is scoped to one pot. After `potpie setup`, a `default` local pot is created and made active. |
| **Context graph** | The graph-backed memory inside the engine. Stores typed entities, relationships, source-backed claims, provenance, and timeline records. |
| **Entity** | A typed project object: service, feature, file, owner, issue, decision, runbook, incident, or environment. |
| **Claim** | A canonical fact about an entity or relationship, with source evidence, truth class, confidence, and time metadata. |
| **Source ref** | A pointer back to a file, PR, ticket, commit, or external system document. Every claim is evidence-backed. |
| **Semantic mutation** | The agent-facing write contract. Agents propose intent and evidence; the engine validates, lowers to graph operations, and writes with provenance. |
| **Skill** | A CLI-managed recipe that teaches an agent harness how to use the Context Engine. Skills are installed into harnesses like Claude Code or Cursor; they are not graph data. |
| **Event Ledger** | A separate managed or self-hostable service for source events from GitHub, Linear, and similar integrations. The local graph pulls events from the ledger; the ledger does not store graph state. |
## What You Can Do With It
### Context retrieval
Pull the bounded context an agent or developer needs before starting work:
```bash theme={null}
potpie resolve "what should I know before working on the billing webhooks?"
potpie resolve "trace the authentication flow" --intent debug --mode deep
potpie search "rate limiter middleware"
```
### Durable project memory
Save facts, decisions, and observations that persist across sessions:
```bash theme={null}
potpie record --type decision --summary "All new endpoints require shared rate-limiter middleware"
potpie record --type fix --summary "Stripe webhook retries fan into async retry worker" --scope service:billing
```
### Graph workbench
Explicit reads, entity lookups, mutation proposals, history, and quality checks:
```bash theme={null}
potpie graph catalog --task "debug refund failures"
potpie graph read --subgraph debugging --view prior_occurrences --scope service:refunds-api
potpie graph search-entities "AuthService" --type Service
potpie graph propose --file mutation.json
potpie graph commit mutation-plan:01JY8T5C
```
### Source integrations
Connect GitHub, Linear, Jira, or Confluence so agents can query issues, PRs, decisions, and runbooks alongside code:
```bash theme={null}
potpie github login
potpie source add github potpie-ai/potpie
```
## Supported Agent Harnesses
Potpie installs **skills** into your AI coding agent to teach it how to read context from the engine before acting. The following harnesses are supported:
| Harness | Install command |
| ------------ | ---------------------------------------- |
| Claude Code | `potpie skills install --agent claude` |
| OpenAI Codex | `potpie skills install --agent codex` |
| Cursor | `potpie skills install --agent cursor` |
| OpenCode | `potpie skills install --agent opencode` |
Skills are installed into the harness's global skills directory by default. Use `--scope project --path .` to commit a project-scoped skill that travels with the repository.
## How It Fits Into Your Workflow
A typical session with Potpie looks like this:
1. **Setup once:** `potpie setup --repo . --agent claude` provisions the local daemon, backend, default pot, and installs Claude Code skills.
2. **Open your harness:** Claude Code, Cursor, Codex, or OpenCode. The installed skill tells the agent to call Potpie before editing code.
3. **The agent reads context:** Your agent calls `potpie resolve ""` and uses the scoped context Potpie returns.
4. **Work normally:** The agent edits, tests, and commits. Context keeps it grounded.
5. **Record learnings:** Use `potpie record` to save decisions and findings durably. They appear in future `resolve` results.
You do not need to run a manual ingest command on the happy path. The harness and its installed skills coordinate context retrieval and ingestion for each task.
## Next Steps
Install the CLI and run `potpie setup`.
Practical workflows and examples.
Full command reference.
# CLI Manual
Source: https://docs.potpie.ai/cli/manual
Complete reference manual for the potpie command-line interface.
## NAME
**potpie** — context-graph CLI for AI agents and local developer workflows.
## SYNOPSIS
```
potpie [--json] [--verbose | -v] [--version] [--help] COMMAND [ARGS...]
```
## DESCRIPTION
`potpie` is the primary interface for the Potpie context engine. It provisions a local daemon, manages workspace boundaries (pots), registers source systems, retrieves bounded context for coding tasks, and administers the underlying project-memory graph.
The engine runs locally as a detached daemon or in-process. The same command surface routes to a managed backend when a managed pot is active.
## GLOBAL OPTIONS
| Option | Description |
| ----------------- | -------------------------------------------------------------- |
| `--json` | Emit all output as machine-readable JSON. |
| `--verbose`, `-v` | Show full tracebacks on errors. |
| `--version` | Print version, Python version, and executable path, then exit. |
| `--help` | Print help and exit. Available on every subcommand. |
## COMMANDS
### setup
```
potpie setup [OPTIONS]
```
Idempotent first-run provisioning: config, storage, daemon, default pot, and agent skills. Safe to re-run. Presents an interactive wizard on TTYs.
| Option | Type | Default | Description |
| --------------------------- | ------- | --------------- | --------------------------------------------------------------------- |
| `--repo` | PATH | `.` | Repository path to register during setup. |
| `--pot` | NAME | `default` | Initial pot name to create or use. |
| `--agent` | HARNESS | `claude` | Agent harness to configure (`claude`, `codex`, `cursor`, `opencode`). |
| `--backend` | PROFILE | `falkordb_lite` | Graph backend profile for this setup run. |
| `--scan` | flag | off | Enable source scanning during setup. |
| `--dry-run` | flag | off | Preview setup steps without executing them. Returns a `SetupPreview`. |
| `--yes`, `-y` | flag | off | Assume yes for all prompts (non-interactive). |
| `--daemon` / `--in-process` | flag | `daemon` | Provision a detached daemon or run in-process. |
### status
```
potpie status [OPTIONS]
```
Integration auth status by default. Use `--host` for daemon, pot, backend, and skills readiness.
| Option | Default | Description |
| ----------- | --------- | ------------------------------------------------------------ |
| `--verify` | off | Verify integration credentials with a lightweight API check. |
| `--host` | off | Show host-level readiness instead of integration auth. |
| `--intent` | `feature` | Intent for host-status shaping. Only with `--host`. |
| `--harness` | `claude` | Harness for host-status checks. Only with `--host`. |
| `--pot` | active | Pot scope. Only with `--host`. |
### doctor
```
potpie doctor
```
Run a full local diagnostic: daemon mode and health, CLI install paths, backend profile and capability readiness, active pot, and ledger binding.
### whoami
```
potpie whoami
```
Print the currently authenticated identity, mode (`local` or `managed`), and detail. Local installs report a `none` identity.
### resolve
```
potpie resolve TASK [OPTIONS]
```
Pull bounded context for a task description. Takes a natural-language task, queries the project-memory graph, and returns a scoped context envelope.
| Argument | Required | Description |
| -------- | -------- | ------------------------------------------------ |
| `TASK` | yes | Natural-language description of the coding task. |
| Option | Default | Description |
| ----------- | --------- | -------------------------------------------------------------------- |
| `--intent` | `feature` | Intent family: `feature`, `debug`, `review`, `ops`. |
| `--include` | none | Comma-separated include families (e.g. `architecture,dependencies`). |
| `--mode` | `fast` | Retrieval depth: `fast`, `balanced`, `verify`, `deep`. |
| `--pot` | active | Pot scope. |
### search
```
potpie search QUERY [OPTIONS]
```
Narrow follow-up lookup on a known phrase, symbol name, or entity.
| Argument | Required | Description |
| -------- | -------- | ------------------------------------------------------------- |
| `QUERY` | yes | A known phrase, symbol name, file path, or entity to look up. |
| Option | Default | Description |
| ----------- | ------- | --------------------------------- |
| `--include` | none | Comma-separated include families. |
| `--pot` | active | Pot scope. |
### record
```
potpie record [OPTIONS]
```
Write a durable project learning to the graph.
| Option | Required | Description |
| ----------- | -------- | -------------------------------------------------------------------------------------- |
| `--type` | yes | Record type: `decision`, `fix`, `preference`, `constraint`. |
| `--summary` | yes | Short summary of the learning. |
| `--scope` | no | Structured scope as `key:value` pairs, comma-separated (e.g. `service:inventory-svc`). |
| `--pot` | no | Pot scope. Defaults to active pot. |
### use
```
potpie use REF [OPTIONS]
```
Set the active pot by name or id. Top-level alias for `potpie pot use`.
| Option | Description |
| ----------- | -------------------------------------- |
| `--local` | Force selection of a local-origin pot. |
| `--managed` | Select a managed-origin pot. |
### login
```
potpie login [OPTIONS]
```
Sign in to Potpie. Opens a browser-based session by default, or stores an API key with `--api-key`.
| Option | Description |
| ----------------- | ------------------------------------------- |
| `--api-key`, `-k` | Potpie API key. Skips browser login. |
| `--url`, `-u` | Potpie API base URL. Only with `--api-key`. |
### logout
```
potpie logout
```
Remove Potpie account credentials from local storage.
### ui
```
potpie ui [OPTIONS]
```
Launch the local graph-explorer UI served by the daemon.
| Option | Default | Description |
| ---------------------- | -------- | ----------------------------------------- |
| `--open` / `--no-open` | `--open` | Open the explorer in the default browser. |
| `--pot` | none | Open the explorer against a specific pot. |
## COMMAND GROUPS
### pot
```
potpie pot SUBCOMMAND [OPTIONS]
```
Manage workspace boundaries. A pot is a named scope that groups sources, graph data, and agent context.
| Subcommand | Description |
| -------------------------------- | ----------------------------------------- |
| `list` | List all pots. |
| `info` | Show the active pot. |
| `create NAME` | Create a new pot. |
| `use REF` | Set the active pot. |
| `linked` | Show pots linked to the current repo. |
| `rename REF NEW-NAME` | Rename a pot. |
| `reset [REF] --confirm` | Reset graph state for a pot. |
| `archive REF` | Archive a pot. |
| `default show` | Show repo-local default pot. |
| `default set REF` | Bind the current repo to a default pot. |
| `default clear` | Remove repo-local default binding. |
| `linear-team diff-sync TEAM` | Incremental Linear team graph diff-sync. |
| `jira-project diff-sync PROJECT` | Incremental Jira project graph diff-sync. |
### source
```
potpie source SUBCOMMAND [OPTIONS]
```
Register and inspect source systems within a pot. `source add` records metadata only — it does not ingest or scan.
| Subcommand | Description |
| ------------------- | ---------------------------------------------------- |
| `add KIND LOCATION` | Register a source (`repo`, `github`, or `document`). |
| `list` | List sources for the active pot. |
| `status SOURCE_ID` | Inspect one source record. |
| `remove SOURCE_ID` | Remove a source record. |
### github
```
potpie github SUBCOMMAND [OPTIONS]
```
| Subcommand | Description |
| ----------------- | --------------------------------------- |
| `login [--force]` | Authenticate with GitHub (device flow). |
| `logout` | Remove stored GitHub credentials. |
| `repos` | List accessible GitHub repositories. |
### linear
```
potpie linear SUBCOMMAND [OPTIONS]
```
| Subcommand | Description |
| -------------------------------------------- | -------------------------------------------------------------------------------- |
| `login [--force] [--add]` | Authenticate with Linear (PKCE OAuth). `--add` connects an additional workspace. |
| `logout [--all]` | Remove stored Linear credentials. `--all` removes all workspaces. |
| `ls [--limit N]` | List connected Linear workspaces. |
| `select [--org ORG] [--key KEY] [--limit N]` | Select a team and fetch issues. |
### jira
```
potpie jira SUBCOMMAND [OPTIONS]
```
| Subcommand | Description |
| ---------------------------------------------------------------------------- | ---------------------------------------------------- |
| `login [--force] [--email EMAIL] [--api-token TOKEN] [--site-subdomain SUB]` | Authenticate with Jira using an Atlassian API token. |
| `logout` | Remove stored Jira credentials. |
| `ls [--limit N]` | List connected Jira projects. |
| `select [--key KEY] [--limit N]` | Select a project and fetch issues. |
### confluence
```
potpie confluence SUBCOMMAND [OPTIONS]
```
| Subcommand | Description |
| ---------------------------------------------------------------------------- | ---------------------------------------------------------- |
| `login [--force] [--email EMAIL] [--api-token TOKEN] [--site-subdomain SUB]` | Authenticate with Confluence using an Atlassian API token. |
| `logout` | Remove stored Confluence credentials. |
| `ls [--limit N]` | List connected Confluence spaces. |
| `select [--key KEY] [--limit N]` | Select a space and fetch pages. |
### daemon
```
potpie daemon SUBCOMMAND
```
Local daemon lifecycle. These are recovery and inspection tools; normal use does not require them.
| Subcommand | Description |
| ----------------- | ------------------------------------------------- |
| `start` | Start the detached daemon. |
| `status` | Print daemon PID, uptime, mode, and health. |
| `logs [--follow]` | Print daemon logs. `--follow` tails in real time. |
| `restart` | Restart the daemon. |
| `stop` | Stop the daemon. |
### service
```
potpie service SUBCOMMAND
```
Control supporting services managed by the daemon. Only meaningful when a detached daemon is running.
| Subcommand | Description |
| ---------------- | -------------------------------------------------------- |
| `up NAME` | Start a named supporting service. |
| `down NAME` | Stop a named supporting service. |
| `status` | List all managed services and their status. |
| `logs NAME [-f]` | Print logs for a named service. `-f` tails in real time. |
### ledger
```
potpie ledger SUBCOMMAND [OPTIONS]
```
Inspect and manage the Event Ledger binding and consumer cursor.
| Subcommand | Description |
| ---------------------- | --------------------------------------------------------------------- |
| `status` | Show ledger binding and availability. |
| `use BINDING [URL]` | Bind a ledger: `managed` or `self-hosted `. |
| `disconnect` | Clear the Event Ledger binding. |
| `query [OPTIONS]` | Inspect ledger event history. Read-only; does not advance the cursor. |
| `pull --source SOURCE` | Pull events and advance the consumer cursor. |
| `sources list [--pot]` | List ledger source connectors for a pot. |
`ledger query` options:
| Option | Description |
| ---------- | ------------------------------- |
| `--source` | Filter by source ID. |
| `--type` | Normalized event kind filter. |
| `--since` | ISO 8601 instant lower bound. |
| `--until` | ISO 8601 instant upper bound. |
| `--limit` | Maximum events. Default: `100`. |
| `--pot` | Pot scope. |
### graph
```
potpie graph SUBCOMMAND [OPTIONS]
```
Graph workbench: reads, writes, quality checks, inbox, and administration.
| Subcommand | Description |
| ----------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------- |
| `status [--pot]` | Graph data-plane readiness and health. |
| `catalog [--subgraph] [--profile] [--format] [--pot]` | Discover graph contract: versions, views, mutation ops, ontology. |
| `describe SUBGRAPH [--view VIEW] [--examples] [--pot]` | Describe a subgraph or named view. |
| `read --subgraph SUB --view VIEW [OPTIONS]` | Read over a named view. |
| `search-entities QUERY [OPTIONS]` | Resolve entity or claim identity. |
| `neighborhood --entity KEY [OPTIONS]` | Read a local neighborhood around an entity. `--entity` is required. |
| `propose [--file FILE] [--ttl TTL] [--pot]` | Stage a validated graph mutation plan. `--ttl` sets plan expiry (e.g. `1h`, `2d`). |
| `commit PLAN_ID [--verify] [--approved-by USER] [--pot]` | Commit a staged plan. `--verify` runs post-commit quality checks. |
| `mutate [--file FILE] [--dry-run] [--allow-review-required] [--approved-by USER] [--pot]` | Validate and apply a semantic mutation in one step. |
| `mutation-template --kind KIND` | Print a schema-only mutation skeleton. |
| `nudge --event EVENT --session ID [OPTIONS]` | Deterministic event-to-action policy: inject context, prompt a write, or stay silent. |
| `history [OPTIONS]` | Inspect graph mutation history. |
| `inspect [OPTIONS]` | Inspect graph internals or raw payloads. |
| `inbox add` | Add a pending work item. |
| `inbox list` | List pending inbox items. |
| `inbox show` | Inspect one inbox item. |
| `inbox claim` | Claim an inbox item for processing. |
| `inbox mark-applied` | Mark an inbox item as applied. |
| `inbox mark-rejected` | Mark an inbox item as rejected. |
| `inbox close` | Close an inbox item. |
| `quality summary [--pot]` | Read-only quality summary report. |
| `quality duplicate-candidates` | Find likely duplicate entities. |
| `quality stale-facts` | Detect stale claims. |
| `quality conflicting-claims` | Surface conflicting claims. |
| `quality orphan-entities` | Find orphaned entities. |
| `quality low-confidence` | Show low-confidence graph material. |
| `quality projection-drift` | Detect projection drift. |
| `bulk apply [--file]` | Apply many semantic mutations in chunked propose/commit steps. |
| `export` | Export graph data. |
| `import` | Import graph data. |
| `repair [OPTIONS]` | Run graph repair flows. |
`graph read` options:
| Option | Default | Description |
| --------------------- | --------- | --------------------------------------------------------------------- |
| `--subgraph` | — | Canonical subgraph (e.g. `debugging`). **Required.** |
| `--view` | — | Named view within `--subgraph`. **Required.** |
| `--query` | none | Text filter for the view. |
| `--scope` | none | `key:value[,key:value]` scope hints. |
| `--current` | off | Resolve pot from the current repo directory. Does not add repo scope. |
| `--repo` | none | Repo scope: `owner/repo`, URL, or `current`. |
| `--since` / `--until` | none | ISO 8601 instant time bounds. |
| `--time-window` | none | Relative lookback: `24h`, `7d`, `2w`. Ignored when `--since` is set. |
| `--environment` | none | Environment filter. |
| `--source-ref` | none | Exact claim source ref (repeatable). |
| `--depth` | none | Traversal depth for neighborhood views. |
| `--direction` | none | `out`, `in`, or `both`. |
| `--limit` | `12` | Maximum items. |
| `--sort` | `auto` | `auto`, `score`, `occurred_at`. |
| `--dedupe` | `auto` | `auto`, `none`, `source_ref`, `activity`. |
| `--format` | `auto` | `auto`, `raw`, `events`, `table`, `jsonl`. |
| `--detail` | `compact` | `compact` or `full`. |
| `--relations` | `summary` | `summary` or `full`. |
| `--pot` | active | Pot scope. |
`graph search-entities` options:
| Option | Description |
| ----------------------- | ----------------------------------------------------- |
| `--type` | Entity label filter (e.g. `Service`). |
| `--predicate` | Predicate filter. |
| `--subgraph` | Subgraph filter. |
| `--scope` | Scope hints in `key:value` form. |
| `--truth` | Truth-value filter. |
| `--source-system` | Source system filter. |
| `--source-family` | Source family filter. |
| `--external-id` | External ID filter. |
| `--source-ref` | Exact claim source ref (repeatable). |
| `--since` / `--until` | ISO 8601 instant time bounds. |
| `--environment` | Environment filter. |
| `--supporting-claims N` | Number of supporting claims to include. Default: `0`. |
| `--limit` | Maximum entities. Default: `10`. |
`graph mutation-template` supported `--kind` values:
`bug-fix` · `decision` · `feature` · `infra-snapshot` · `preference` · `preference-policy` · `repo-baseline` · `timeline-change` · `timeline-event`
### timeline
```
potpie timeline SUBCOMMAND [OPTIONS]
```
| Subcommand | Description |
| ------------------ | ------------------------------------------------------------------ |
| `recent [OPTIONS]` | Recent project events from the active pot across all repo sources. |
`timeline recent` options:
| Option | Default | Description |
| --------------------- | --------- | --------------------------------------------- |
| `--query` | none | Text query filter. |
| `--since` / `--until` | none | ISO 8601 instant bounds. |
| `--time-window` | none | Relative lookback (e.g. `7d`). |
| `--service` | none | Service scope. Omit for project-wide results. |
| `--limit` | `12` | Maximum events. |
| `--format` | `auto` | `auto`, `events`, `table`, `raw`, `jsonl`. |
| `--detail` | `compact` | `compact` or `full`. |
| `--relations` | `summary` | `summary` or `full`. |
| `--pot` | active | Pot scope. |
### backend
```
potpie backend SUBCOMMAND
```
Graph backend profile selection and health checks.
| Subcommand | Description |
| ------------- | --------------------------------------------- |
| `list` | List available backend profiles. |
| `status` | Show current backend status and capabilities. |
| `use PROFILE` | Switch the active backend profile. |
| `doctor` | Run detailed backend readiness diagnostics. |
### skills
```
potpie skills SUBCOMMAND [OPTIONS]
```
Manage CLI-installed agent skills. Skills are installed into agent harnesses; they are not graph data and not additional agent tools.
| Subcommand | Description |
| --------------------------- | -------------------------------------------------- |
| `list` | List installed and available skills. |
| `install [SKILL_ID]` | Install skill(s) for a harness. |
| `update [--all]` | Update installed skills. |
| `remove [SKILL_ID] [--all]` | Remove installed skills. |
| `status` | Show installed, missing, and outdated skill state. |
| `add SOURCE` | Add a skill source by path or URL. |
Common options:
| Option | Default | Description |
| --------- | -------- | ------------------------------------------------------------------- |
| `--agent` | `claude` | Target agent harness. |
| `--scope` | `global` | `global` or `project`. Auto-selects `project` when `--path` is set. |
| `--path` | none | Repo path for project-scoped skill installation. |
### cloud
```
potpie cloud SUBCOMMAND
```
Managed profile and sync commands. All subcommands currently return a structured not-implemented response.
| Subcommand | Description |
| ----------------------- | ------------------------------------------ |
| `login` | Managed profile login. |
| `status` | Cloud sync status. |
| `push [--pot]` | Push local pot state to cloud. |
| `pull [--pot]` | Pull cloud state to local. |
| `skills sync [--agent]` | Sync managed skill catalog into a harness. |
### config
```
potpie config SUBCOMMAND
```
Read or write local configuration entries. Persisted to `~/.potpie/config.json`.
| Subcommand | Description |
| --------------- | ------------------------------------------------------ |
| `list` | List all non-secret config entries. |
| `get [KEY]` | Print a single value, or all values if KEY is omitted. |
| `set KEY VALUE` | Set a configuration value. |
### telemetry
```
potpie telemetry SUBCOMMAND
```
Control product analytics and error reporting preferences.
| Subcommand | Description |
| ---------- | --------------------------------------------------------- |
| `status` | Show current telemetry status (crash reports, analytics). |
| `enable` | Enable anonymous CLI telemetry. |
| `disable` | Disable all outbound CLI telemetry. |
## EXIT STATUS
| Code | Meaning |
| ---- | ------------------------------------------------------------------- |
| `0` | Success. |
| `1` | General error or validation failure. Use `--verbose` for traceback. |
| `2` | Service unavailable — daemon or backend not reachable. |
| `3` | Degraded — completed with one or more non-fatal failures. |
| `4` | Authentication error. |
## ENVIRONMENT
| Variable | Description |
| -------------------------- | ------------------------------------------------------- |
| `CONTEXT_ENGINE_HOST_MODE` | Override host mode: `daemon` (default) or `in_process`. |
| `POTPIE_HOME` | Override the default config and data directory. |
| `NO_COLOR` | Disable ANSI colour output. |
## FILES
| Path | Description |
| ------------------------ | ------------------------------------------------------------- |
| `~/.potpie/config.json` | Main configuration file. |
| `~/.potpie/credentials/` | Stored integration tokens (GitHub, Linear, Jira, Confluence). |
| `~/.potpie/data/` | Local graph storage and ledger data. |
| `~/.potpie/skills/` | Installed agent skill bundles. |
| `.potpie.toml` | Repository-local pot routing config (repo root). |
## EXAMPLES
```bash theme={null}
# Install and run first-time setup
uv tool install potpie
potpie setup --repo . --agent claude
# Preview setup without executing
potpie setup --dry-run
# Check integration auth; verify credentials live
potpie status
potpie status --verify
# Check host readiness (daemon, pot, graph, skills)
potpie status --host
# Run full local diagnostics
potpie doctor
# Connect GitHub and register a repository
potpie github login
potpie source add repo .
# Connect Linear and list workspaces
potpie linear login
potpie linear ls
# Connect Jira (non-interactive)
potpie jira login --email me@corp.com --api-token ATATT... --site-subdomain myteam
# Retrieve context for a task
potpie resolve "add rate limiting to the /api/payments endpoint"
# Retrieve context with deep mode and JSON output
potpie resolve "trace all callers of AuthService.verify" --mode deep --json | jq '.items'
# Narrow search for a known entity
potpie search "RateLimiter"
# Record a project decision
potpie record --type decision --summary "All new endpoints must use the shared rate-limiter middleware"
# Switch pots and read the graph
potpie use my-other-pot
potpie graph catalog
potpie graph read --subgraph architecture --view service_map
# Resolve entity identity before a write
potpie graph search-entities "AuthService" --type Service --supporting-claims 3
# Read recent timeline events
potpie timeline recent --time-window 7d --format events
# Install skills for a harness
potpie skills install --agent claude
potpie skills status --agent cursor --scope project --path .
# Launch the local graph UI
potpie ui
# Ledger: bind and query
potpie ledger status
potpie ledger query --source github --type push --since 2026-06-01T00:00:00Z --limit 20
```
## SEE ALSO
* [CLI Reference](/cli/reference) — Command families and install flow.
* [Setup & Lifecycle](/cli/setup-and-lifecycle) — Setup, status, doctor, and config in depth.
* [Context Commands](/cli/context-commands) — `resolve`, `search`, and `record` in depth.
* [Integrations & Auth](/cli/integrations-and-auth) — Provider login flows.
* [Pots & Sources](/cli/pots-and-sources) — Workspace routing and source registration.
* [Graph & Operations](/cli/graph-and-operations) — Graph workbench and operational commands.
* [GitHub Repository](https://github.com/potpie-ai/potpie) — Source code and architecture notes.
# Pots & Sources
Source: https://docs.potpie.ai/cli/pots-and-sources
Workspace routing, repo-local defaults, source registration, and ingestion entry points.
Potpie uses **pots** as workspace or tenant boundaries. Sources are then registered against a pot.
This is the part of the CLI that controls where context lives and which repository or external system belongs to that context boundary.
## Top-Level Alias: `potpie use`
```bash theme={null}
potpie use [OPTIONS] REF
```
Top-level alias for `potpie pot use`.
| Option | Type | Description |
| ----------- | ------ | --------------------------------- |
| `--local` | `bool` | Force local-origin pot selection. |
| `--managed` | `bool` | Select a managed-origin pot. |
## `potpie pot`
```bash theme={null}
potpie pot COMMAND [ARGS]...
```
### Core Pot Commands
| Command | Purpose |
| ------------------------------------ | ------------------------------------------------------ |
| `potpie pot list` | List available pots. |
| `potpie pot info` | Show the active pot. |
| `potpie pot create ` | Create a new pot. |
| `potpie pot use [` | Make a pot active. |
| `potpie pot linked --repo current` | Show pots linked to a repo and any repo-local default. |
| `potpie pot rename ][ ` | Rename a pot. |
| `potpie pot reset [ref] --confirm` | Reset graph state for a pot. |
| `potpie pot archive ][` | Archive a pot. |
### Important Options
`potpie pot list`
| Option | Description |
| ----------- | ------------------------------------- |
| `--local` | Local-origin pots only. |
| `--managed` | Managed-origin pots only. |
| `--all` | Show local and managed pots together. |
`potpie pot create`
| Option | Description |
| -------- | ---------------------------------------- |
| `--repo` | Associate a repository at creation time. |
| `--use` | Make the new pot active immediately. |
## Repo-Local Defaults
```bash theme={null}
potpie pot default COMMAND
```
Repo-local defaults let a repository resolve to the right pot automatically.
| Command | Purpose |
| --------------------------------------------- | -------------------------------------- |
| `potpie pot default show --repo current` | Show the repo-local default pot. |
| `potpie pot default set ][ --repo current` | Bind a repo to a default pot. |
| `potpie pot default clear --repo current` | Remove the repo-local default binding. |
## Source Registration
```bash theme={null}
potpie source COMMAND
```
### Important model
`potpie source add` **registers metadata only**. It does not ingest, parse, or scan by itself.
The diagram below shows how context enters the graph:
```mermaid theme={null}
flowchart LR
sourceAdd["potpie source add repo ."]
resolveCmd["potpie resolve / graph read"]
metadata["source metadata stored\n(no graph write)"]
onDemand["on-demand context pull\nby agent or developer"]
sourceAdd --> metadata
resolveCmd --> onDemand
```
`source add` registers a repository once; context is pulled when agents or developers actually need it.
### Source commands
| Command | Purpose |
| ------------------------------------- | -------------------------- |
| `potpie source add ` | Register a source record. |
| `potpie source list` | List sources for a pot. |
| `potpie source status ` | Inspect one source record. |
| `potpie source remove ` | Remove a source record. |
### `potpie source add`
```bash theme={null}
potpie source add [OPTIONS] KIND LOCATION
```
| Parameter | Type | Description |
| ---------- | ----- | ----------------------------------------------------------------- |
| `kind` | `str` | Source type, such as `repo`, `github`, or `document`. |
| `location` | `str` | Path, `owner/repo`, URL, or integration-specific source location. |
| Option | Type | Description |
| ---------------------------- | ------ | --------------------------------------------------------- |
| `--name` | `str` | Optional display name for the source. |
| `--pot` | `str` | Pot to register against. |
| `--default` / `--no-default` | `bool` | For repo sources, set or skip repo-local default routing. |
Examples:
```bash theme={null}
potpie source add repo .
potpie source add github potpie-ai/potpie
potpie source add document https://internal.wiki/runbook/auth-migration
```
## Ingestion Entry Points
This is where your expectation mattered: ingestion is not a separate generic `ingest` top-level command.
Instead, ingestion shows up in **pot-attached external-system workflows**:
### Linear team sync
```bash theme={null}
potpie pot linear-team diff-sync TEAM
```
| Command | Purpose |
| ----------- | ------------------------------------------------------------- |
| `diff-sync` | Queue an incremental graph-audit diff sync for a Linear team. |
### Jira project sync
```bash theme={null}
potpie pot jira-project diff-sync PROJECT
```
| Command | Purpose |
| ----------- | ---------------------------------------------------- |
| `diff-sync` | Queue incremental Jira project diff-sync into a pot. |
## Recommended Workspace Flow
```bash theme={null}
potpie pot list
potpie pot create my-repo --repo . --use
potpie source add repo . --default
potpie pot linked --repo current
```
# CLI Reference
Source: https://docs.potpie.ai/cli/reference
The Potpie CLI command map: setup, context retrieval, integrations, pots, sources, and graph operations.
Potpie is a **CLI-first** product. The command surface is not a thin wrapper around HTTP endpoints — it is the primary interface for local setup, source registration, context retrieval, graph reads, and operational control. Both humans and AI agent harnesses (Claude Code, Cursor, OpenAI Codex, OpenCode) use the same CLI.
New to Potpie? Start with [Introduction](/cli/introduction) and [Installation](/cli/installation) before diving into the reference.
## Command Families
Complete man-page style reference. All commands, options, exit codes, environment variables, and file paths in one place.
Install Potpie, run first-time setup, verify readiness, inspect local state, and launch the UI.
Pull context for a task, run narrow follow-up searches, and record durable project learnings.
Sign into Potpie, connect GitHub, Linear, Jira, and Confluence, and inspect integration status.
Manage workspace boundaries, repo-local defaults, source registration, and ingestion entry points.
Daemon lifecycle, services, event ledger, graph workbench, timeline reads, backend profiles, and skills.
## Root Command
```bash theme={null}
potpie [OPTIONS] COMMAND [ARGS]...
```
### Global Options
| Option | Description |
| ----------------- | ---------------------------------------------------------------------------------------- |
| `--json` | Emit machine-readable JSON. Useful for piping to `jq` or consuming from agent harnesses. |
| `--verbose`, `-v` | Show verbose tracebacks on errors. |
| `--version` | Print `potpie-context-engine` version, Python version, and executable path. |
| `--help` | Show root help. Available on every subcommand. |
## Command Index
| Family | Commands |
| ------------------- | -------------------------------------------------------------------------------- |
| Context | `resolve`, `search`, `record` |
| Setup & readiness | `setup`, `status`, `doctor`, `whoami`, `ui`, `config` |
| Auth & integrations | `login`, `logout`, `github`, `linear`, `jira`, `confluence`, `auth` |
| Workspace routing | `use`, `pot`, `source` |
| Runtime operations | `daemon`, `service`, `ledger`, `graph`, `timeline`, `backend`, `skills`, `cloud` |
## Recommended First-Run Sequence
```bash theme={null}
# Install
uv tool install potpie
# Set up local environment (interactive wizard on TTY)
potpie setup --repo . --agent claude
# Verify readiness
potpie status --host
# Connect GitHub
potpie github login
# Register the repository as a source
potpie source add repo .
# Resolve context to confirm everything is working
potpie resolve "what should I know before working in this repository?"
# Open the graph explorer
potpie ui
```
## Important Model
* **`source add` registers metadata only.** It does not ingest or scan the repository by itself. Context is pulled on demand by `resolve`, `search`, agents, or graph reads.
* **External-system sync** runs through pot-attached connector commands such as `pot linear-team diff-sync` and `pot jira-project diff-sync`.
* **The graph workbench** lives under `potpie graph`. It is a CLI command group, not an HTTP API.
* **All commands default to the active pot.** Use `--pot ` to scope a single command without changing the active pot.
* **Local and managed pots** use the same CLI surface. After `potpie login`, managed pots appear in `potpie pot list` and `potpie use`.
## Output Contract
| Format | How to get it |
| --------------- | ------------------------------------------------------- |
| Human (default) | Action-oriented summary with a recommended next command |
| JSON | Pass `--json` to any command |
Exit codes:
| Code | Meaning |
| ---- | ------------------------------------------------------------ |
| `0` | Success |
| `1` | General error |
| `2` | Usage or argument validation error |
| `3` | Degraded — setup completed but one or more hard steps failed |
| `4` | Authentication error |
| `5` | Service unavailable |
# Setup & Lifecycle
Source: https://docs.potpie.ai/cli/setup-and-lifecycle
Setup, readiness, diagnostics, local identity, UI launch, and local config commands.
This page covers the commands you use to install, bootstrap, inspect, and operate a local Potpie environment.
## `potpie setup`
```bash theme={null}
potpie setup [OPTIONS]
```
Idempotent first-run provisioning for config, storage, daemon, default pot, and skills.
### Options
| Option | Type | Description |
| --------------------------- | ------ | --------------------------------------------------------- |
| `--repo` | `str` | Repository path to bind during setup. Defaults to `.`. |
| `--pot` | `str` | Default pot name to create or use. Defaults to `default`. |
| `--agent` | `str` | Harness/agent profile to configure. Defaults to `claude`. |
| `--backend` | `str` | Graph backend profile for this setup run. |
| `--scan` | `bool` | Enable scanning during setup when supported. |
| `--dry-run` | `bool` | Preview setup steps without executing them. |
| `--yes`, `-y` | `bool` | Assume yes for prompts. |
| `--daemon` / `--in-process` | `bool` | Choose detached daemon mode or in-process mode. |
### Examples
```bash theme={null}
potpie setup
potpie setup --repo . --agent claude
potpie setup --repo . --agent codex --backend falkordb
potpie setup --dry-run
```
## `potpie status`
```bash theme={null}
potpie status [OPTIONS]
```
By default this shows **integration auth status**. Use `--host` for daemon, pot, backend, and skills readiness.
### Options
| Option | Type | Description |
| ----------- | ------ | ----------------------------------------------------------- |
| `--verify` | `bool` | Verify integration credentials with lightweight API checks. |
| `--host` | `bool` | Switch from auth status to host/pot readiness. |
| `--intent` | `str` | Host-status intent, default `feature`. |
| `--harness` | `str` | Harness used for host-status checks, default `claude`. |
| `--pot` | `str` | Pot to evaluate for host status. |
### Examples
```bash theme={null}
potpie status
potpie status --verify
potpie status --host
potpie status --host --pot default --intent feature --harness claude
```
## `potpie doctor`
```bash theme={null}
potpie doctor
```
Runs local diagnostics across:
* daemon mode and uptime
* backend readiness and implemented capabilities
* active pot visibility
* ledger availability
* skill drift or readiness nudges
## `potpie whoami`
```bash theme={null}
potpie whoami
```
Shows the current host identity. In local OSS mode this typically reports a `none`-style identity rather than a managed account subject.
## `potpie ui`
```bash theme={null}
potpie ui [OPTIONS]
```
Launches the local graph explorer served by the daemon.
### Options
| Option | Type | Description |
| ---------------------- | ------ | ----------------------------------------- |
| `--open` / `--no-open` | `bool` | Open the explorer in a browser. |
| `--pot` | `str` | Open the explorer against a specific pot. |
### Examples
```bash theme={null}
potpie ui
potpie ui --pot default
potpie ui --no-open
```
## `potpie config`
```bash theme={null}
potpie config COMMAND [ARGS]...
```
Local config is persisted to `/config.json`.
### Subcommands
| Command | Purpose |
| --------------------------------- | --------------------------- |
| `potpie config get ` | Read a stored config value. |
| `potpie config set ` | Persist a config value. |
### Examples
```bash theme={null}
potpie config get backend.profile
potpie config set backend.profile falkordb
```
## Recommended Lifecycle Sequence
1. Install the CLI with `uv tool install potpie` or `pip`.
2. Run `potpie setup`.
3. Verify readiness with `potpie status --host`.
4. Connect integrations with provider-specific login commands.
5. Register the current repository with `potpie source add repo .`.
6. Use `potpie ui` or `potpie resolve` to start working with the graph.
# Context Engine
Source: https://docs.potpie.ai/concepts/context-engine
How Potpie turns repositories, source history, and durable project memory into a bounded context system for agents.
Potpie's **Context Engine** is the project-context system behind its agents. It gives Potpie a bounded, project-specific understanding of your codebase so agents can answer questions, debug issues, plan changes, and record durable learnings without starting from scratch on every task.
In the implementation used by Potpie today, the Context Engine includes:
* a **pot-scoped** context model for workspace isolation;
* a **graph-backed memory layer** for entities, claims, source refs, and timelines;
* a **CLI-first agent surface** exposed through `resolve`, `search`, `record`, and `status`;
* a lower-level **graph workbench** for explicit reads, proposals, commits, and quality workflows;
* backend adapters that let the same engine run locally or behind a managed service.
## What The Context Engine Does
The Context Engine is not a generic knowledge graph. In this repository, Potpie consistently describes it as a system for **grounding agents in real project context**.
That means it is responsible for:
* scoping context to a **pot**, so reads and writes stay inside the right workspace;
* reading from code, repository structure, source history, and other linked systems;
* retrieving the smallest useful slice of context for a task instead of over-reading the repo;
* storing durable project memory such as decisions, observations, and validated graph facts;
* exposing both high-level agent tools and lower-level graph operations over the same underlying model.
## Core Concepts
| Concept | What it means in Potpie |
| --------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| **Pot** | The workspace boundary for context. Sources, reads, claims, mutations, and status are all scoped to one pot. |
| **Context graph** | The graph-backed memory inside the Context Engine. It stores entities, relationships, claims, evidence, and timeline-style records. |
| **Entity** | A typed project object such as a service, feature, owner, issue, decision, runbook, or incident. |
| **Claim** | A canonical fact about an entity or relationship, with provenance and time metadata. |
| **Source ref** | Evidence that points back to a file, PR, ticket, document, or external system. |
| **Semantic mutation** | The agent-facing write contract for durable graph updates. Agents propose intent, not raw graph CRUD. |
| **Workbench** | The lower-level graph command surface for discovery, reads, proposals, commits, history, inbox, and quality checks. |
## Runtime Shape
Potpie's current architecture is **CLI-first**. Users and agents interact with the CLI, MCP server, or HTTP surface, and those surfaces route into the same host shell and service modules.
```mermaid theme={null}
flowchart TB
actor["user or agent"]
surface["CLI / MCP / HTTP"]
host["Host shell"]
pots["Pot management"]
graph["Graph service"]
skills["Skill manager"]
backend["Graph backend"]
stores[("local or hosted stores")]
actor --> surface --> host
host --> pots
host --> graph
host --> skills
pots --> graph
graph --> backend --> stores
```
In local usage, Potpie provisions local config, local storage, and an active default pot. In managed usage, the same graph-oriented services can run behind a backend API on hosted storage. The graph model stays the same; only the host and storage adapters change.
## Agent Surfaces
Most users do not work with the graph workbench directly. The normal entry point is the four-tool context surface:
| Surface | Purpose |
| --------- | --------------------------------------------------------- |
| `status` | Check readiness, active pot, and recommended next actions |
| `resolve` | Retrieve bounded context for a task |
| `search` | Run a narrower follow-up lookup |
| `record` | Save durable project memory |
These are the tools that let an agent ask, "what should I know before I work on this?" The graph workbench sits underneath them when Potpie needs explicit graph reads, semantic writes, history, or validation.
## Why This Matters
The Context Engine exists to reduce two common failure modes in code agents:
* reading too much of the repository and losing precision;
* answering from loose summaries instead of project-specific evidence.
By keeping context scoped, sourced, and queryable, Potpie can:
* narrow debugging to the relevant execution surface;
* map the likely blast radius of a change before editing code;
* retrieve prior decisions and durable learnings instead of rediscovering them;
* move from broad task context to exact files only when deeper evidence is required.
## How The Graph Fits In
The graph is an important implementation layer inside the Context Engine, but it is not the whole product.
Use the graph-facing model when you need:
* typed entities and relationships;
* source-backed claims with provenance;
* semantic mutation proposals and guarded commits;
* backend-level capabilities such as graph reads, inspection, analytics, and snapshots.
Use the broader **Context Engine** framing when you are describing how Potpie actually works for users and agents: a CLI-first, pot-scoped context system that turns project signals into usable developer context.
# Parsing
Source: https://docs.potpie.ai/concepts/parsing
With Potpie, you can with ease, parse through repository’s complex source code, build a structured dependency graph & seamlessly capture every symbol along with their relationship.
]![a simple image showing code to graph text]()
## Repo Onboarding
As you add a repository, Potpie instantly validates the current parsed `status`.
If parsed graph exists, then potpie uses the existing graph, else the repository is passed to the **File Analysis**.
## File Analysis
Every file in the repository is evaluated before parsing action is initiated.
* Files without meaningful source code, such as images, binaries, or notebooks, are excluded early on to avoid unnecessary processing.
* Files with recognized source extensions are accepted as valid inputs and forwarded for structured analysis.
## AST Querying
Each file is parsed into an abstract syntax tree and queried for symbols, which are extracted by matching the file against the language grammar.
* Every `function`, `class`, `method`, or `interface` discovered is recorded with its exact name and precise location in the codebase.
* Each symbol is also classified to indicate whether it represents an **original definition** or a **reference** to a definition elsewhere.
## Graph Construction
* **Definitions** are represented as nodes in the knowledge graph.
* **References** between symbols are represented as edges.
This creates a navigable structural map of the codebase that captures not only what exists, but also interdependency between the components.
## Storage
* The repository is marked as `ready` only when all nodes & relationships are persisted.
* Any subsequent request for the same commit skips parsing entirely and queries the existing graph directly.
# Custom Agents
Source: https://docs.potpie.ai/custom-agents/introduction
Build an agent with a defined role, goal, and task set that runs against your codebase.
A custom agent runs a defined `role`, `goal`, and `task` set against your codebase. You control which tools it uses, who can access it, and what it produces.
***
## Before you begin
* A Potpie account
* Your repository parsed and `ready` . If you haven't done this yet see [API Access](/agents/api-access) .
***
## Define the agent
A custom agent is built from four required attributes that together determine how it thinks, what it prioritizes, and how it formats its output.
The professional function the agent adopts. Shapes how it frames analysis and what expertise it draws on. Be specific — "Senior Automated Code Review Agent" produces more focused output than "Code Reviewer."
The primary objective, stated specifically and measurably. The agent uses this to evaluate whether a task is complete. Vague goals produce vague results.
Professional context that informs the agent's decision-making — experience level, methodology, domain standards. This shapes judgment calls the agent makes when instructions are ambiguous.
High-level instructions applied across all tasks — output format, edge case handling, quality standards. Use this to enforce consistent structure across every response the agent produces.
***
## Configure tasks
Each agent requires between one and five tasks. A task defines what the agent does, which tools it can use, and what its output should look like.
What the task accomplishes, focused on outcomes rather than steps. Potpie automatically enhances this with step-by-step reasoning before the agent runs, so you don't need to enumerate every action — describe the goal.
Tool IDs the agent can use for this task. At least one is required. See [Tools Reference](/agents/tools-reference) for all valid IDs and what each tool does.
A JSON object specifying the format and structure of the task result. Use this to enforce consistent output — for example, a markdown report with specific sections, or a JSON object with defined keys.
MCP server configurations scoped to this task. The schema is accepted but MCP execution is not active in the current release.
***
## Set access permissions
Agent access can be scoped to just you, shared with specific teammates by email, or made available to everyone in your organization.
***
## Full example: Code review agent
The following example shows a complete agent built from a plain-language prompt.
**User prompt**
> I need an agent that can help software developers with code reviews. It should analyze pull requests, identify potential bugs, suggest improvements for code quality, and ensure best practices are followed.
***
**role**
```
Senior Automated Code Review & Pull Request Quality Agent
```
**goal**
```
Help software developers by reviewing pull requests end-to-end — analyze changes, identify
potential bugs and security issues, suggest concrete improvements for code quality and
maintainability, and ensure team best practices are followed.
```
**backstory**
```
A staff-level software engineer and code quality specialist with deep experience across
backend, frontend, and DevOps stacks. Has led large-scale code review programs, authored
secure coding standards, and mentored teams on maintainability, testing discipline, and
performance.
```
**system\_prompt**
```
Return all findings as markdown. Prioritize by impact. Show evidence from diffs.
Provide minimal, safe patches or precise suggestions for every blocker.
```
***
**Task**
Perform a comprehensive pull request code review — analyze the diff, identify bugs and security issues, suggest concrete improvements, evaluate testing and rollout risk, and optionally post inline review comments and create follow-up issues.
`change_detection`, `get_changes_for_pr`, `get_file_diff`, `get_code_file_structure`, `analyze_code_structure`, `fetch_file`, `fetch_files_batch`, `intelligent_code_graph`, `ask_knowledge_graph_queries`, `get_code_graph_from_node_id`, `get_node_neighbours_from_node_id`, `get_code_from_node_id`, `execute_terminal_command`, `show_diff`, `apply_changes`, `github_add_pr_comments`, `create_jira_issue`, `get_linear_issue`
Markdown PR review report containing: PR overview, risk assessment, prioritized findings (Blocker / Major / Minor / Nit) with file citations and suggested fixes, tests and quality gates, best practices checklist, and links to any created issues or PR comments.
***
## What to do next
* Follow the step-by-step walkthrough → [Configure a Custom Agent](/tutorials/configure-custom-agents)
* See what Potpie's built-in agents can do → [Forge](/build-flow/forge)
* Connect external services to extend your agent → [Integrations](/extensions/overview)
# Auth Flow
Source: https://docs.potpie.ai/examples/auth-flow
Understand how authentication works before building a protected endpoint.
Adding a protected endpoint on top of an unmapped auth implementation risks mismatched token validation, broken access rules, or bypassed middleware. Reading through the codebase manually to map the full flow leaves gaps.
**Ask** traces the full **authentication flow** through the [context graph](/concepts/context-engine), from incoming request to token validation to access enforcement, and returns every file involved with exact line ranges.
**Question:**
```
How is authentication handled across the API? What middleware validates tokens and how do protected routes enforce access?
```
**Ask traces:**
1. The middleware that intercepts and validates incoming tokens
2. The auth service and its dependencies
3. How protected routes enforce access rules
**Response includes:**
* Token validation middleware with exact file paths and line ranges
* Auth service implementation and every file it depends on
* Every protected route and the access rules applied to each
The same auth pattern applies directly to the new endpoint. [**Build**](/build-flow/build-a-feature) generates the implementation matching the existing pattern exactly.
Try it yourself on your codebase → [Ask Your Codebase](/tutorials/explore-your-codebase)
# Auth Middleware
Source: https://docs.potpie.ai/examples/auth-middleware
Update authentication middleware consistently across every protected route.
Updating authentication middleware with unmapped route dependencies leaves some routes on the old implementation. In a large API, manually auditing every route for middleware usage is error-prone.
**Build** maps every route that depends on the middleware through the [context graph](/concepts/context-engine), generates the updated implementation, and surfaces every affected file as a **diff** before applying anything.
**Request:**
```
Update the authentication middleware to support OAuth
```
**Build traces:**
* Every route that applies the current middleware
* Every file that imports or configures it
* Any tests that cover the existing behavior
**Code generation includes:**
* Updated middleware implementation with OAuth support
* Adjustments to every dependent route where the interface changes
* Modified test coverage reflecting the new behavior
The complete change set appears as a **diff** before PR creation. [Create the PR](/build-flow/build-a-feature#what-it-produces) directly from the **diff** view.
Try it yourself on your codebase → [Build a Feature](/tutorials/make-code-changes)
# Code Migration
Source: https://docs.potpie.ai/examples/code-migration
Migrate a module to a new pattern with full dependency awareness.
Migrating a module to a new pattern requires knowing every file that needs to change before starting. A change that appears isolated often touches dozens of consumers, interfaces, and tests across layers.
**Build** reads the existing module through the [context graph](/concepts/context-engine), maps every dependent service and interface, and generates a **specification** listing every file to create or modify before a line of code is written.
**Request:**
```
Migrate the payment module from REST to GraphQL
```
**Build maps:**
* Every service that consumes the current module's interface
* Every contract or type definition that needs to change
* Every test that covers the existing behavior
**Code generation includes:**
* Updated module implementing the new pattern
* Adjusted consumers with matching interface changes
* Modified tests reflecting the new contract
The complete change set appears as a **diff** before PR creation. [Create the PR](/build-flow/build-a-feature#what-it-produces) directly from the **diff** view.
Try it yourself on your codebase → [Build a Feature](/tutorials/make-code-changes)
# Code Review
Source: https://docs.potpie.ai/examples/code-review
Understand exactly what a PR changes across the full codebase before approving it.
Reviewing a pull request from the diff alone misses what it actually affects. A two-line change to a shared utility can break a dozen callers across the codebase. This guide shows you how to map the full impact of any PR before you approve it.
## Before you begin
* Your repository is connected and indexed in Potpie ([quickstart](/quickstart))
* You have a pull request open that you want to review
## Run the analysis
Go to [Potpie](https://app.potpie.ai) → **Ask** and select your repository.
Describe what the PR modifies and ask what it affects:
```
What does changing the UserService.updateProfile method affect across the codebase?
```
Ask traverses the [context graph](/concepts/context-engine) from every modified function outward, mapping all callers, dependents, and transitive effects.
Ask returns:
* Every function, class, and module that depends on the changed code
* Each call site with its exact file path and line number
* Areas of the codebase most likely to regress from this change
## Results
Once you have the impact map, you have two paths:
**Approve with confidence** by using the file paths and line numbers to verify each affected call site is handled correctly in the PR diff.
If any affected path looks risky, **hand off to Debug** by opening a [Debug](/build-flow/debug-an-issue) conversation and tracing the code path to verify no regression was introduced.
## Try it on your codebase
→ [Explore your codebase with Ask](/tutorials/explore-your-codebase)
# Impact Analysis
Source: https://docs.potpie.ai/examples/impact-analysis
Find everything that depends on a service before you change it.
Changing a core service without knowing its dependents turns a contained refactor into a cascade of broken builds. This guide shows you how to map the full blast radius of any service change before touching a single line of code.
## Before you begin
* Your repository is connected and indexed in Potpie ([how to connect a repo](/tutorials/connect-your-repo))
* You know the name of the service or interface you want to change
## Run the analysis
Go to [Potpie](https://app.potpie.ai) → **Ask** and select your repository.
Describe the service you want to change and ask what depends on it:
```
What depends on PaymentService and what breaks if I change its interface?
```
Ask traverses the [context graph](/concepts/context-engine) outward from the target service, mapping every dependent function, class, and module across the repository.
Ask returns:
* Every class, function, and module that calls or imports `PaymentService`
* Each call site with its exact file path and line number
* Transitive dependencies that would be affected by an interface change
## Results
Once you have the dependency map, you have two paths:
**Proceed manually** by updating each call site yourself using the file paths and line numbers, knowing nothing is missed.
**Hand off to Build** by pasting the dependency list into a [Build](/build-flow/build-a-feature) conversation. Build uses the same map to generate a spec and a diff across every affected file simultaneously.
## Try it on your codebase
→ [Explore your codebase with Ask](/tutorials/explore-your-codebase)
# Memory Leak
Source: https://docs.potpie.ai/examples/memory-leak
Trace a memory leak in a long running service to its source across object lifecycle and dependency chains.
A long running service degrading over time rarely points to the leak in its stack trace. Heap growth across requests can originate in a cache, an event listener, a retained reference, or a closure hiding across multiple files and layers.
**Debug** traces **object lifecycle** and retention patterns across the codebase through the [context graph](/concepts/context-engine), identifies exactly what holds in memory and why, and returns a targeted fix at the source.
**Issue:**
```
The background worker service crashes after several hours due to out-of-memory errors.
```
**Potpie traces:**
1. The background worker and its request handling loop
2. Objects allocated per request and whether they release properly
3. Any caches, listeners, or references that accumulate across requests
**Root cause citation:**
* Exact file and line where objects persist beyond their lifecycle
* The reference chain preventing garbage collection
**Fix includes:**
* Corrected object lifecycle management at the source
* Assessment of whether the same retention pattern exists elsewhere in the service
[**Build**](/build-flow/build-a-feature) generates the corrected code as a reviewable **diff**.
Try it yourself on your codebase → [Debug an Issue](/tutorials/trace-and-fix)
# Null Pointer
Source: https://docs.potpie.ai/examples/null-pointer
Trace a null pointer exception to its origin across service and data layers.
A null pointer exception surfacing in a generic service layer shows where the crash happens, while the null value originates elsewhere. Tracing it backwards through multiple service and data layers manually leaves the true origin uncertain.
**Debug** traces the full execution path through the [context graph](/concepts/context-engine) from the point of failure back to the source, identifies exactly where the null value enters without a guard, and returns a targeted fix.
**Issue:**
```
Users are getting null pointer errors during checkout with empty carts.
```
**Potpie traces:**
1. The checkout controller that receives the request
2. The cart service and how it handles empty state
3. The downstream order service that fails on null cart data
**Root cause citation:**
* Exact file path and line where the null value passes through without a null check
* The dependent call site that throws the exception
**Fix includes:**
* Null guard at the correct layer with the minimal change required
* Verification across all call sites for the same missing check
[**Build**](/build-flow/build-a-feature) generates the corrected code as a reviewable **diff**.
Try it yourself on your codebase → [Debug an Issue](/tutorials/trace-and-fix)
# Example Uses
Source: https://docs.potpie.ai/examples/overview
Real tasks across Ask, Build, and Debug , each grounded in your actual codebase.
Map every downstream dependency from any service before making a change.
Understand exactly what a PR changes across the full codebase before approving it.
Apply rate limits across all routes with full middleware chain awareness and per-endpoint policies.
Migrate a module to a new pattern with full dependency awareness.
Trace a memory leak in a long-running service to its source across object lifecycle and dependency chains.
Trace and fix race conditions causing intermittent failures in production.
## Next Steps
* Connect your first repository and try these tasks against your own codebase by following the [quickstart](/quickstart).
* To understand how each mode works, read through [Ask](/build-flow/ask-a-question), [Build](/build-flow/build-a-feature), and [Debug](/build-flow/debug-an-issue).
# Race Conditions
Source: https://docs.potpie.ai/examples/race-conditions
Trace and fix race conditions causing intermittent failures in production.
Race conditions leave intermittent, hard to reproduce failures in production. The stack trace shows where the failure surfaces, while the unsafe shared state originates elsewhere.
**Debug** walks the [context graph](/concepts/context-engine) through every concurrent code path involved in the failure, identifies the exact timing window where state is shared unsafely, and returns a targeted fix pinpointing the precise file and line that needs a guard.
**Issue:**
```
Orders occasionally duplicate during checkout. Only happens under load.
```
**Potpie traces:**
1. The checkout controller and how it handles concurrent requests
2. The order creation service and how it manages shared state
3. The point where two concurrent requests write to the same record without a lock
**Root cause citation:**
* Exact file and line where the missing lock allows concurrent writes
* The shared resource receiving unsynchronized concurrent writes
**Fix includes:**
* Lock or atomic operation at the correct layer with the minimal change required
* Verification across all shared resources for the same exposure pattern
[**Build**](/build-flow/build-a-feature) generates the corrected code as a reviewable **diff**.
Try it yourself on your codebase → [Debug an Issue](/tutorials/trace-and-fix)
# Rate Limiting
Source: https://docs.potpie.ai/examples/rate-limiting
Add rate limiting to existing routes with full middleware chain awareness.
Adding rate limiting to an existing API without mapping every route, middleware chain, and configuration surface leaves gaps. Some routes get protected. Others don't. Limits set in one place conflict with defaults defined elsewhere.
**Build** reads the full routing structure through the [context graph](/concepts/context-engine), identifies every entry point that needs a limit, and generates a **specification** covering every file to create or modify before writing a line.
**Request:**
```
Add rate limiting to all public API routes — 100 requests per minute per IP, with a stricter 10 per minute on auth endpoints
```
**Build maps:**
* Every public route and its position in the middleware stack
* Existing middleware configuration files and where limits are currently defined
* Auth-specific routes that need a separate, stricter policy
* Any tests covering route behavior that need updating
**Code generation includes:**
* Rate limiting middleware wired into the existing middleware chain
* Per-route and per-group limit configuration matching the existing config structure
* Updated auth route handlers with the stricter policy applied
* Test coverage reflecting the new limiting behavior
The complete change set appears as a **diff** before PR creation. [Create the PR](/build-flow/build-a-feature#what-it-produces) directly from the **diff** view.
Try it yourself on your codebase → [Build a Feature](/tutorials/make-code-changes)
# Refactor Scope
Source: https://docs.potpie.ai/examples/refactor-scope
Map every dependency before touching a shared service.
Refactoring a shared service with an incomplete dependency tree breaks callers the refactor missed. In a large codebase, the actual scope of a "small" change rarely surfaces from the service itself.
**Ask** maps every dependent across the [context graph](/concepts/context-engine) using the **Node Neighbors** tool, organized by dependency type, so the full impact surfaces before touching a single line.
**Question:**
```
What depends on UserService?
```
**Ask returns:**
* Every class, function, and module that imports or calls `UserService`
* Every call site with its exact file path and line number, organized by dependency type
* Transitive dependencies that could be affected by interface changes
**Ask** maps the full **blast radius** before the refactor begins. [**Build**](/build-flow/build-a-feature) uses the same dependency map to generate a spec and **diff** scoped to every affected file.
Try it yourself on your codebase → [Ask Your Codebase](/tutorials/explore-your-codebase)
# Potpie
Source: https://docs.potpie.ai/introduction
## What is Potpie
Potpie's proprietary [Context Engine](/concepts/context-engine) enables agents to understand your codebase in the depth required for complex **multi-hop** reasoning across components for **debugging**, **refactoring**, and other advanced tasks.
The **Spec driven development** workflow prioritizes upfront planning to define clear requirements and architecture so the code thats fits right into your codebase.
![Potpie]()
Index a branch to generate project context. Potpie builds the context layer and does the rest.
Start your [5-minute quickstart journey →](/quickstart)
Explore [example use cases](/examples/overview) across Ask, Build, and Debug, each grounded in real engineering tasks.
## Next Steps
* [Quickstart](/quickstart) - Set up Potpie and connect your first repository in just three steps.
* [Context Engine](/concepts/context-engine) - Understand how Potpie turns code, history, and durable memory into usable agent context.
# Spec Agent
Source: https://docs.potpie.ai/pre-built-agents/specgen-agent
The Spec Agent analyzes your repository before asking a single question. It first identifies your actual stack, architecture, and existing patterns, then asks clarifying questions grounded in those findings. The specification it produces is tailored to your codebase rather than built from a generic template.
## How It Works
### Explore the Codebase
The agent starts by reading the repository before any user interaction. It builds the full file tree, discovers the framework, architectural patterns, database and ORM layer, and main entry points, then reads the README, dependency manifests, and the main entry file.
If specific nodes are referenced in the request, it fetches their code and maps their neighbors before proceeding.
### Ask Clarifying Questions
The agent generates three to five multiple choice questions grounded in what it actually finds in the repository. These cover the real framework in use, the existing authentication mechanism, and the configured database. Every option is derived directly from those findings, so every question reflects the actual implementation rather than hypothetical choices.
## Generate the specification
Upon the user replying with their choices, the agent treats those answers as hard constraints and combines them with the original request and codebase findings to produce a full specification:
* **Technical Specification** : the complete requirements document produced for the requested feature
* **Executive Summary** : what is being built, for whom, and the main outcomes
* **Context** : project overview, original request, summary of clarification answers, and research findings
* **Success Metrics** : 3–4 measurable outcomes
* **Functional Requirements** : each with description, acceptance criteria, and priority
* **Non-Functional Requirements** : each with measurement criteria
* **Architecture** : narrative description and a Mermaid diagram
* **Technical Design** : data models, interfaces and API endpoints, external dependencies
* **Notes and Open Questions** : follow-ups and caveats.
### Refinement
If a prior specification exists in the conversation history, the agent skips exploration and clarification entirely. It retrieves the most recent version of the spec, applies only the requested modification (whether updating a section, adding a requirement, or removing content), and outputs the fully revised document. All unchanged sections are preserved exactly as they were.
Clarifying questions are skipped unless the change is ambiguous, in which case the agent asks at most one question before proceeding.
***
## Calling the Agent
```bash theme={null}
curl -X POST http://localhost:8001/api/v2/conversations/ \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"project_ids": ["proj_abc123"],
"agent_ids": ["spec_generation_agent"]
}'
```
Once you have a `conversation_id`, describe what you want to build:
```bash theme={null}
curl -X POST http://localhost:8001/api/v2/conversations/conv_xyz789/message/ \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"content": "Add a notifications system that supports email and in-app alerts"
}'
```
***
## Next Steps
* See [Code Generation Agent](/agents/code-changes-agent) to implement the specification
* See [Codebase Q\&A Agent](/agents/qna-agent) to explore the codebase before speccing a feature
# Quickstart
Source: https://docs.potpie.ai/quickstart
Start using Potpie for your codebase in four steps.
Create your Potpie account and connect your GitHub account to allow Potpie AI agents access your codebases.
![Sign Up Page]()
![Repository Selection]()
Once the repo is selected, Potpie captures your entire codebase in a **graphical index** which captures all the cannonical relationships(`classes`, `interfaces`, `files`, and `functions`) present in the codebase and performs [inference](/concepts/inference) at every abstraction level.
Start a conversation with your indexed codebase.
![Select a Mode]()
Potpie offers different agents/modes depending on your task. Each mode utilizes the same codebase graph but is optimized for a specialized task.
You can explore more about these modes here:
Cited and precise graph answers.
Builds that adapt to the codebase.
Root cause traced through the graph.
## Next Steps
* [Tutorial: Make Your First Query](/tutorials/explore-your-codebase) - Learn how to ask questions and explore your codebase.
* [Tutorial: Make Code Changes](/tutorials/make-code-changes) - Use the Build agent to make code changes with codebase awareness.
* [Concepts: Context Engine](/concepts/context-engine) - Understand how Potpie builds usable agent context for your codebase.
* [API Reference](/api-reference/overview) - Integrate Potpie agents into your workflow programmatically.
# Local Setup
Source: https://docs.potpie.ai/self-hosting/setup
Run Potpie locally on your own infrastructure.
## Before you begin
Make sure you have the following installed:
* [Docker](https://docker.com) installed and running
* [Git](https://git-scm.com) installed
* [Python 3.11+](https://python.org) with [uv](https://docs.astral.sh/uv/)
***
## Install Potpie
```bash theme={null}
git clone --recurse-submodules https://github.com/potpie-ai/potpie.git
cd potpie
```
```bash theme={null}
cp .env.template .env
```
Open `.env` and fill in the values — see `.env.template` in the repository for all required and optional fields including LLM provider, database, Redis, and storage settings.
Set `isDevelopmentMode=enabled` to parse local repositories directly, or `isDevelopmentMode=disabled` to use GitHub-connected repos.
Using Ollama? Set `LLM_PROVIDER=ollama` and use `ollama_chat/qwen2.5-coder:7b` for both `CHAT_MODEL` and `INFERENCE_MODEL`.
```bash theme={null}
curl -LsSf https://astral.sh/uv/install.sh | sh
uv sync
```
This creates a `.venv` directory and installs all dependencies from `pyproject.toml`.
```bash theme={null}
chmod +x scripts/start.sh
./scripts/start.sh
```
The script starts Docker services, waits for PostgreSQL to be ready, applies database migrations, starts the FastAPI application, and starts the Celery worker.
```bash theme={null}
curl -X GET 'http://localhost:8001/health'
```
To stop all services:
```bash theme={null}
./scripts/stop.sh
```
***
## Set up the frontend
```bash theme={null}
cd potpie-ui
cp .env.template .env
pnpm build && pnpm start
```
***
## Configure GitHub authentication
Potpie supports three methods for accessing GitHub repositories. The method is selected automatically based on which environment variables are set.
**GitHub App** *(recommended for production)*
Your GitHub App's numeric ID. Found in the app's settings page on GitHub.
The private key generated when you created the GitHub App.
Create a GitHub App in your organization with the following permissions, then set the variables above in `.env`:
| Scope | Permission |
| ------------------------ | -------------- |
| Repository Contents | Read only |
| Repository Metadata | Read only |
| Repository Pull requests | Read and write |
| Repository Secrets | Read only |
| Repository Webhooks | Read only |
| Organization Members | Read only |
| Account Email address | Read only |
Once the app is created, select **Install App** from its sidebar and install it on your target organization or user account.
***
**Personal Access Token Pool** *(recommended for development)*
A comma-separated list of GitHub personal access tokens with `repo` scope. Potpie randomly selects from the pool for load balancing. Each token allows 5,000 requests per hour.
```bash theme={null}
GH_TOKEN_LIST=ghp_token1,ghp_token2,ghp_token3
```
***
**Unauthenticated** *(public repositories only)*
No configuration required. Rate-limited to 60 requests per hour. Not recommended for anything beyond initial testing.
***
## Use a self-hosted Git provider
For self-hosted Git servers such as GitBucket, set the following in `.env`:
The Git provider to use. Accepted values: `github`, `gitbucket`.
Base URL of your self-hosted Git server's API.
```bash theme={null}
CODE_PROVIDER_BASE_URL=http://your-git-server.com/api/v3
```
Access token for your self-hosted Git server.
`GH_TOKEN_LIST` tokens are always used for GitHub.com requests regardless of what `CODE_PROVIDER_BASE_URL` is set to.
***
## Enable observability with Logfire *(optional)*
[Logfire](https://logfire.pydantic.dev) provides LLM trace monitoring for Potpie. Get a token at [logfire.pydantic.dev](https://logfire.pydantic.dev) and add it to `.env`:
Your Logfire project token. Tracing is initialized automatically on startup once this is set. View traces at [logfire.pydantic.dev](https://logfire.pydantic.dev).
Set to `false` to disable sending traces to Logfire cloud and keep all trace data local.
# Configure Custom Agents
Source: https://docs.potpie.ai/tutorials/configure-custom-agents
In this tutorial, you'll learn how to configure a custom agent in Potpie that runs against your codebase's knowledge graph with access to the same tool library as the built-in agents.
To understand how custom agents work, see the [Custom Agents page](/custom-agents/introduction).
## Creating an Agent
Review the configuration and create the agent. The agent is ready for immediate use in conversations.
![Agent Creation]()
Specify the agent's **role**, **goal**, **backstory**, and **system prompt**. These four attributes establish the agent's identity and govern how it approaches every task.
![Agent Identity Configuration]()
Define between one and five tasks. For each task, provide a description, select the tools the agent may use, and specify the expected output format.
![Task and Tool Configuration]()
# Explore Your Codebase
Source: https://docs.potpie.ai/tutorials/explore-your-codebase
In this tutorial, you'll learn how to use Ask in Potpie to get cited answers grounded in your actual source code, with exact file paths and line numbers for every claim.
To understand how Ask works, see the [Ask mode page](/build-flow/ask-a-question).
Type a natural language question about the codebase. **Ask** handles **flow tracing** and **dependency mapping**.
![Chat interface]()
Potpie returns an answer with file paths and line references where relevant.
![Response in progress]()
![Completed response with citations]()
When a question involves a third-party library, it retrieves external documentation via `web search`.
# Generate an API Key
Source: https://docs.potpie.ai/tutorials/generate-api-key
In this tutorial, you'll learn how to generate an API key in Potpie to authenticate access and interact with any repository, agent, or conversation .
To understand how API access works, see the [API Access page](/agents/api-access).
## Generating an API Key
Open Potpie and sign in.
![Potpie Dashboard]()
Click the account menu in the bottom-left corner and select **Settings**.
![Username menu]()
In the **API Key** section, click **+ Generate API Key**.
![API Key Management]()
Copy and store the key securely.
![Generated API Key]()
# Make Code Changes
Source: https://docs.potpie.ai/tutorials/make-code-changes
In this tutorial, you'll learn how to use Build in Potpie to generate code that matches your codebase's exact patterns and review every change as a diff before it reaches the repository.
To understand how Build works, see the [Build mode page](/build-flow/build-a-feature).
## Workflow
Enter a description of the feature for to build.
![Feature description input]()
Potpie surfaces a set of clarifying questions as multiple choice options. Answers lock in the scope and requirements before the specification begins.
![Clarifying questions]()
Potpie parses the codebase against the confirmed requirements and generates a specification covering every file to create or modify, implementation details for each change, and dependency relationships between affected components.
![Specification page]()
Once the spec is confirmed, Potpie generates a plan.
An explanation of what changes, which parts of the codebase are in scope, and how the new code fits the existing system.
![Plan summary tab]()
A dependency graph showing how new components wire into existing services, data models, and API boundaries as they exist in the repository.
![Architecture tab]()
Each task lists the target file, implementation intent, dependency order, and the verification criteria checked after each diff is generated.
![Plan items tab]()
Potpie generates the code and presents every change as a **diff**. Changes match the existing code style and conventions identified during **specification**.
![Code generation diff view]()
Clicking **Create PR** pushes the full diff to the repository.
![Final review before PR]()
# Trace and Fix Bugs
Source: https://docs.potpie.ai/tutorials/trace-and-fix
In this tutorial, you'll learn how to use Debug in Potpie to trace a reported issue to its origin in the knowledge graph and get a fix at the source, not a symptom patch.
To understand how Debug works, see the [Debug mode page](/build-flow/debug-an-issue).
Paste an error message, stack trace, or describe the unexpected behavior. Include any context about when it occurs.
![Describing the issue]()
Follow up messages within the same session retain full context. Start with a high-level symptom and narrow to the root cause across subsequent turns.
The **Debug Agent** applies its **eight step methodology** automatically: validating the behavior, traversing code paths, pinning the **root cause**, and generating a targeted fix.
![Bug analysis and targeted fix]()