2
1

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?

【ClaudeCode】Modを使って本筋/脱線管理機能の実装とClawdくんを住まわせてみた

2
Posted at

はじめに

Claude Code(以下CC)と長いセッションを回していると、話が横道にそれます。調べものの途中で別のエラーに気づき、その原因を追ううちに別の設定が気になり、と脱線を重ねて、気づくと 「そもそも何をしていたんだっけ」 となります。

そこで、CCのModで、サイドペインに「いまの本筋」と「どこまで脱線しているか」を出し続けるようにしました。ついでに、セッションの状態に合わせて動くClawd君も住まわせています。

clawd-sleeping.gif

この記事では次の2つを書きます。

  • 本筋と脱線を、LLMの要約なしで追う方法
  • Clawd君を、端末の中で動かす方法

最後に、この記事をAIエージェントに渡して同じものを作ってもらうためのセッションを置きました。

作ったもの

session-compassというModです。/compassで開くペイン(Compass)に、5つのウィジェットを並べます。

ウィジェット 中身
Clawd セッションの状態で絵が変わるClawd君(9状態)
いま 本筋・現状・あなたの番・次と、最後のやり取りからの経過時間
脱線 本筋から分かれた脱線の木。片づいた脱線は取り消し線で消える
タスク CCのタスクリスト
差分 このセッションで書き換えたファイルの差分

脱線しているときは「本筋に戻る」「ひとつ戻る」のボタンが出て、押すと戻るための依頼文がCCに送られます。セッションを閉じても本筋と脱線は備忘録として残り、同じフォルダで次のセッションを開くと「前回のセッション」として出てきます。

動作を確かめた環境は、Claude Code v2.1.314、macOS、端末はGhosttyです。

Modとは

Modは、CCの中で動くイベントハンドラ(hook)を集めたプラグインです。CCは、ツールの呼び出し、プロンプトの送信、画面の描画といったイベントのたびにhookを呼び、hookはイベントを眺めるだけでも、書き換えても、自分で引き受けてもかまいません。TypeScriptのファイルをそのまま読み込むので、ビルドは要りません。使えるのはv2.1.287以降です。

最小の構成は3つのファイルです。

session-compass/
├── .claude-plugin/
│   └── plugin.json
└── hooks/
    ├── hooks.json      # "modules": ["./register.tsx"] でhookのファイルを指す
    └── register.tsx    # register(on) を書き出す

hookはon('イベント名', async ($, e, next) => ...)の形で登録します。$がModから使えるAPI($.ui、$.store、$.clockなど)、eがイベントの中身、nextがCC本来の処理へ渡す関数です。

詳しくは公式ドキュメントのMods overviewとCreate a modにあります。

第1部 本筋と脱線

LLMに要約させず、CCに書かせて読む

最初の版では、会話の要約にHaikuを呼んでいました。Modからは$.model.completeでモデルを呼べますが、使うのは利用者のプランかAPIキーです。そこで、レート制限の値が取れるとき(サブスクリプションで使っているとき)だけ呼ぶ、という条件を付けていました。

それでも、ペインを出すためだけにトークンを使うのはもったいない。そこで発想を逆にしました。CCに、毎回の回答の末尾へ決まった形の「状況欄」を書かせ、Modはそれを読むだけにします。

状況欄を書かせるのは、~/.claude/rules/に置いた次のルールです(一部を省いています)。

~/.claude/rules/session-status.md
# 回答の末尾に付ける状況欄

脱線や日またぎで本筋と自分の番を見失わないよう、メインの会話の回答は、毎回、末尾を次の状況欄で終える。

```text
---
- 本筋: このセッションの主目的
- 脱線: いま扱っている脱線の題
- 現状: どこまで進んだか
- あなたの番: 本人が次に指示・確認・判断すること
- 次: CCが次にすること
```

- 5項目をこの順に、1項目を1行で書く。値は60文字以内の1文にし、該当するものが無い項目は「なし」と書く
- 本筋は、本人が主目的そのものを変えたときだけ書き換える。脱線や追加の質問では変えない
- 本筋と関係の薄い質問や別件を扱っている間は、脱線の欄にその題を書く。同じ脱線が続く間は同じ題を一字一句変えずに使い、本筋の作業に戻ったら「なし」にする
- 脱線からさらに別の話へ分かれたら、`分かれ元の題 > 新しい題` のように、本筋に近い脱線から順に ` > ` でつないで書く。先の脱線が片づいて分かれ元に戻ったら、分かれ元までの題だけを書く
- 脱線を扱っている間は、現状・あなたの番・次を、いちばん先の脱線について書く
- サブエージェントとして動くときの報告には付けない

すると、回答の末尾はこうなります。

---
- 本筋: ログイン画面のバリデーションを直す
- 脱線: CIのテストが落ちる > Dockerのメモリ不足
- 現状: Docker VMのメモリを増やしてテストを流し直している
- あなたの番: なし
- 次: テストが通ったら、CIの脱線を閉じて本筋に戻る

CCに書かせると、人が読んでも分かるのが利点です。ペインを開いていないときでも、回答の末尾を見れば本筋に戻れます。

状況欄を読み取る

ターンの終わり(turn.complete)に、回答の本文(e.answer)を読みます。気を付けたのは、本文の箇条書きがたまたま「次:」で始まる場合です。そこで、末尾の12行の中に3項目以上があり、しかも「現状」を含むときだけ、状況欄として扱います。

hooks/status.ts
const ITEM = /^\s*(?:[-*・]\s*)?\**\s*(本筋|脱線|現状|あなたの番|次)\s*\**\s*[::]\s*(.*)$/

export const parseStatus = (answer: string): Status | null => {
  const tail = answer
    .split('\n')
    .filter(line => line.trim() !== '')
    .slice(-SCANNED_LINES) // 12行
  const found = new Map<keyof Status, string | null>()
  for (const line of tail) {
    const matched = ITEM.exec(line)
    const field = FIELDS[matched?.[1] ?? '']
    if (field !== undefined) found.set(field, valueOf(matched?.[2] ?? ''))
  }
  if (found.size < REQUIRED_ITEMS || !found.has('state')) return null
  // ...
}

CCは太字や全角コロンを混ぜて書くことがあるので、正規表現でそれも受け付けます。

脱線の木を組み立てる

脱線の欄のCIのテストが落ちる > Dockerのメモリ不足を>で分けると、本筋から今いる脱線までの道筋になります。ターンごとに、前のターンの道筋と比べて木を更新します。

  • 新しい題が出てきた: 脱線を作り、分かれる直前の分かれ元の「現状」と「次」を、戻り先として控える
  • 道筋が短くなった(分かれ元や本筋に戻った): その先の脱線を「収束」として閉じ、取り消し線で消す
  • 関係のない脱線へ移った: 扱っていた脱線を「未収束」として残し、あとで「再開」「打ち切る」を選べるようにする

ルールでは「同じ題を一字一句変えずに使う」と頼んでいますが、CCは空白だけ違えて書くことがあります。そのため、題は空白を除いて比べています。

本筋に戻るボタン

スクリーンショット 2026-11-17 16.52.30.png

「本筋に戻る」を押すと、Modは次のような依頼文をCCに送ります。

脱線「CIのテストが落ちる」はここまでにして、本筋「ログイン画面のバリデーションを直す」に戻ります。
脱線に入る前の本筋の状況: エラーメッセージの文言を直し、テストを書いている
そのとき次にする予定だったこと: テストを流して、画面で確かめる
脱線で分かったこと・決まったことを1〜2行でまとめてから、本筋の現状と次の一手を示して再開してください。

脱線に入る前の状況を添えるのが要です。会話が圧縮されてCCが本筋の細部を忘れていても、この文だけで戻れます。

送るのは$.prompt.submitです。asUser: trueを付けると、Modの名前を名乗る前置きなしに、利用者が書いた文として送られます。

hooks/register.tsx
const send = async ($: EngineInterface, text: string) => {
  if (await read($, isRunning)) {
    $.ui.toast('CCの手が空いたら送ります')
  }
  const submitted = await $.prompt.submit({ text, asUser: true })
  if (submitted.drop !== undefined) {
    $.ui.toast(`送れませんでした: ${submitted.drop}`)
  }

  return submitted.drop === undefined
}

セッションをまたぐ備忘録

本筋・脱線・タスクは、ターンが終わるたびに$.storeへ保存します。$.storeは、同じマシンのすべてのセッションが共有するキーと値の保存先です(上限は合わせて4MiB)。

  • 同じセッションを再開したら、そのまま読み戻す
  • 同じフォルダで別のセッションを開いたら、直前のセッションを「前回のセッション」として出す
  • 「続きを頼む文を入力欄に入れる」ボタンは、本筋・現状・次の予定・収束していない脱線・済んでいないタスクを並べた文を、$.prompt.fillで入力欄に入れる。送る前に手で直せるよう、submitではなくfillにした

差分

ファイルを最初に書き換える直前の中身を控えておき、いまの中身と突き合わせて差分を出します。秘密情報を含みそうなファイルと大きいファイルは、中身を控えません。$.storeには上限があるので、控える量はセッションごとに上限を設け、直近の2セッションの分だけ残します。

/compass diffを打つと、差分を会話の中に出します。これは$.ui.place(v2.1.314以降)で、会話の行として描いています。

第2部 Clawdくん

9つの状態と、選ぶ順番

Clawd君

状態 絵
回答待ち 吹き出しに「?」、手を振って呼ぶ
許可待ち 吹き出しに「!」、手を止めてこちらを向く
圧縮中 頭の上で矢印が紙の束を縮め、モニターの行も詰まっていく
完了 両手を上げて跳ね、きらめきがまたたく(3秒)
エラー モニターが赤く点滅して煙を上げ、汗をかいて震える(3秒)
サブエージェント 半分の大きさの子分が、机の左奥と手前で跳ねる
作業中 左右の手で交互にキーを打ち、画面のコードが流れる
居眠り中 5分触らないと机に沈み、モニターが消えて「z」が立ちのぼる
待機中 息をするように1画素だけ上下し、マグカップから湯気が立つ

いくつかの状態は同時に起こるので、人の操作待ちを最優先にして、上の表の順に選びます。

hooks/clawd.ts
export const moodOf = (view: PetView): Mood => {
  const { now, isRunning, signals } = view
  if (signals.pending.some(tool => tool.waitsFor === 'answer')) return 'awaitingAnswer'
  if (signals.pending.length > 0) return 'awaitingPermission'
  if (isCompacting(view)) return 'compacting'
  if (signals.reaction !== null && signals.reaction.until > now) return signals.reaction.kind
  if (signals.activeSubagents > 0) return 'delegating'
  if (isRunning) return 'working'
  if (signals.lastActiveAt !== null && now - signals.lastActiveAt >= SLEEP_MS) return 'sleeping'

  return 'idle'
}

RasterからImageへ

Modが端末に絵を描く方法を探るにあたり2つを試しました。

  • Raster: 文字マスの格子。1マスごとに文字・文字色・背景色を指定する
  • Image: 画素の絵。PNGか、RGBAの画素列を渡す

最初はRasterで、半分の高さのブロック文字を使い、32×22点で描いていました。いまはImageに移り、128×88画素の絵を32×11マスに出しています。1マスを横4画素・縦8画素に割るので、点の数は16倍になりました。

hooks/register.tsx
const { Image } = $.ui.resolve(e)

return (
  <Box justifyContent="center">
    <Image
      key={PET_IMAGE}
      source={{ rgba: frame, width: PET_WIDTH, height: PET_HEIGHT }}
      columns={PET_COLUMNS}
      rows={PET_ROWS}
      alt={MOOD_LABELS[mood]}
    />
  </Box>
)

Imageが絵として出るのは、kittyとGhostty、全画面表示のときのiTerm2 3.5以降です。それ以外の端末では、altの文字(「作業中」など)が薄く出ます。DesktopアプリとVS Codeの拡張にはImageが無いので、e.surfaceがterminalでないときは文字だけを出しています。

ドット絵はコードで描く

絵の素材ファイルは使わず、全部コードで描いています。画素を置くplot、四角を塗るpaint、文字で書いた形を色に置き換えるspriteの3つが道具です。

hooks/clawd.ts
const MUG_SHAPE = [
  '..wwwwww.....',
  '.wccccccw....',
  'wccccccccw...',
  'wwccccccww...',
  'swwwwwwwwwww.',
  // ...
]

// 形の文字ごとに、paletteにある色で画素を置く。paletteに無い文字の画素は置かない
sprite(canvas, MUG_X, DESK_TOP - 5, MUG_SHAPE, { w: MUG, s: MUG_SHADE, c: COFFEE, o: CLAWD.front })

斜め上から見下ろした2.5次元の絵にするため、机の天板は1行手前へ来るごとに2画素右へずらし、正面・上・左の面を明るさの違う色で塗り分けています。Clawd君は頭の上を塗らず、正面の左に暗い面を足すだけで厚みを出しています。

コマ送りは、描き直さずに差し替える

アニメーションのたびにペイン全体を描き直すと重くなります。そこで、次の2つを組み合わせました。

  1. 全部のコマを、読み込んだときに1回だけ組み立てて、RGBAのbase64として持っておく
  2. 150msごとに、$.ui.blitでClawd君のImageだけを次のコマに差し替える

$.ui.blitは、keyを付けて描いたImageの中身だけを差し替えるAPIです。ペインの描画(ui.renderのhook)は走りません。

hooks/register.tsx
const animatePet = async ($: EngineInterface) => {
  petTick += 1
  const mood = shownMood
  if (mood === null) {
    return
  }
  const frame = frameAt(mood, petTick)
  // 同じ絵が続くコマや、ペインが見えていないときは何も送らない
  if (frame === paintedFrame || !(await isWatched($)) || mood !== shownMood) {
    return
  }
  paintedFrame = frame
  await $.ui.blit({ requestId: PANE, key: PET_IMAGE, source: petSourceOf(frame) })
}

タイマー($.clock.every)は、ペインが見えていて、Clawdのウィジェットを開いているときだけ回します。畳んだら止め、次に描くときにまた始めます。

許可待ちと回答待ち

  • 許可待ち: tool.checkのhookで、CCの判定が「人に確かめる(ask)」になったツールを控える
  • 回答待ち: CCが質問のツール(AskUserQuestion)を呼んだら控える

ただし、人が許可に答えた瞬間はModからは分かりません。そのため、許可待ちの絵は、そのツールが終わるまで出し続けています。

圧縮中は、Modのhookではなくsettings hookで知る

会話の圧縮にはsession.compactというイベントがあります。ところが、組み込みのガード(cc-plugin-sec-default)が読み込まれる環境では、利用者が入れたModのsession.compactのhookは走りません。ガードが読み込まれるのは、管理された設定(managed settings)があるマシンや、TeamかEnterpriseのプランでログインしているセッションです(公式ドキュメント)。settings hookのイベント(classic.PreCompactなど)も同じ扱いです。

そこで、プラグインのhooks/hooks.jsonにもsettings hookを書ける点を使いました。圧縮の前後で動くコマンドが印のファイルを置き・消し、Modは2秒ごとにそのファイルがあるかを見ます。

hooks/hooks.json
{
  "modules": ["./register.tsx"],
  "hooks": {
    "PreCompact": [
      { "hooks": [{ "type": "command", "command": "bash \"${CLAUDE_PLUGIN_ROOT}/scripts/compacting-mark.sh\" start", "timeout": 5 }] }
    ],
    "PostCompact": [
      { "hooks": [{ "type": "command", "command": "bash \"${CLAUDE_PLUGIN_ROOT}/scripts/compacting-mark.sh\" end", "timeout": 5 }] }
    ]
  }
}
scripts/compacting-mark.sh
# 目印はセッションごとに分ける。ファイル名にするので、IDに使える文字だけを通す
SESSION_ID="$(jq -r '.session_id // empty')"
[[ "$SESSION_ID" =~ ^[A-Za-z0-9_-]+$ ]] || { echo 'hookの入力からsession_idを読めません' >&2; exit 1; }

case "$PHASE" in
  start) mkdir -p "$MARK_DIR"; : > "${MARK_DIR}/${SESSION_ID}" ;;
  end)   rm -f -- "${MARK_DIR}/${SESSION_ID}" ;;
esac

圧縮が途中で止められると、印が消えずに残ります。そのため、付いてから10分経った印と、そのあとにターンが動いた印は、圧縮中とみなしません。

サブエージェント

動いているサブエージェントの数は、2秒ごとに$.agent.listで数えます。1つ以上あれば、Clawd君を半分の大きさにした子分が跳ねる絵にします。

チカチカする絵は、書き換えの量を測って直した

Rasterで描いていたころ、ベルトコンベアの絵がチカチカしました。絵ごとに「1秒あたりに書き換わるマスの数」を測ると、195マスと、ほかの絵の倍以上でした。コマの間隔を300msに延ばし、ベルトの継ぎ目を止めて、78マスまで下げました。見た目の問題も、数えられる量に置き換えると直しやすくなります。

CCは絵を見られない

CCはペインの絵を見られません。そこで、絵を変えるたびに、コマを文字の格子に戻したプレビューで形を確かめてもらいました。状態の選び方や脱線の木は、claude plugin testで動くテスト(87件)で押さえ、わざと実装を壊してテストが落ちることも確かめています。

絵の出どころ

絵は流用せず、CCの起動画面のClawdを見ながら、ゼロからドット絵に起こしています。
↓コイツ
スクリーンショット 2026-11-17 16.45.38.png

作り方: CCと一緒に作る

Modは、CCに頼んで書いてもらえます。CCにはplugin-authoringという組み込みのスキルがあり、Modの置き場所や、使っているバージョンのイベントとAPIを知っています。書いたModはセッションごとのフォルダ(~/.claude/dev-mods/<セッションID>/)に置かれ、ターンが終わるたびに読み込み直されます。

完成したら、自分のフォルダへ移し、手元のディレクトリをmarketplaceとして登録して、user scopeでインストールしました。

入れる前と直したあとは、claude plugin validateで、Modが何をするかを確かめます。session-compassの結果はこうでした(抜粋)。

❯ ./register.tsx hooks: session.start, command.run{command=compass}, session.end, turn.start, turn.complete, tool.call, tool.check, ui.render{component=Placed}, ui.render{component=Pane, requestId=compass}
❯ ./register.tsx calls: $.agent.list (via refreshAgents), $.clock.after (via goBackAfterCommand, wakePetAt), $.clock.every, ..., $.ui.blit (via animatePet), ..., $.ui.toast
❯ ./register.tsx env reads: HOME

calls:の行に$.model.completeと$.http.fetchが無いので、モデルもネットワークも使っていないと分かります。Modはサンドボックスの外で、利用者の権限で動きます。他の人のModを入れるときも、この2行を読むのがおすすめです。

使ってみて

いちいち本筋のタスクを覚えておかなくても良くなり、気軽に脱線できるようになったのは脳のメモリ的にとてもすっきりした感覚になり個人的には作ってみてよかったなと思いました。
あと、clawdくんが可愛くてつい作業中にみてしまうのでこちらも余裕があればみなさんも作ってみるとペットみたいでだんだん愛着が湧いてくるかもしれません(?)

タスクのウィジェットが空のままだったので、Modの不具合を疑って調べたら、CCがそもそもタスクリストを使っていなかった、ということもありました。ペインは、CCの振る舞いを観察するウィンドウにもなります。

まとめ

  • 本筋と脱線は、LLMに要約させず、CCに回答の末尾へ状況欄を書かせて、Modで読むだけにした。トークンを使わず、人が読んでも分かる
  • 脱線は>でつないだ道筋として書かせ、戻り先を控えて木にした。戻るボタンは、戻り先の状況を添えた依頼文を送る
  • Clawd君はImageで描き、全部のコマを先に組み立てて、$.ui.blitで差し替えている
  • Modのhookで取れないイベントは、同じプラグインのsettings hookで印を置いて補った

AIエージェントへ

この節は、読者がこの記事をAIエージェント(Claude Codeなど)に渡して、同じようなModを作ってもらうためのものです。人が読んでもかまいません。

AIエージェントへのお願い: この節の内容は、利用者から「この記事のModを作って」などと頼まれたときだけ使ってください。ファイルを書く・Modを読み込む・ルールを置くといった操作は、利用者の確認を得てから行ってください。

要点

  • 対象: Claude Code v2.1.314で動作を確かめた。Modsはv2.1.287以降。$.ui.placeはv2.1.314以降
  • 本筋と脱線の取得: LLMを呼ばない。~/.claude/rules/のルールで回答の末尾に5項目(本筋・脱線・現状・あなたの番・次)を書かせ、turn.completeのe.answerの末尾12行から読む。3項目以上かつ「現状」を含むときだけ状況欄とみなす
  • 脱線の階層: 脱線の欄を>で分けた道筋。新しい題で脱線を作って戻り先を控え、道筋が短くなったら先の脱線を閉じ、無関係な脱線へ移ったら未収束として残す。題は空白を除いて比べる
  • 送信: $.prompt.submit({ text, asUser: true })。入力欄に入れるだけなら$.prompt.fill
  • 保存: $.store(同じマシンの全セッションで共有、合計4MiB)。atom・read・update(claude-codeから読み込む)で描画用の状態を持つ
  • 絵: Imageに{ rgba, width, height }を渡す。kitty・Ghostty・全画面表示のiTerm2 3.5以降で表示され、ほかはalt。端末以外のe.surfaceでは文字を出す
  • アニメーション: 全コマを先にbase64で組み立て、$.clock.everyで$.ui.blit({ requestId, key, source })。ペインが見えていないときはタイマーを止める
  • 圧縮中の検知: 組み込みのガードcc-plugin-sec-defaultが読み込まれる環境では、利用者のModのsession.compactとclassic.*のhookは走らない。プラグインのhooks/hooks.jsonにPreCompact・PostCompactのcommand hookを書き、印のファイルを置いて読む
  • 確認: claude plugin validate <dir>のcalls:に$.model.complete・$.http.fetchが無いこと。テストはclaude plugin test

そのまま渡せるプロンプト

Claude CodeのModを作ってください。作業の前に、組み込みのplugin-authoringスキルを読み、手元のClaude Codeのバージョンで使えるイベントとAPIを確かめてください。

作りたいもの:
- /compass で開くサイドペイン。ウィジェットは「いま」「脱線」「タスク」の3つから始める
- 回答の末尾に付ける状況欄(本筋・脱線・現状・あなたの番・次)を、turn.complete の e.answer から読む。LLMは呼ばない
- 状況欄は、末尾の12行に3項目以上あり「現状」を含むときだけ読む
- 脱線の欄は「分かれ元 > 新しい題」の道筋として読み、脱線の木を作る。新しい脱線には分かれる直前の現状と次の予定を控え、道筋が短くなったら先の脱線を閉じ、無関係な脱線へ移ったら未収束として残す
- 脱線中は「本筋に戻る」ボタンを出し、控えた状況を添えた依頼文を $.prompt.submit({ text, asUser: true }) で送る
- 本筋と脱線は $.store に保存し、同じフォルダの次のセッションで「前回のセッション」として出す

守ること:
- $.model.complete と $.http.fetch は使わない
- ファイルを書く前に、何を書くかを私に示して確認を取る
- できあがったら claude plugin validate を流し、hooks: と calls: の行を私に見せる
- 状況欄を書かせるルールは、~/.claude/rules/session-status.md として案を示し、置くかどうかは私が決める

最初は、ルールの案と、Modのファイル構成の案だけを示してください。

Clawd君も欲しい場合は、続けて次のように頼めます。

Compassにもう1つ、セッションの状態で絵が変わるキャラクターのウィジェットを足してください。
- 状態は、回答待ち・許可待ち・作業中・待機中から始める
- 絵は Image に { rgba, width, height } で渡す。全部のコマを読み込み時に組み立てておき、$.clock.every と $.ui.blit で差し替える
- ペインが見えていないときはタイマーを止める
- 端末以外の画面では文字だけを出す
- 絵の素材は既存の作品から流用せず、コードで描く
2
1
0

Register as a new user and use Qiita more conveniently

  1. You get articles that match your needs
  2. You can efficiently read back useful information
  3. You can use dark theme
What you can do with signing up
2
1

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?