npm package: @hjanuschka/pi-entire
Description: Pi coding agent extension for Entire.io session tracking
Author: hjanuschka
Latest version: 1.0.0

# Pi-Entire Extension

Integrates [pi coding agent](https://github.com/badlogic/pi-mono) with [Entire.io](https://entire.io) for automatic AI session capture and tracking.

## What is Entire?

Entire hooks into your git workflow to capture AI agent sessions on every push. Sessions are indexed alongside commits, creating a searchable record of how code was written in your repo.

## Features

- **Automatic Session Tracking**: Tracks prompts, files modified, and checkpoints during pi sessions
- **Checkpoint Counting**: Shows checkpoint count in the status bar
- **Session Metadata**: Writes session metadata to `.entire/metadata/` for Entire to consume
- **Status Command**: `/entire status` shows current session info
- **LLM Tool**: `entire_status` tool lets the LLM check session status

## Installation

### 1. Install Entire CLI

```bash
curl -fsSL https://entire.io/install.sh | bash
```

Or via Homebrew:
```bash
brew tap entireio/tap
brew install entireio/tap/entire
```

### 2. Enable Entire in Your Repository

```bash
cd your-project
entire enable
```

### 3. Install the Pi Extension

Add to your `~/.pi/agent/settings.json`:
```json
{
  "packages": [
    "npm:@hjanuschka/pi-entire"
  ]
}
```

Or for project-local installation, add to `.pi/settings.json`:
```json
{
  "packages": [
    "npm:@hjanuschka/pi-entire"
  ]
}
```

Then restart pi or use `/reload` to load the extension.

## Usage

### Status Bar

When Entire is active, you'll see a status indicator in pi's footer:
```
📦 Entire: 5 checkpoints
```

### Commands

| Command | Description |
|---------|-------------|
| `/entire status` | Show current session status |
| `/entire rewind` | Rewind to a previous checkpoint |
| `/entire help` | Show available commands |

### LLM Tool

The extension registers an `entire_status` tool that the LLM can use to check session status:

```
Use entire_status to check if session tracking is active
```

## How It Works

### Session Lifecycle

1. **Session Start**: When pi starts, the extension checks if Entire is enabled and creates a new session ID
2. **Turn Tracking**: After each agent turn, checkpoints are tracked and the status bar is updated
3. **Metadata Writing**: Session metadata (prompts, files modified) is written to `.entire/metadata/<session-id>/`
4. **Session End**: Final metadata is written when the session ends

### Integration with Entire Strategies

| Strategy | Behavior |
|----------|----------|
| **manual-commit** (default) | Checkpoints are created when you make a git commit |
| **auto-commit** | Checkpoints are created automatically after each agent response |

The extension tracks session state regardless of strategy - the actual checkpoint persistence is handled by Entire's git hooks.

## Configuration

No additional configuration required. The extension automatically:
- Detects if Entire CLI is installed
- Checks if Entire is enabled in the current repository
- Tracks session state in memory

## Comparison: Pi vs Claude Code / Gemini CLI

Entire was originally built for Claude Code and Gemini CLI. Here's how the pi integration compares:

| Feature | Claude Code / Gemini | Pi |
|---------|---------------------|-----|
| Checkpoint Saving | Via agent hooks | Via turn_end events |
| Session Metadata | Agent-provided | Extension-generated |
| Rewind Support | Full support | Full support |
| Strategy Support | Both strategies | Both strategies |

## Architecture

```
┌─────────────────────────────────────────────┐
│                Pi Coding Agent               │
│                                             │
│  ┌─────────────────────────────────────┐   │
│  │         Pi-Entire Extension          │   │
│  │                                      │   │
│  │  • session_start → check status     │   │
│  │  • turn_end → track checkpoint      │   │
│  │  • agent_end → write metadata       │   │
│  │  • /entire command                  │   │
│  │  • entire_status tool               │   │
│  └─────────────────────────────────────┘   │
│                    │                        │
└────────────────────┼────────────────────────┘
                     │
                     ▼
          ┌──────────────────┐
          │   Entire CLI     │
          │                  │
          │  • Git hooks     │
          │  • Checkpoints   │
          │  • Rewind        │
          └──────────────────┘
                     │
                     ▼
          ┌──────────────────┐
          │  entire/         │
          │  checkpoints/v1  │
          │  (metadata)      │
          └──────────────────┘
```

## Troubleshooting

### "Entire CLI not installed"

Install Entire:
```bash
curl -fsSL https://entire.io/install.sh | bash
```

Then add to PATH:
```bash
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc
```

### "Entire is not enabled"

Enable Entire in your repository:
```bash
cd your-project
entire enable
```

### Extension not loading

Check that the package is in your settings.json:
```bash
cat ~/.pi/agent/settings.json
# Should include: "packages": ["npm:@hjanuschka/pi-entire"]
```

Use `/reload` in pi to reload extensions, or restart pi.

## Development

### Testing the extension locally

```bash
# Load directly for development
pi -e ./index.ts

# Check extension is loaded
/entire status
```

### Publishing to npm

```bash
npm publish --access public
```

### Contributing

Contributions welcome! Please open issues and PRs at the Entire CLI repo:
https://github.com/entireio/cli

## License

MIT License - see [LICENSE](LICENSE) for details.

## Links

- [Entire.io](https://entire.io)
- [Entire CLI on GitHub](https://github.com/entireio/cli)
- [Pi Coding Agent](https://github.com/badlogic/pi-mono)