diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/docs/configuration/config.md | 27 | ||||
| -rw-r--r-- | docs/docs/guide/agent-hooks.md | 126 | ||||
| -rw-r--r-- | docs/mkdocs.yml | 1 |
3 files changed, 154 insertions, 0 deletions
diff --git a/docs/docs/configuration/config.md b/docs/docs/configuration/config.md index f453f903..3d4f6b25 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"` or `"codex"`. + +```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 new file mode 100644 index 00000000..6e02b794 --- /dev/null +++ b/docs/docs/guide/agent-hooks.md @@ -0,0 +1,126 @@ +# 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. + +## Quick Start + +Install hooks for your agent, then restart the agent: + +```shell +# Claude Code +atuin hook install claude-code + +# Codex +atuin hook install codex +``` + +That's it. Commands the agent runs will now appear in your Atuin history, tagged with the agent's name. + +## How It Works + +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: + +| Agent | Config file | +|-------|-------------| +| Claude Code | `~/.claude/settings.json` | +| Codex | `~/.codex/hooks.json` | + +The hook lifecycle: + +1. **PreToolUse** -- the agent is about to run a Bash command. Atuin records the command, working directory, and timestamp (same as `history start`). +2. **PostToolUse / PostToolUseFailure** -- the command finished. Atuin records the exit code and duration (same as `history end`). + +Only `Bash` tool invocations are captured. Other tool types (file writes, web fetches, etc.) are ignored. + +## Filtering by Author + +By default, Atuin's interactive search shows only your own commands. Agent-run commands are hidden so they don't clutter your history. + +This is controlled by the `search.authors` setting in `~/.config/atuin/config.toml`: + +```toml +[search] +# Default: only show commands from human users +authors = ["$all-user"] +``` + +### Special filter values + +| Value | Meaning | +|-------|---------| +| `$all-user` | Any author that is **not** a known AI agent | +| `$all-agent` | Any known AI agent author | + +You can also use literal author names: + +```toml +[search] +# Show only your own commands and Claude Code commands +authors = ["$all-user", "claude-code"] +``` + +```toml +[search] +# Show everything (no filtering) +authors = [] +``` + +```toml +[search] +# Show only agent commands +authors = ["$all-agent"] +``` + +Currently recognized agent names are: `claude-code`, `codex`, and `copilot`. + +## Supported Agents + +### Claude Code + +```shell +atuin hook install claude-code +``` + +This adds hook entries to `~/.claude/settings.json`. Claude Code calls `atuin hook claude-code` on each `Bash` tool use, passing the event as JSON on stdin. + +### Codex + +```shell +atuin hook install codex +``` + +This adds hook entries to `~/.codex/hooks.json`. Codex calls `atuin hook codex` on each Bash tool use matching `^Bash$`. + +## Verifying Installation + +After installing hooks and restarting your agent, run a command through the agent and then check your history: + +```shell +# Show all history including agent commands +atuin search --authors '' -- '' + +# Show only agent commands +atuin search --authors '$all-agent' -- '' +``` + +You can also check the agent's config file directly to confirm the hooks are registered: + +```shell +# Claude Code +cat ~/.claude/settings.json | grep atuin + +# Codex +cat ~/.codex/hooks.json | grep atuin +``` + +## Re-installing + +Running `atuin hook install` again is safe. If hooks are already installed, the command will skip them and print a message: + +``` +hooks.PreToolUse: already installed, skipping +hooks.PostToolUse: already installed, skipping +hooks.PostToolUseFailure: already installed, skipping +``` diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml index 00adcfb2..a25dfa8f 100644 --- a/docs/mkdocs.yml +++ b/docs/mkdocs.yml @@ -70,6 +70,7 @@ nav: - Basic usage: guide/basic-usage.md - Advanced usage: guide/advanced-usage.md - Shell Integration: guide/shell-integration.md + - AI Agent Hooks: guide/agent-hooks.md - Deleting history: guide/delete-history.md - Syncing dotfiles: guide/dotfiles.md - Theming: guide/theming.md |