Claude mod で Claude Code に Clawd を住まわせた

Claude Code の mod（関数フックのプラグイン）を使って、作業中のプロンプトの上で Clawd がうろうろする mod「clawd-wander」を作った。
clawd-wander は、自分用の mod をまとめて置くリポジトリ claude-mods に入れている。

この記事では、何を作ったか、Claude Code の mod とは何か、mod で何ができそうかをまとめる。

Claude Code の mod とは

mod は、Claude Code の中に TypeScript のコードを差し込んで、画面や振る舞いを変えるプラグインのこと。
settings.json に書く従来の hooks（主にシェルコマンドを起動するフック）と違い、Claude Code の中で関数として動く。

1 つの mod は、次の 3 ファイルでできている。

<mod>/
├── .claude-plugin/plugin.json   # 名前・バージョン・説明
└── hooks/
    ├── hooks.json               # {"modules": ["./register.ts"]}
    └── register.ts              # フック本体

フック本体は on(イベント, フック) でフックを足していく形で書く。

import type { Register } from 'claude-code';

export const register: Register = (on) => {
  on('tool.call', async ($, e, next) => {
    const result = await next(e); // ほかのプラグインと Claude Code 本来の処理を進める
    if (result.isError === true) $.ui.toast(`${e.tool} が失敗した`);
    return result;
  });
};

• $ は Claude Code 側の機能の入り口。$.ui（描画）、$.clock（タイマー）、$.agent（サブエージェント）のように「名詞.動詞」で呼ぶ
• e はイベントの入力。tool.call なら呼ばれたツール名や引数が入っている
• next(e) で後続の処理を進める。呼ばずに返せば処理を横取りでき、next({ ...e, ... }) で入力を書き換えることもできる

型定義は Claude Code が mod のフォルダに書き出してくれるので、tsc -p <mod> で型チェックできる。
claude plugin validate で読み込めるかの検査、claude plugin test でテストの実行まで揃っている。

mod の API は早期公開の段階で、リリースごとに変わる。本記事の内容は Claude Code 2.1.292 時点で確認したもの。
clawd-wander は 2.1.287 以降のターミナルで動く。

mod の置き場 claude-mods

claude-mods は、手元で使う mod を集めて置くリポジトリ。名前は似ているが、Claude Code の機能名ではない。いまは clawd-wander の 1 つだけが入っている。リポジトリ自体がマーケットプレイス local-mods になっていて、mod を 1 つずつフォルダで持つ。

claude-mods/
├── .claude-plugin/marketplace.json   # マーケットプレイス local-mods の定義
└── clawd-wander/                     # 今回作った mod

手元のフォルダをマーケットプレイスとして登録すると、インストール後もそのフォルダを直接読む。
mod を編集したら、各セッションで /reload-plugins を実行すれば反映される。

claude plugin marketplace add ~/git/private/claude-mods
claude plugin install clawd-wander@local-mods --scope user

clawd-wander でできること

Claude が作業している間だけ、プロンプトのすぐ上の帯に Clawd が現れてうろうろする。作業が終わると消える。

状況	マスコットの反応
Claude が作業中	Clawd が帯の中を行ったり来たりする
サブエージェントが起動	1 体ごとに仲間が増える（おばけ・ロボット・宇宙人・キノコ・恐竜・ネコ）
編集・調査・新規作成	編集中はハンマー、調べ物中は虫めがね、新しく書くときは鉛筆を持つ
サブエージェントを呼ぶ	旗を持つ
テストを走らせる	フラスコを持つ
ツールが失敗した	赤い「!」を出して驚く
手が止まった	小さく丸まって居眠りする
作業が終わった	ぴょんと跳ねてから、ふわっと消える
ときどき	仲間が Clawd のあとを一列についていく（カルガモ行列）

仕組み

使っているイベントは 3 つだけ。

イベント	やっていること
ui.render	プロンプト上の帯（AbovePrompt）に、マスコットを描く Raster を 1 つ置く
agent.spawn	サブエージェントが起動したら仲間を 1 体増やす
tool.call	呼び出し元のマスコットに、ツールに合った道具を持たせる。失敗したら驚かせる

描画は $.clock.every で 100 ms ごとにコマを進め、$.ui.blit で Raster の中身だけを書き換えている。
帯ごと描き直さないので、ほかの表示を巻き込まずにアニメーションできる。

マスコットの絵は、1 文字を横 2 × 縦 2 のドットとみなし、象限ブロック文字（▘ ▝ ▛ █ など）で描いている。
半文字単位で位置をずらせるので、1 ドットずつ滑らかに歩ける。

mod の可能性

clawd-wander は見た目を変えるだけの mod だが、mod の API はもっと広い。
Claude Code に同梱の mod 作成スキル（plugin-authoring）が挙げている「頼まれたら何を使うか」は次のとおり。

やりたいこと	使うもの
横に開くペイン・パネル	$.ui.open と ui.render（Pane）
プロンプト上の帯	ui.render（AbovePrompt）
ステータスライン・トースト	$.ui.status / $.ui.toast
ツール呼び出しを止める・書き換える・反応する	tool.call
送ったプロンプトを書き換える	prompt.submit
システムプロンプトを足す・差し替える	prompt.compose
音を鳴らす	$.audio.play
スラッシュコマンドを足す	$.command.register と command.run
タイマー・モデル呼び出し・ファイル・プロセス	$.clock / $.model / $.fs / $.process など

ここから考えると、たとえば次のような mod が作れそうだ（どれもアイデアで、まだ作っていない）。

• ガードレール: tool.call で git push --force や terraform apply を止める。コマンドを起動せず、判定ロジックを TypeScript で書ける
• 作業の見える化: サブエージェントの一覧や、いま何を読んでいるかをペインに出し続ける
• 完了通知: 長い作業が終わったら音を鳴らす。ターンの完了は turn.complete で受け取れる
• プロンプトの下ごしらえ: 社内の略語を、送る前に正式名称へ展開する
• チーム用のスラッシュコマンド: よく使う手順をコマンドにし、マーケットプレイス経由で配る

hooks や MCP サーバーが「外から Claude Code に働きかける」ものだとすると、mod は「Claude Code の内側に手を入れる」もの。
ターミナルだけでなく、デスクトップアプリや VS Code にも描画先がある。
画面・入力・ツール呼び出しのすべてに手が届くので、自分の使い方に合わせて Claude Code そのものを作り変えられる。

まとめ

• Claude Code の mod は、TypeScript の関数フックで画面や振る舞いを変えるプラグイン
• 今回作ったのは、作業中に Clawd がうろうろする mod「clawd-wander」
• clawd-wander は、自分用の mod を集めたリポジトリ claude-mods に置いている。リポジトリはそのままマーケットプレイスとして使える
• mod はガードレール・可視化・通知・コマンド追加まで手が届く。Claude Code を「使う」から「育てる」へ広げられる

clawd-wander のソースは takiguchi-yu/claude-mods の clawd-wander/ にある。