setup-atuin-hook

name	setup-atuin-hook
description	Install or update the Codex Atuin PreToolUse/PostToolUse hook in the current workspace or user config, then validate it by checking Atuin history.

Setup Atuin Hook

Use this skill when the user wants the Codex Atuin hook installed, updated, or verified.

What this plugin provides

• hooks/post_tool_use_to_atuin.py: entrypoint for the hook
• hooks/codex_atuin_hook/: shared implementation for payload parsing, Atuin I/O, and state
• examples/hooks.json: sample hook registration

Installation workflow

1. Decide whether the user wants workspace-local or user-global setup.
2. Enable Codex hooks in the relevant .codex/config.toml:

[features]
codex_hooks = true

3. Add both PreToolUse and PostToolUse registrations to .codex/hooks.json, matching only Bash.
4. Point the command at this plugin's hooks/post_tool_use_to_atuin.py.
5. Set CODEX_ATUIN_AUTHOR and CODEX_ATUIN_INTENT inline in the hook command when the user wants explicit metadata.
6. Validate by running a Bash tool command in Codex and checking:

atuin history last --format '{command}|{author}|{intent}|{exit}|{duration}'

Notes

• Prefer a project-local .codex/ folder when the user asks to test in one repo.
• The hook is designed to fail open if Atuin is missing.
• The robust path uses tool_use_id across PreToolUse and PostToolUse to compute duration.