tony · tony · May 31, 2026 · May 30, 2026 · May 30, 2026 · May 30, 2026
diff --git a/CHANGES b/CHANGES
@@ -42,6 +42,24 @@ $ uvx --from 'agentgrep' --prerelease allow python
 
 <!-- END PLACEHOLDER - ADD NEW CHANGELOG ENTRIES BELOW THIS LINE -->
 
+### What's new
+
+#### Pi backend (#28)
+
+agentgrep now searches [Pi](https://github.com/earendil-works/pi) (the
+earendil-works "Pi Agent Harness") as a new backend. Pi keeps each
+conversation as one append-only JSONL session file under
+`~/.pi/agent/sessions/`, grouped by working directory, with no separate
+prompt-history log or SQLite index — so user prompts surface as prompts
+and assistant and tool turns as history straight from the transcript.
+Discovery honours `PI_CODING_AGENT_DIR` and the flat
+`PI_CODING_AGENT_SESSION_DIR` override (where the working directory is
+recovered from the session header), and every other on-disk pi store —
+settings, models, themes, tools, managed binaries, prompt templates,
+the debug log, and the npm extension root — is catalogued for
+completeness, with `auth.json` documented but never indexed. See
+{doc}`/backends/pi` for details.
+
 ## agentgrep 0.1.0a11 (2026-05-31)
 
 agentgrep 0.1.0a11 splits the Cursor backend into two agents —

diff --git a/README.md b/README.md
@@ -5,7 +5,7 @@
 [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
 
 Read-only search for local AI agent prompts and history across Codex,
-Claude Code, Cursor, Gemini, and Grok.
+Claude Code, Cursor, Gemini, Grok, and Pi.
 
 `agentgrep` provides a CLI and an MCP server over the same discovery + parsing layer:
 

diff --git a/docs/backends/index.md b/docs/backends/index.md
@@ -47,6 +47,12 @@ Gemini CLI chat sessions, prompt logs, checkpoints, settings, and skills.
 Grok CLI prompt history, session transcripts, memory, logs, and config.
 :::
 
+:::{grid-item-card} Pi
+:link: pi
+:link-type: doc
+Pi (earendil-works) session transcripts, settings, prompts, and managed extensions.
+:::
+
 ::::
 
 ## Coverage levels
@@ -84,4 +90,5 @@ cursor-cli
 cursor-ide
 gemini
 grok
+pi
 ```
diff --git a/docs/backends/pi.md b/docs/backends/pi.md
@@ -0,0 +1,72 @@
+(backend-pi)=
+
+# Pi
+
+Base path: `~/.pi/agent` (env override: `PI_CODING_AGENT_DIR`).
+
+`observed_version`: `pi v0.78.0` (observed 2026-05-30).
+
+pi (the earendil-works "Pi Agent Harness") stores each conversation as
+one append-only JSONL file under `~/.pi/agent/sessions/`, grouped by
+working directory. The directory key is the cwd with its leading slash
+stripped and `/`, `\`, and `:` replaced by `-`, wrapped in double
+dashes (e.g. `--home-d-work-python-agentgrep--`). Each session file is
+named `<iso-timestamp>_<session-uuid>.jsonl`.
+
+Unlike Codex or Grok, pi keeps no separate prompt-history log and no
+SQLite session index — the session transcript is the entire searchable
+surface, which makes pi the structural twin of the Claude Code backend.
+
+The optional `PI_CODING_AGENT_SESSION_DIR` override points at the
+sessions directory directly. When it is set, pi writes session files
+flat into that directory with no per-working-directory subdirectory;
+agentgrep then recovers the cwd from each session's header rather than
+the directory name.
+
+## Stores
+
+```{storage:agent} pi
+```
+
+## Record schemas
+
+### pi.sessions
+
+The first line is a session header; `version` is `3` and may be absent
+in older (v1) files.
+
+```json
+{"type": "session", "version": 3, "id": "019e5691-...",
+ "timestamp": "2026-05-23T20:41:01.417Z",
+ "cwd": "/home/d/work/python/agentgrep"}
+```
+
+Every later line is a `SessionEntry` sharing `id` / `parentId` /
+`timestamp` (an append-only tree, not a flat list). A `message` entry
+wraps an LLM message; `role` is `user`, `assistant`, or `toolResult`,
+and `content` is a string or a content-blocks array. Assistant turns
+carry `model` and `provider` inline.
+
+```json
+{"type": "message", "id": "...", "parentId": "...",
+ "timestamp": "2026-05-23T20:41:05.000Z",
+ "message": {"role": "user",
+             "content": [{"type": "text", "text": "..."}],
+             "timestamp": 1779999665000}}
+```
+
+User turns surface as prompts and assistant / tool turns as history via
+the shared role-to-kind mapping. `compaction` and `branch_summary`
+entries contribute their `summary` text, and `session_info` contributes
+its user-set `name`; `model_change`, `thinking_level_change`, `custom`,
+and `label` entries are metadata only. Entry-level timestamps are
+ISO-8601; the inner `message.timestamp` is unix-milliseconds and is used
+only as a fallback.
+
+## Documentary stores
+
+The remaining `pi.*` rows are catalogued for completeness but not
+searched: `pi.settings`, `pi.models`, `pi.themes`, `pi.tools`,
+`pi.bin`, `pi.prompts`, `pi.debug_log`, and `pi.extensions_npm` (the
+managed npm extension install root). `pi.auth` holds provider
+credentials and is documented but never enumerated from disk.
diff --git a/docs/dev/index.md b/docs/dev/index.md
@@ -16,7 +16,7 @@ Cross-commit `hyperfine` sweeps across HEAD, trunk, ranges, lookback, tags, or e
 :::{grid-item-card} Storage catalogue
 :link: storage-catalog
 :link-type: doc
-On-disk store layouts for Codex, Claude Code, Cursor, Gemini CLI, and Grok CLI — useful for adapter authors and anyone tracing why a record was or wasn't found.
+On-disk store layouts for Codex, Claude Code, Cursor, Gemini CLI, Grok CLI, and Pi — useful for adapter authors and anyone tracing why a record was or wasn't found.
 :::
 
 :::{grid-item-card} Architecture decisions

diff --git a/docs/dev/storage-catalog.md b/docs/dev/storage-catalog.md
@@ -279,6 +279,34 @@ Documentary-only entries cover events, summaries, memory, logs,
 worktrees, and config — all catalogued with `search_by_default=False`
 or deferred.
 
+### Pi
+
+`observed_version`: ``pi v0.78.0`` (observed 2026-05-30).
+
+Pi (earendil-works) stores each conversation as one append-only JSONL
+file under `${PI_CODING_AGENT_DIR or ${HOME}/.pi/agent}/sessions/`,
+grouped by working directory (`--<encoded_cwd>--`, leading slash
+stripped and `/ \ :` replaced by `-`). It keeps no separate
+prompt-history log and no SQLite index, so a single adapter covers the
+whole searchable surface:
+
+- `pi.sessions_jsonl.v1` parses `sessions/--<cwd>--/<ts>_<uuid>.jsonl`.
+  Line one is a `type:"session"` header (`version` may be absent in v1
+  files); each later line is a `SessionEntry` tagged union. `message`
+  entries carry an LLM message (`role` user / assistant / toolResult,
+  `content` string or content-blocks; assistant turns carry `model`),
+  while `compaction` / `branch_summary` summaries and `session_info`
+  names are emitted as history text. User turns surface as prompts via
+  the shared role-to-kind mapping.
+
+Discovery resolves two roots: `PI_CODING_AGENT_DIR` (the agent dir,
+default `~/.pi/agent`) and the optional `PI_CODING_AGENT_SESSION_DIR`,
+which holds session files flat with the cwd recovered from the header.
+
+Documentary-only entries cover settings, auth (private credentials),
+models, themes, tools, managed binaries, prompt templates, the debug
+log, and the npm extension install root.
+
 ## Adding or updating a store
 
 1. Edit `src/agentgrep/store_catalog.py`. Stamp `observed_version`

diff --git a/docs/getting-started/configuration.md b/docs/getting-started/configuration.md
@@ -12,7 +12,7 @@ Use `--agent` one or more times to limit search or discovery:
 $ uv run agentgrep grep "cache" --agent codex
 ```
 
-Supported agents are `codex`, `claude`, `cursor-cli`, `cursor-ide`, `gemini`, and `grok`. Omitting `--agent` searches all supported agents.
+Supported agents are `codex`, `claude`, `cursor-cli`, `cursor-ide`, `gemini`, `grok`, and `pi`. Omitting `--agent` searches all supported agents.
 
 ## Search type
 

diff --git a/docs/index.md b/docs/index.md
@@ -2,7 +2,7 @@
 
 # agentgrep
 
-Read-only search for local AI agent prompts and history across Codex, Claude Code, Cursor, Gemini, and Grok.
+Read-only search for local AI agent prompts and history across Codex, Claude Code, Cursor, Gemini, Grok, and Pi.
 
 ```{warning}
 **Pre-alpha.** APIs may change. [Feedback welcome](https://github.com/tony/agentgrep/issues).

diff --git a/docs/mcp/resources.md b/docs/mcp/resources.md
@@ -26,7 +26,7 @@ used to interpret that source.
 ```{fastmcp-resource-template} agentgrep_sources_by_agent
 ```
 
-Read `agentgrep://sources/codex`, `agentgrep://sources/claude`, `agentgrep://sources/cursor-cli`, `agentgrep://sources/cursor-ide`, `agentgrep://sources/gemini`, or `agentgrep://sources/grok` to filter discovery by agent.
+Read `agentgrep://sources/codex`, `agentgrep://sources/claude`, `agentgrep://sources/cursor-cli`, `agentgrep://sources/cursor-ide`, `agentgrep://sources/gemini`, `agentgrep://sources/grok`, or `agentgrep://sources/pi` to filter discovery by agent.
 
 ## Store catalog
 

diff --git a/docs/tui/index.md b/docs/tui/index.md
@@ -3,7 +3,7 @@
 # TUI
 
 The `agentgrep ui` command launches the interactive Textual explorer
-over the same Codex, Claude Code, Cursor, Gemini, and Grok stores the rest
+over the same Codex, Claude Code, Cursor, Gemini, Grok, and Pi stores the rest
 of the CLI walks. It is read-only — agentgrep never mutates the
 source stores. Bare `agentgrep` prints the directory of choices, so
 the explorer always needs the explicit `ui` subcommand.

diff --git a/pyproject.toml b/pyproject.toml
@@ -1,7 +1,7 @@
 [project]
 name = "agentgrep"
 version = "0.1.0a11"
-description = "Read-only search for local AI agent prompts and history (Codex, Claude Code, Cursor, Gemini, Grok)"
+description = "Read-only search for local AI agent prompts and history (Codex, Claude Code, Cursor, Gemini, Grok, Pi)"
 requires-python = ">=3.14,<4.0"
 authors = [
   {name = "Tony Narlock", email = "tony@git-pull.com"}
@@ -21,7 +21,7 @@ classifiers = [
   "Typing :: Typed",
 ]
 
-keywords = ["ai", "codex", "claude", "cursor", "gemini", "grok", "mcp", "search", "agent-history"]
+keywords = ["ai", "codex", "claude", "cursor", "gemini", "grok", "pi", "mcp", "search", "agent-history"]
 readme = "README.md"
 packages = [
   { include = "*", from = "src" },