recall-commands

name	recall-commands
description	atuin に記録された Claude Code の Bash 実行履歴をサルベージするための「正しいクエリ組み立て方」リファレンス

recall-commands

プラグインに組み込まれたフックによって Claude Code の Bash 実行履歴を {session} フィールドにセッション ID 紐付きで記録している。このスキルはその履歴を機械的に引くための「正しいクエリ組み立て方」を提供する。

atuin 単体の --help やドキュメントには載っていない挙動や、設計上のバグが複数あり、素直に使うと欲しい結果が得られない。検証で判明した使える組み合わせと、踏むと外れる罠をここに集約する。

共通のクエリ設計

出力フォーマット

後段で機械処理しやすいよう、pipe 区切りで --format を組む。ANSI 装飾は入らないので、そのままパイプに流せる。

利用可能なプレースホルダ (主要なもの):

• {time} — 実行時刻 (設定 TZ で表示)
• {session} — Claude Code セッション ID (UUID)
• {command} — 実行されたコマンド文字列
• {exit} — 終了コード (0 でない実行を絞りたいときに必須)
• {directory} — 実行ディレクトリ
• {duration} — 実行時間
• {author} — 実行者 (claude-code / 人間ユーザー名 / 他のエージェント名)

例: --format '{time}|{session}|{exit}|{command}'

コマンドの選び方

やりたいこと	使う CLI
特定セッション ID のコマンドだけ全件取りたい	atuin history list --session (環境変数 ATUIN_SESSION 必須)
コマンド文字列の部分一致で検索したい (逆引き含む)	atuin search --search-mode full-text
時間範囲・著者・終了コード・cwd で絞りたい	atuin search (絞り込みフラグが豊富)

セッション絞り込みと部分一致検索は 同じコマンドで両立できない (理由は後述の罠 1)。session 絞り込みが必須なら history list、そうでなければ search を選ぶ。

ユースケース 1 — 特定セッションの全履歴を取得

前セッション ID が分かっていて、その Bash 実行ログを丸ごと欲しいとき。

ATUIN_SESSION=<session-id> atuin history list --session \
  --format '{time}|{exit}|{command}'

注意点:

• --session フラグと ATUIN_SESSION 環境変数の 両方が必須。フラグだけだと atuin のデフォルト zsh session で絞り込まれてしまう
• 出力は時刻昇順 (古い順)
• atuin history list には --limit フラグが 無い。件数を絞るなら | head -N / | tail -N で外側から

現セッションを対象にする場合は、ATUIN_SESSION 環境変数がすでに存在するので atuin history list --session ... だけで OK。

ユースケース 2 — コマンド断片から session ID を逆引き

「chezmoi apply を打った session があったはず」のように、コマンド文字列の断片しか手がかりがないとき、それを実行した Claude Code セッション ID を特定する。

atuin search --search-mode full-text \
  --format '{time}|{session}|{command}' \
  '<コマンド断片>'

注意点:

• --search-mode full-text を 必ず付ける。デフォルト (prefix) と fuzzy は、クエリにマッチしないと無関係な最新コマンドをノイズとして返してくる (罠 2)
• --format のヘルプには {session} が載っていないが、実際は機能する (undocumented)
• session ID だけが欲しければ後段で | awk -F'|' '{print $2}' | sort -u で抽出

このスキルが確定させるのは「いつ・どの session で・どんなコマンドを」まで。逆引きした session ID を起点に当時の会話文脈まで辿る流れは別途まとめてある。

ユースケース 3 — 時間範囲・著者・終了コードで俯瞰

「直近で claude-code が打った失敗コマンドだけ見たい」のような俯瞰。

atuin search --author 'claude-code' \
  --exclude-exit 0 \
  --after '2026-05-20T00:00:00+09:00' \
  --format '{time}|{exit}|{command}' \
  --limit 50

主な絞り込みフラグ:

• --author 'claude-code' — Claude Code が実行したコマンドのみ
• --author '$all-agent' — 任意のエージェント (claude-code 以外も含む)
• --author '$all-user' — 人間ユーザーが直接打ったもの
• --exit N / --exclude-exit N — 終了コードで絞り込み・除外
• --cwd <path> / --exclude-cwd <path> — 実行ディレクトリで絞り込み・除外
• --after <時刻> / --before <時刻> — 時間範囲。書式は罠 3 を参照
• --limit N — 件数制限 (search 側にはある。history list には無い)

罠 (atuin v18.16.0 で確認)

罠 1: atuin search --filter-mode session は ATUIN_SESSION を見ない

--filter-mode session を付けても、参照されるのは atuin の zsh セッション ID であって ATUIN_SESSION 環境変数ではない。つまり Claude Code セッション ID での絞り込みには 使えない。

# 期待通りに動かない例 — Claude Code session ではなく atuin zsh session で絞られる
ATUIN_SESSION=<id> atuin search --filter-mode session

セッション絞り込みは atuin history list --session を使う (ユースケース 1)。

罠 2: search のデフォルト search-mode はクエリ不一致時にノイズを返す

atuin search のデフォルトは --search-mode prefix。これと fuzzy は、クエリ文字列にマッチするコマンドが無いときに、無関係な最新コマンドを大量に返してくる。コマンド断片で逆引きするには full-text モード一択。

# NG: 'chezmoiroot' を含まないコマンドが大量に混じる
atuin search 'chezmoiroot' --format '{session}|{command}'

# OK: 文字列を実際に含むコマンドだけ返る
atuin search --search-mode full-text 'chezmoiroot' --format '{session}|{command}'

罠 3: --before / --after は TZ 非明示時に UTC として解釈される

atuin issue #2808 — --before / --after の値にタイムゾーンオフセットが含まれていないと、ローカル TZ ではなく UTC として解釈される。--timezone / --tz フラグを足してもこの解釈は上書きされない。

# NG (JST 環境で): UTC として解釈されるので、JST 23:55 のコマンドはマッチしない
atuin search --after '2026-05-20 23:55:00'

# NG: --timezone フラグも効かない
atuin search --tz +09:00 --after '2026-05-20 23:55:00'

# OK: 値側にオフセットを必ず明示する
atuin search --after '2026-05-20T23:55:00+09:00'

ユーザーや上流から「今日の 0 時以降」のような自然文で時刻を受け取ったら、まず ISO 8601 + ローカル TZ オフセットに変換してから atuin に渡す:

date -d 'today 00:00' -Iseconds  # 例: 2026-05-20T00:00:00+09:00

罠 4: atuin history list に --limit が無い

件数制限は | head -N / | tail -N で外側から行う。--reverse で時刻順を反転できるので、最新 N 件が欲しければ --reverse=false と組み合わせる手もある。

罠 5: atuin search の --format ヘルプには {session} が載っていない

--help の出力上は {command}, {directory}, {duration}, {user}, {host}, {time}, {exit}, {relativetime} だけが列挙されているが、実際は {session} も機能する (undocumented)。逆引きのキモなので気にせず使う。

Claude Code セッション ID の取り方

取得元	方法
現セッション	環境変数 CLAUDE_CODE_SESSION_ID
前セッション	ユーザー提示・引き継ぎ文書など外部の手がかりから
コマンド断片しかないとき	ユースケース 2 で逆引き