From 129ad222d2ea2896a06ed29cbce5faa0b0d7399e Mon Sep 17 00:00:00 2001
From: Ellie Huxtable <ellie@atuin.sh>
Date: Mon, 13 Apr 2026 20:41:30 +0100
Subject: feat: add pi hook installer (#3398)

Support installing the pi extension via `atuin hook install pi`. Bundle
the extension in the binary and update the docs.

<!-- Thank you for making a PR! Bug fixes are always welcome, but if
you're adding a new feature or changing an existing one, we'd really
appreciate if you open an issue, post on the forum, or drop in on
Discord -->

## Checks
- [ ] I am happy for maintainers to push small adjustments to this PR,
to speed up the review cycle
- [ ] I have checked that there are no existing pull requests for the
same thing
---
 docs/docs/configuration/config.md | 27 +++++++++++++++++++++++++++
 docs/docs/guide/agent-hooks.md    | 31 +++++++++++++++++++++++++------
 2 files changed, 52 insertions(+), 6 deletions(-)

(limited to 'docs')

diff --git a/docs/docs/configuration/config.md b/docs/docs/configuration/config.md
index f453f903..68ac9b82 100644
--- a/docs/docs/configuration/config.md
+++ b/docs/docs/configuration/config.md
@@ -576,6 +576,33 @@ frequency_score_multiplier = 0.8
 frecency_score_multiplier = 2.0
 ```
 
+#### `authors`
+
+Default: `["$all-user"]`
+
+Filter search results by command author. This controls which commands appear in interactive search based on who (or what) ran them. Useful when AI coding agents are recording commands via [agent hooks](../guide/agent-hooks.md).
+
+Special values:
+
+| Value | Meaning |
+|-------|---------|
+| `$all-user` | Commands from any author that is **not** a known AI agent |
+| `$all-agent` | Commands from any known AI agent |
+
+You can also use literal author names like `"claude-code"`, `"codex"`, or `"pi"`.
+
+```toml
+[search]
+# Default: only show human-authored commands
+authors = ["$all-user"]
+
+# Show everything (no author filtering)
+# authors = []
+
+# Show commands from you and Claude Code
+# authors = ["$all-user", "claude-code"]
+```
+
 ## Stats
 
 This section of client config is specifically for configuring Atuin stats calculations
diff --git a/docs/docs/guide/agent-hooks.md b/docs/docs/guide/agent-hooks.md
index 6e02b794..cefeb155 100644
--- a/docs/docs/guide/agent-hooks.md
+++ b/docs/docs/guide/agent-hooks.md
@@ -1,10 +1,10 @@
 # AI Agent Hooks
 
-Atuin can capture commands run by AI coding agents (like Claude Code and Codex) alongside your regular shell history. Each command is tagged with the agent that ran it, so you can filter your history by author.
+Atuin can capture commands run by AI coding agents (like Claude Code, Codex, and pi) alongside your regular shell history. Each command is tagged with the agent that ran it, so you can filter your history by author.
 
 ## Quick Start
 
-Install hooks for your agent, then restart the agent:
+Install hooks for your agent, then restart or reload the agent:
 
 ```shell
 # Claude Code
@@ -12,6 +12,9 @@ atuin hook install claude-code
 
 # Codex
 atuin hook install codex
+
+# pi
+atuin hook install pi
 ```
 
 That's it. Commands the agent runs will now appear in your Atuin history, tagged with the agent's name.
@@ -20,12 +23,13 @@ That's it. Commands the agent runs will now appear in your Atuin history, tagged
 
 AI coding agents support hook systems that notify external tools when they're about to run a shell command and when the command finishes. Atuin uses these hooks to record each command as a history entry, just like commands you type yourself.
 
-When `atuin hook install` runs, it writes the agent's config file to register Atuin as a hook handler:
+When `atuin hook install` runs, it writes the agent's config file or extension to register Atuin as a hook handler:
 
-| Agent | Config file |
-|-------|-------------|
+| Agent | Config file / extension |
+|-------|-------------------------|
 | Claude Code | `~/.claude/settings.json` |
 | Codex | `~/.codex/hooks.json` |
+| pi | `~/.pi/agent/extensions/atuin.ts` |
 
 The hook lifecycle:
 
@@ -73,7 +77,7 @@ authors = []
 authors = ["$all-agent"]
 ```
 
-Currently recognized agent names are: `claude-code`, `codex`, and `copilot`.
+Currently recognized agent names are: `claude-code`, `codex`, `copilot`, and `pi`.
 
 ## Supported Agents
 
@@ -93,6 +97,16 @@ atuin hook install codex
 
 This adds hook entries to `~/.codex/hooks.json`. Codex calls `atuin hook codex` on each Bash tool use matching `^Bash$`.
 
+### pi
+
+```shell
+atuin hook install pi
+```
+
+This writes Atuin's extension to `~/.pi/agent/extensions/atuin.ts`.
+
+Then restart pi or run `/reload`. The extension wraps pi's built-in `bash` tool and records every bash command with author `pi` by calling `atuin history start` before execution and `atuin history end` afterwards.
+
 ## Verifying Installation
 
 After installing hooks and restarting your agent, run a command through the agent and then check your history:
@@ -113,6 +127,9 @@ cat ~/.claude/settings.json | grep atuin
 
 # Codex
 cat ~/.codex/hooks.json | grep atuin
+
+# pi
+ls ~/.pi/agent/extensions/atuin.ts
 ```
 
 ## Re-installing
@@ -124,3 +141,5 @@ hooks.PreToolUse: already installed, skipping
 hooks.PostToolUse: already installed, skipping
 hooks.PostToolUseFailure: already installed, skipping
 ```
+
+For pi, reinstalling will also skip if the managed extension already matches the bundled version.
-- 
cgit v1.3.1