# pi

> Import pi coding agent sessions along the branch you last worked on, with tool calls, token usage, and estimated cost.

pi saves JSONL sessions in folders named after the working directory. Hansard
supports the five session formats pi has used, from its early linear files to
the tree format of versions 2 and 3.

## Source IDs

| Source | Use it for                                         |
| ------ | -------------------------------------------------- |
| `pi`   | pi coding agent sessions and their branch history. |

## How the import works

Hansard scans pi's JSONL sessions, which are grouped by an encoded working
directory. Linear sessions replay in their saved order. For tree sessions,
Hansard starts at the last entry in the file and follows each entry's parent
back to the start, which is the branch pi resumes. User and assistant
messages, reasoning, tool calls and results, model changes, compactions, token
usage, and cost become the conversation. The working directory sets the
project.

pi 1.1.0 keeps session version 3 and adds explicit system messages, standalone
usage, and context edits. Hansard preserves those records with their types.
Context edits describe changes to model input and do not erase the original
archived messages. System sections retain explicit clears and tool definitions.
Summary usage stays separate from reply-model attribution when no model was
recorded.

Entries on abandoned branches stay in the archive's exact copy of the file,
but they do not appear in the conversation or its details. Hansard rejects
files it cannot identify, files that mix formats, damaged files, files that
change while being read, and files over the size limit, instead of guessing
the closest format. Importing again updates a session with the same ID. Fields
that an older pi version never wrote stay empty rather than being estimated.

## Import and keep current

**Import now**

```sh
hansard import --source pi --since all
hansard index rebuild
```

**Keep current**

With **Automatic** source selection, the watcher already includes `pi`. With
a **Custom** list, enable it. The watcher picks it up within 30 seconds:

```sh
hansard config sources enable pi
```

## Review the import in the app

1. When the import finishes, open **Conversations** and select **Filter & sort**.
2. Set **Source** to **pi** and set **Time** to the window you imported. Use **Folder** to narrow the list when you use this harness in several projects.
3. Select a conversation to check its messages, tool calls, files, commits, model, and token usage.

To keep archiving new sessions from a local harness, open **Settings → Imports**. **Automatic** follows every supported harness installed on this computer. **Custom** lets you turn individual harnesses on or off. Cloud sources and account exports never run from here; each needs its own import command. If a conversation you expect is missing after you reset the filters, run the import command on this page again with `--explain-skips` where the source supports it.

## What Hansard preserves

- User and assistant messages, reasoning, and tool calls and results.
- The branch pi resumes, compaction records, model changes, input and output
  tokens, and pi's estimated cost calculated from configured model rates.
- Recorded response models separately from requested models and model selections.
- Explicit zero counters separately from missing token and cost fields.
- The working directory from the session's folder name.
- An exact copy of each JSONL file next to the conversation.

## Known limitations

- Hansard imports only records that belong to a valid pi session tree.
- oh-my-pi, a fork of pi, uses a different format and is not supported.
- Fields that older pi formats did not record stay empty. Hansard does not
  fill them in from later releases.
- Reasoning effort follows recorded configuration only for a matching request
  model. A reply with a different model or provider clears the earlier effort.
  pi can omit configuration changes when resuming through the CLI; an unrecorded
  effort change for the same model cannot be detected from the session file.
- Native validation covers pi `0.73.1` with a local synthetic endpoint, resumed
  turns, successful and failed edits, a failed shell command, an image result,
  repeated import, and offline raw rebuild. Hosted accounting, extensions,
  forks, compaction, and full viewer acceptance remain unverified.
- A separate upstream audit covers pi `1.1.0` with synthetic regressions.
  No local `1.1.0` store was available for native acceptance.

## Refresh an existing archive

```sh
hansard import --source pi --since all
hansard index rebuild
```

The current parser separates response models from selections, marks calculated
costs as estimates, preserves zero counters, and counts successful native edit
pairs. Sessions archived by an earlier parser need a reimport to refresh these
fields. If the original JSONL is unavailable,
rebuild from its verified preserved copy:

```sh
hansard rebuild --from-raw --provider pi --since all
```