Pi Coding Agent

Sessions are stored as JSONL (JSON Lines) files. Each line is a single JSON object representing a SessionEntryBase.

Tree Structure

Entries form a tree structure using id and parentId fields. This allows for in-place branching (e.g., via /fork) without creating new files.

• The first entry (the SessionHeader) has no parentId.
• Subsequent entries point to their parent via parentId.
• The "leaf" represents the current position in the conversation.

File Location

Sessions are located at: ~/.pi/agent/sessions/--<path>--/<timestamp>_<uuid>.jsonl

Note: <path> is the working directory with / replaced by -.

Skills are self-contained capability packages that the agent loads on-demand. They provide specialized workflows, setup instructions, helper scripts, and reference documentation for specific tasks.

Pi uses a progressive disclosure model:

1. Startup: Pi scans skill locations and extracts names and descriptions.
2. Context: Available skill names and descriptions are included in the system prompt in XML format.
3. On-demand Loading: When a task matches a skill's description, the agent uses the read tool to load the full SKILL.md file.
4. Execution: The agent follows the instructions in the skill, using relative paths to access associated scripts, references, or assets.

Note: Models do not always load the full skill automatically. You can force the agent to load a skill by using the /skill:name command or via explicit prompting.

Both compaction and branch summarization use a standardized Markdown structure to preserve context. This format ensures that when the agent's context is compressed, the most critical information—goals, progress, and decisions—is retained for the LLM.

Summary Structure

## Goal
[What the user is trying to accomplish]

## Constraints & Preferences
- [Requirements mentioned by user]

## Progress
### Done
- [x] [Completed tasks]

### In Progress
- [ ] [Current work]

### Blocked
- [Issues, if any]

## Key Decisions
- **[Decision]**: [Rationale]

## Next Steps
1. [What should happen next]

## Critical Context
- [Data needed to continue]

<read-files>
path/to/file1.ts
path/to/file2.ts
</read-files>

<modified-files>
path/to/changed.ts
</modified-files>

To prevent exhausting context windows in long sessions, Pi uses compaction to summarize older messages while preserving recent ones.

Compaction Methods

• Manual: Use the /compact command. You can provide optional custom instructions: /compact <custom instructions>.
• Automatic: Enabled by default. It triggers on context overflow (recovers and retries) or when approaching the limit (proactive).

Note: Compaction is lossy. The full history remains in the JSONL file and can be revisited using the /tree command.

Pi uses termux-clipboard-set and termux-clipboard-get for clipboard operations.

Important Limitations:

• No image clipboard: The Termux clipboard API only supports text; ctrl+v image pasting will not work.
• No native binaries: Some optional native dependencies (like the clipboard module) are skipped during installation on Android ARM64.

Prompt templates are Markdown snippets that expand into full prompts within the editor. You invoke a template by typing /name (where name is the filename without the .md extension). Pi provides autocomplete that displays available templates along with their descriptions and argument hints.

/review                           # Expands review.md
/component Button                 # Expands with argument
/component Button "click handler" # Multiple arguments

When Pi scans prompts/ directories for templates, the discovery process is non-recursive. If you need to use templates organized in subdirectories, you must either:

1. Add the specific subdirectories explicitly via the prompts settings.
2. Define them in a package manifest.

When building custom TUI components for the Pi agent, follow these critical rules:

1. Theme Access: Always use the theme object provided in the ctx.ui.custom callback. Never import a theme directly.
2. Type Safety: When using DynamicBorder, always explicitly type the color parameter: (s: string) => theme.fg("accent", s).
3. Rendering Lifecycle: Always call tui.requestRender() inside your handleInput method after any state changes to ensure the UI updates.
4. Component Interface: Custom components must return an object implementing the three-method interface: { render, invalidate, handleInput }.
5. Reuse Components: Prioritize using built-in components like SelectList, SettingsList, and BorderedLoader instead of building from scratch.

The behavior of the session leaf pointer depends on the type of node you select in the tree:

User Message or Custom Message

1. The leaf is set to the parent of the selected node (or null if it is the root).
2. The message text is placed in the editor for re-submission.
3. Submitting the edited text creates a new branch.

Non-User Message (assistant, compaction, etc.)

1. The leaf is set to the selected node itself.
2. The editor remains empty.
3. You continue the conversation from that point.

Selecting the Root User Message

If you select the very first message in the session (which has no parent):

1. The leaf is reset to null (resulting in an empty conversation).
2. The message text is placed in the editor.
3. This effectively restarts the session from scratch.