## Pi: AI Coding Agent for the Command Line

Entire integrates with Pi through a project-local TypeScript extension, automatically capturing sessions and checkpoints. The Pi integration is in preview and may contain bugs.

## Prerequisites

- [Entire CLI installed](https://docs.entire.io/installation)
- [Pi](https://pi.dev/) installed and configured
- A Git repository with Entire enabled

## Enable

```
entire agent add pi
pi
```

`entire agent add pi` installs a TypeScript extension at `.pi/extensions/entire/index.ts`. Pi loads the extension from the project and forwards lifecycle events to Entire.

## How it works

Entire integrates with Pi through project-level extension hooks. The extension tracks the session lifecycle:

1. **Session Start** — `session_start` creates a new Entire session.
2. **Prompt Tracking** — `before_agent_start` captures each user prompt and the active transcript path.
3. **Turn Completion** — `agent_end` finalizes the turn and captures a stable transcript snapshot.
4. **Session Cleanup** — `session_shutdown` clears the active session cache.
5. **Transcript Capture** — Entire reads Pi’s JSONL session transcript from `~/.pi/agent/sessions/` or `PI_CODING_AGENT_DIR`.
6. **Session Storage** — data is saved to the `entire/checkpoints/v1` branch.

## What gets captured

| Data           | Description                                          |
| ---------------| ----------------------------------------------------|
| Conversation    | Full transcript of prompts and responses            |
| File changes    | Files modified through Pi `write` and `edit` tools |
| Tool calls      | Tool invocations with inputs and outputs            |
| Token usage     | Input, output, cache-read, and cache-write tokens   |
| Timestamps      | Session, turn, and checkpoint timing                |

## Features

**Rewind during sessions.** Use `entire checkpoint rewind` to restore to a previous checkpoint during or after a Pi session. When you rewind, Entire restores the checkpointed transcript state and shows the command to continue the Pi session. See the [`checkpoint rewind` command reference](https://docs.entire.io/cli-reference/checkpoint#checkpoint-rewind) for full flag documentation.

**Resume previous sessions.** Switch to a session’s branch with `entire session resume BRANCH`. The CLI restores the session log if needed and prints `pi --session SESSION_ID`. See the [`session resume` command reference](https://docs.entire.io/cli-reference/sessions#session-resume) for full flag documentation.

**Explain commits.** Inspect any commit or checkpoint with `entire checkpoint explain`. See the [`checkpoint explain` command reference](https://docs.entire.io/cli-reference/checkpoint#checkpoint-explain) for full flag documentation.

## Caveats and limitations

1. **The integration is in preview.** Pi support may have rough edges while the extension and transcript format settle.
2. **Hooks are extension-based.** Pi loads Entire through `.pi/extensions/entire/index.ts` instead of a JSON hook config.
3. **Transcript capture depends on Pi writing JSONL session files.** Entire reads from Pi’s session store and caches snapshots under `.entire/tmp/pi/`.
4. **Subagent capture is not available.** Pi does not currently expose a subagent transcript tree, so Entire captures the main Pi session.
5. **Shell-written files are less granular in transcript analysis.** Entire extracts file paths from Pi’s `write` and `edit` tools; shell commands that modify files are still represented by Git diffs at checkpoint time.

## Best practices

**Enable Pi through Entire.** Use `entire agent add pi` instead of manually creating the extension. Entire preserves the expected extension shape and can reinstall it safely.

**Commit at logical points.** Create checkpoints at natural stopping points: after implementing a feature, before risky refactors, or when you’d want to rewind later.

**Keep Pi session files available.** If you plan to attach or resume older sessions, keep Pi’s session store under `~/.pi/agent/sessions/` or your configured `PI_CODING_AGENT_DIR`.

## Example workflow

```
# 1. Enable Entire with Pi
cd my-project

# 2. Start Pi
pi

# 3. Work with Pi
# Ask it to write code, make changes, and iterate

# 4. Check status (in another terminal)
entire status

# 5. Rewind if needed
entire checkpoint rewind

# 6. Commit when ready
git add .
git commit -m "Add feature with Pi"

# 7. Push to see on entire.io
git push
```

Your session is now visible on [entire.io](/content/site-root.html) with full context for code review.

## Troubleshooting

### Session not being captured

1. Verify Entire is enabled: `entire status`
2. Check that `.pi/extensions/entire/index.ts` exists in the repository
3. Ensure Pi is running from within the repository
4. Reinstall hooks with `entire agent add pi --force`

### No checkpoints created

1. Checkpoints require file changes — ensure Pi is modifying files
2. Commit or stage work as part of your normal Git flow
3. Check your settings in `.entire/settings.json`
4. Verify the Pi extension was installed with `entire agent add pi`

### Transcript not captured

1. Ensure Pi is writing JSONL files under `~/.pi/agent/sessions/` or `PI_CODING_AGENT_DIR`
2. Check that the active session has a valid `.jsonl` transcript file
3. Look for errors in Entire hook output with `entire doctor`