# Pi Coding Agent Integration

Remnic ships a native Pi Coding Agent extension through `@remnic/plugin-pi`.
It uses Pi's extension hooks instead of wrapping Pi with a parallel runtime.

> Using the [Oh My Pi (omp)](https://omp.sh) fork? The same runtime extension
> works there via the `omp` connector — see [omp.md](./omp.md).

## Install

Start the Remnic daemon, then install the connector:

```bash
remnic daemon start
remnic connectors install pi
```

The installer writes:

- `~/.pi/agent/extensions/remnic/index.ts` — Pi auto-discovery wrapper
- `~/.pi/agent/extensions/remnic/remnic.config.json` — private daemon URL, namespace, and auth token (`0600`)
- `~/.pi/agent/extensions/remnic/README.md` — local operator notes

To skip writing the Pi extension and only create the connector/token:

```bash
remnic connectors install pi --config installExtension=false
```

To target a non-default daemon or namespace:

```bash
remnic connectors install pi \
  --config remnicDaemonUrl=http://127.0.0.1:4318 \
  --config namespace=work
```

## What The Extension Does

- Uses Pi's `context` hook to recall relevant Remnic context before an agent turn.
- Uses `agent_end`, `turn_end`, and `session_shutdown` hooks to observe Pi messages and tool activity with `sourceFormat: "pi"`.
- Uses `session_before_compact` to flush Remnic LCM for the active session before Pi compacts context.
- Records the compaction token delta after Pi produces the compacted checkpoint.
- Registers Remnic MCP tools as Pi tools when the Remnic daemon token is configured.
- Persists lightweight dedupe state with Pi `custom` entries so repeated turns are not re-observed.

## Pi Commands

The extension registers these Pi slash commands:

- `/remnic-status` — check daemon health
- `/remnic-recall <query>` — recall Remnic context for a query
- `/remnic-remember <memory>` — explicitly store a memory
- `/remnic-lcm-search <query>` — search archived Pi context
- `/remnic-why` — inspect the last recall explanation
- `/remnic-compact` — request Pi compaction

## Configuration

The extension loads configuration from:

1. `REMNIC_PI_CONFIG`
2. `~/.pi/agent/extensions/remnic/remnic.config.json`

Supported config keys:

| Key | Default | Description |
|-----|---------|-------------|
| `remnicDaemonUrl` | `http://127.0.0.1:4318` | Remnic HTTP/MCP daemon URL |
| `authToken` | unset | Connector token generated by `remnic connectors install pi` |
| `namespace` | unset | Remnic namespace for recall/observe/store requests |
| `recallMode` | `auto` | Recall mode: `auto`, `minimal`, `full`, `graph_mode`, or `no_recall` |
| `recallTopK` | `8` | Max recalled results |
| `recallBudgetChars` | `12000` | Max recalled context injected into Pi |
| `recallEnabled` | `true` | Enable context-hook recall |
| `observeEnabled` | `true` | Enable Pi turn observation |
| `observeSkipExtraction` | `false` | Archive observed messages without extraction |
| `compactionEnabled` | `true` | Enable LCM flush/checkpoint coordination |
| `mcpToolsEnabled` | `true` | Register Remnic MCP tools as Pi tools |
| `statusEnabled` | `true` | Set Pi UI status from daemon health |
| `requestTimeoutMs` | `60000` | HTTP/MCP request timeout for recall/observe/compaction/commands |
| `startupRequestTimeoutMs` | `1000` | Shorter timeout for startup-sensitive probes (MCP `tools/list` registration and the `session_start` health/status check) so a slow or offline daemon can't stall Pi boot |

Boolean-like strings such as `"false"`, `"0"`, `"no"`, and `"off"` are treated as false.

> **Remote daemons: raise `startupRequestTimeoutMs`.** MCP tool registration happens once at session start (`tools/list` against the daemon) under this timeout, and a timeout is swallowed silently — the session simply runs without any `remnic_*` tools, while the separate (lighter) health probe can still report the daemon as ready. The `1000` default is tuned for a localhost daemon; when `remnicDaemonUrl` points at another machine (Tailscale/MagicDNS, VPN, LAN), one cold DNS resolution or relayed round trip can exceed it. Set `"startupRequestTimeoutMs": 10000` for remote daemons, and prefer a stable Tailscale IP over a MagicDNS name on hosts where MagicDNS is not enabled.

## API Surface

Pi uses the shared Remnic access layer:

- `POST /engram/v1/recall`
- `POST /engram/v1/observe`
- `POST /engram/v1/lcm/search`
- `POST /engram/v1/lcm/compaction/flush`
- `POST /engram/v1/lcm/compaction/record`
- `POST /mcp` for MCP tool discovery and calls

Both canonical `remnic.*` MCP tools and legacy `engram.*` aliases remain available through the daemon.
