> ## Documentation Index
> Fetch the complete documentation index at: https://docs.entire.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Pi (Preview)

> Integrate Entire with Pi for AI coding session capture

Pi is an 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](/cli/installation)
* [Pi](https://pi.dev) installed and configured
* A Git repository with Entire enabled

## Enable

```bash theme={null}
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.

<AccordionGroup>
  <Accordion title="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.
  </Accordion>

  <Accordion title="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               |
  </Accordion>

  <Accordion title="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 [`rewind` command reference](/cli/commands#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 [`resume` command reference](/cli/commands#resume) for full flag documentation.

    **Explain commits.** Inspect any commit or checkpoint with `entire checkpoint explain`. See the [`explain` command reference](/cli/commands#explain) for full flag documentation.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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`.
  </Accordion>

  <Accordion title="Example workflow">
    ```bash theme={null}
    # 1. Enable Entire with Pi
    cd my-project
    entire agent add pi

    # 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](https://entire.io) with full context for code review.
  </Accordion>
</AccordionGroup>

## Troubleshooting

<AccordionGroup>
  <Accordion title="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`
  </Accordion>

  <Accordion title="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`
  </Accordion>

  <Accordion title="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`
  </Accordion>
</AccordionGroup>