claude-canvas解説｜Obsidian CanvasをClaude Codeで自動生成する仕組みと導入の罠

Obsidian Canvasは、ノートや画像を無限平面に並べられる機能だが、実際に使うと「並べる作業」そのものが重い。カードを1枚ずつ置き、幅を揃え、線を引き、はみ出したら全部ずらす——この手作業がボトルネックになる。claude-canvas（AgriciDaniel製・MITライセンス）は、その配置作業ごとClaude Codeに任せてしまおうという発想のプラグインだ。/canvas generate "サイバーパンクゲームのムードボード" のような一文から、テンプレート選択・内容生成・座標計算・検証までを一気に走らせて .canvas ファイルを吐き出す。

Claude Code側のプラグイン機構そのもの（インストール、CLAUDE.md、Hooks、スキルの読み込まれ方）を先に押さえておくと、この記事の内容は格段に読みやすくなる。全体像は Claude Code｜2026年版・インストールからCLAUDE.md・Hooks・本番運用までの実装手引き にまとめてある。

claude-canvasとは — Obsidian Canvasを描かせるClaude Codeプラグイン

claude-canvasは、Claudeを「クリエイティブディレクター」に見立てる。ユーザーは完成イメージを言葉で指示し、Claudeが構成・内容・配置を決めて .canvas ファイルとして書き出す。READMEはこの役割分担を明示しており、リポジトリの構造もそれに沿っている。

構成要素はおおよそ次の4層に分かれる。

・コマンド層：commands/canvas.md が /canvas の入口。サブコマンドを対応するスキルへ振り分ける
・スキル層：skills/ 配下に8個のSKILL.md。オーケストレーター1個（canvas）＋サブスキル7個（create / populate / layout / present / generate / template / export）
・エージェント層：agents/ に3個。レイアウト担当・メディア担当・文章担当（composer）
・スクリプト層：scripts/ にPython製CLI。座標計算（canvas_layout.py）・テンプレート展開（canvas_template.py）・検証（canvas_validate.py）

ここが設計上の要点で、座標計算と検証をLLMに任せず、決定論的なPythonスクリプトに降ろしている。レイアウトは数値計算なのでモデルに解かせると崩れやすい。スクリプトへ逃がしたぶん、LLMは「何を書くか」に集中できる。

ファイルはどこに置かれるのか

claude code obsidian 連携ツールを試すとき、いちばん最初に気になるのが「生成物がどこに落ちるか」だ。claude-canvasはSKILL.mdで「Vaultを認識するが、Vaultに依存はしない」という方針を明示していて、判定は2段階になっている。

・カレントディレクトリか親に wiki/canvases/ があれば、そこを使う（同じ作者の claude-obsidian というVault構成を想定したモード）。画像などのメディアは _attachments/images/canvas/ へ
・無ければ、カレントディレクトリに .canvases/ を作って使う（単独モード）。メディアは .canvases/assets/ へ

既定のキャンバスは main.canvas で、ディレクトリが無ければ作成する。Obsidian Vaultの外でも動く設計なので、まず適当な作業ディレクトリで試してからVaultへ持ち込む、という進め方ができる。逆に言えば、Vault内で実行したつもりが親に wiki/canvases/ が無く、意図しない場所に .canvases/ ができることもある。

スキル定義そのものの仕組み（SKILL.mdのフロントマター、description によるトリガー、フォルダ単位の管理）については Claude Skillsとは｜「スキル=フォルダ」の仕組みと作り方・使い方を徹底解説 が詳しい。claude-canvasのSKILL.mdも同じ仕様に沿っている。

/canvas のサブコマンド

READMEとオーケストレーターのSKILL.mdには、次のような対応表が置かれている（抜粋）。

READMEのインストールコマンドは通らない — 実際に導入できる手順

ここが本記事でいちばん実用的な部分になる。READMEに載っている導入コマンドは2つとも、そのままでは動かない。

理由は2つある。いずれもリポジトリの構成とCLIの仕様を見れば確認できる。

① claude plugin install AgriciDaniel/claude-canvas が失敗する
install はプラグイン名を、登録済みのmarketplaceに対して解決する。ところがこのリポジトリの .claude-plugin/ に入っているのは plugin.json だけで、marketplace.json が存在しない。リポジトリのファイル一覧を取ると .claude-plugin/plugin.json の1件しか返らない。名前を引く先が無いので解決できない。

② claude plugin add ~/Desktop/claude-canvas が失敗する
add というサブコマンドが存在しない。手元のClaude Code 2.1.211で claude plugin --help を叩くと、並ぶのは details / disable / enable / eval / init / install / list / marketplace / prune などで、add は無い。

この2点は2026年4月17日にissue #1として報告され、別のユーザー2名が追認のコメントを残している（うち1名は回避手順が機能したと報告）。2026年7月25日時点で作者からの返信もREADMEの修正も確認できない。

回避手順：ローカルにラッパーmarketplaceを作る

issue #1で共有されている回避策は、自分のマシンに「このリポジトリを指すだけのmarketplace」を1つ作ってしまう方法だ。以下は同issueで示された手順に沿ったもの。

# 1) ローカルにラッパーmarketplaceを作る
mkdir -p ~/.claude/local-marketplaces/canvas-wrapper/.claude-plugin
cat > ~/.claude/local-marketplaces/canvas-wrapper/.claude-plugin/marketplace.json <<'JSON'
{
  "name": "canvas-wrapper",
  "owner": {"name": "local"},
  "plugins": [{
    "name": "claude-canvas",
    "source": {"source": "github", "repo": "AgriciDaniel/claude-canvas", "ref": "main"},
    "version": "1.0.0"
  }]
}
JSON

# 2) marketplaceとして登録し、そこからインストールする
claude plugin marketplace add ~/.claude/local-marketplaces/canvas-wrapper
claude plugin install claude-canvas@canvas-wrapper

導入前に「自分が踏むかどうか」を確かめたいなら、リポジトリ側の状態は次のコマンドで直接見られる。ネットワーク越しの確認だけで済み、インストールは不要だ。

# marketplace.json があるか（.claude-plugin/plugin.json だけならREADME手順は通らない）
curl -s "https://api.github.com/repos/AgriciDaniel/claude-canvas/git/trees/main?recursive=1" \
  | python3 -c "import json,sys; print([f['path'] for f in json.load(sys.stdin)['tree'] if 'claude-plugin' in f['path']])"

# 手元のCLIに add サブコマンドが存在するか
claude plugin --help | grep -E '^\s+(add|install|marketplace)' || echo "add は存在しない"

12テンプレートと6レイアウトアルゴリズム — 何が自動化されるのか

claude-canvasの中身で最も作り込まれているのが、テンプレートとレイアウトだ。templates/ には12個のJSONファイルが実際に置かれている。

レイアウト側は scripts/canvas_layout.py（約25KB）に実装があり、リファレンスには各アルゴリズムのパラメータまで書かれている。

数値も具体的だ。放射状レイアウトはリング半径を 300px × リング番号 で決め、角度は 2π ÷ ノード数 で等分する。力学モデルはFruchterman-Reingold法で、最適間隔 k = √(面積 ÷ ノード数)、反発力 k² ÷ 距離、引力 距離² ÷ k、温度は1反復ごとに5%冷却し、100反復でおおむね安定するとされる。

auto の判定ルールも明示されている。

・ファイルノードが6割超かつエッジが少ない → grid（ギャラリー的）
・エッジが0本 → grid（関係の情報が無いため）
・1つのノードが全接続の4割超を持つ → radial（ハブ＆スポーク）
・入力エッジを持たないノードがあり階層が明確 → dagre
・エッジ密度がノード数を超える → force
・いずれにも当てはまらない → dagre

/canvas generate のパイプライン

主力コマンド /canvas generate は、説明文1つから7段階の処理を回す設計になっている。

注目すべきは最後の品質ゲートだ。SKILL.mdは「検証を通過してもプレースホルダーが残っていれば失敗とみなす」と明記し、Describe this / YYYY-MM-DD / Content goes here / Value: 0 といった禁止文字列を名指しで列挙している。テンプレートを展開しただけで満足せず、中身を書き切るまでを1タスクとして定義しているわけだ。加えてノード間の最小間隔（横80px・縦60px）や、マインドマップなら放射状・ナレッジグラフなら力学モデルを適用したかの確認まで手順化されている。

Obsidian Canvasの座標系とJSON Canvas 1.0 — 生成物が壊れない条件

claude-canvasが吐くのは独自形式ではなく、Obsidianチームが策定したJSON Canvas 1.0というオープン仕様のファイルだ。最小構成は nodes と edges の2キーだけで、あとはノードの種類（テキスト／ファイル／リンク／グループ）と座標が並ぶ。

生成物が壊れないために、リファレンスは3つの制約を置いている。

・Zオーダーは配列順：配列の先頭が最背面、末尾が最前面。したがってグループ（ゾーン）は中身のノードより前に置く必要がある。逆にすると背景がコンテンツを覆い隠す
・座標は20pxグリッドにスナップ：x・y・幅・高さをすべて20の倍数に丸める。Obsidian側の見た目が揃う
・ノード数の上限：100個で警告、200個でエラー。無限平面とはいえ描画負荷は有限

IDの衝突対策も決められていて、[種別]-[内容スラッグ]-[10桁のUNIX時刻] という命名にし、バッチ処理での衝突を避けるため秒精度のタイムスタンプをフルで使う。既存IDと衝突した場合は -2 -3 と連番を足す。

こうした制約を人手で守り続けるのは面倒なので、検証はスクリプトに任せる形になっている。

# 生成・編集した .canvas を検証する（重なり・ID重複・グリッドずれ等）
python3 scripts/canvas_validate.py path/to/main.canvas

# レイアウトだけを後からかけ直す（例: 階層レイアウト）
python3 scripts/canvas_layout.py path/to/main.canvas dagre

なお hooks/hooks.json にはPostToolUseフックが登録されており、Write/Editのあとに「.canvas を書いたなら検証を走らせよ」とClaudeに促す仕組みになっている。ただしこのフックには後述の癖がある。

ノードを1枚足すときの座標決定

「既存のキャンバスに画像を1枚足す」という操作は、一見単純だが座標を決める必要がある。オーケストレーターのSKILL.mdには、この自動配置のロジックがPython関数として直接書き込まれている。挙動はゾーン（グループノード）を基準にした次の手順だ。

・追加先のゾーンが無ければ、既存ノード全体の最下端から60px下に置く
・ゾーンがあり、まだ空なら、ゾーン左上から20pxずらした位置に置く
・すでにノードがあるなら、最下段の行を特定し、その右端から40px右に置く
・右にはみ出す場合は、最下段の下20pxへ改行して新しい行を始める
・最後に必ず20pxグリッドへ丸める

「最下段の行だけを見て、その行の上端に高さを揃える」という点が地味に効いている。全ノードの平均や最大で揃えると、行ごとに高さが違うキャンバスで段がずれるためだ。この程度の処理をLLMに毎回考えさせず、決め打ちの手続きとして書いてあるところに、このClaude Code プラグインの設計思想が出ている。

パフォーマンス面の指針も別リファレンスにまとまっており、GIFは1キャンバスあたり3枚まで・幅480px以内、SVGは viewBox 必須（Obsidian上では <img> として描画されるため対話性は無い）といった実務的な制約が並ぶ。

ソースを読んで分かる4つの既知バグと影響範囲

導入の可否を判断するうえで、公開されているissueと実際のソースを突き合わせておく価値がある。以下はリポジトリのコードとテンプレートJSONを読んで確認できた内容で、いずれも対応するissueが立っている。1件目は前章で扱ったインストールの問題で、残る3件をこの章で見ていく。

SCRIPT_DIR 未定義が最も分かりやすい。canvas_template.py は244行目で layout_script = SCRIPT_DIR / "canvas_layout.py" を参照するが、このファイル内で SCRIPT_DIR はどこにも代入されていない。定義されているのは37行目の TEMPLATES_DIR = Path(__file__).parent.parent / "templates" だけだ。作者の意図はおそらく Path(__file__).parent だが、その行が抜けている。

影響範囲は限定できる。この行に到達するのは、テンプレート側が post_layout を持つ場合のみだからだ。12個のテンプレートJSONを確認すると、post_layout を持つのは3つだった。

・flowchart（post_layout: dagre）
・mind-map（post_layout: radial）
・knowledge-graph（post_layout: force）

残る9種（presentation / gallery / dashboard / storyboard / mood-board / timeline / comparison / kanban / project-brief）は post_layout を持たないため、この分岐に入らない。issue #5がタイトルでflowchartとmind-mapを名指ししているのは、この構造と一致する。

ナレッジグラフの崩れも構造から説明がつく。templates/knowledge-graph.json は post_layout に force を指定しているが、edge_templates が空配列で、エッジを1本も生成しない。力学モデルは「接続されたノードが引き合い、すべてのノードが反発する」計算なので、エッジが0本なら引力が働かず反発だけが残る。ノードが際限なく散る結果になる。

# 手元のクローンで上記2点を確認する
grep -n "SCRIPT_DIR" scripts/canvas_template.py     # 244行目の参照のみで、代入行は無い
python3 -c "import json; d=json.load(open('templates/knowledge-graph.json')); \
  print('post_layout=', d.get('post_layout'), '/ edge_templates=', len(d['edge_templates']))"

フックの発火範囲については、hooks/hooks.json の matcher が "Write|Edit" になっている。.canvas に絞る条件はmatcher側に無く、「もし .canvas を書いたなら検証せよ」という条件分岐はプロンプト本文に書かれている。つまりファイル種別に関係なくWrite/Editのたびにフックが発火し、そのつどClaudeが判断する形になる。issue #2と#8が別々に同じ症状を報告しているのは、この設計に起因する。気になる場合は、インストール後に該当プラグインのフック定義を無効化するか、matcherを自分で絞り込むのが現実的だ。

kepano版・Claudianとの違い — どれを選ぶか

ObsidianとAIエージェントをつなぐOSSは複数あり、役割が紛らわしい。層が違うものを比べても仕方がないので、「何をする道具か」で並べてみる。

いちばん混同されやすいのがkepano版との関係だ。kepano版の json-canvas スキルはAIエージェントに「Canvasというファイル形式の読み書き」を教えるもので、claude-canvasはその上に生産パイプラインを載せるものだ。競合というより層が違う。kepano版はObsidian CEO自身が公開しスター数も桁が違うため、まず土台としてこちらを押さえるのが順当で、詳細は Obsidian Skills とは・使い方｜kepano製Agent SkillsでObsidianをAIエージェント化 にまとめている。

Claudianは方向が別で、Obsidian側にClaude Code／Codexを埋め込み、Vaultをそのままエージェントの作業ディレクトリにする。「AIをどこで動かすか」の話であり、「Canvasをどう生成するか」ではない。こちらは Claudian完全ガイド｜ObsidianでClaude Code・Codexを動かす — インストールと使い方 で扱っている。

前提条件と依存関係

導入前に把握しておくべき依存は次のとおり。

・Obsidian v1.1以降（Canvas対応版）。閲覧・編集に必須
・Advanced Canvasプラグイン：プレゼン機能とエクスポートには推奨とされる。1200×675のスライドグループとエッジによるページ送りはこのプラグイン前提
・Python 3.10以降：レイアウトと検証スクリプトの実行に必要
・任意の連携スキル：/banana（画像生成）・/svg（図表生成）・claude-gif-*（GIF）・mcpvault（Vaultのノート読み取り）。SKILL.mdは未導入時に機能を落として動作すると記載している

つまり画像生成を伴う /canvas generate を額面どおり動かすには、別の画像生成スキルが手元に入っている必要がある。この前提はREADMEのデモ画像からは読み取りにくいので、注意しておきたい。

まとめ — 設計は面白いが、導入は自己責任の色が濃い

Obsidian Canvasを手で並べる作業が重いという課題は本物で、それを自動化しようという着眼も正しい。ただし現状のclaude-canvasは、動くプロダクトというより「よくできた設計図と、その部分実装」として読むのが実態に近い。150というスター数は、READMEの完成度とスクリーンショットの質に対して付いたものだろう。実際に使うなら、上のラッパーmarketplace手順で入れたうえで、post_layout を持つ3つのテンプレートは避けるか、SCRIPT_DIR を自分で1行足してから使うことになる。MITライセンスなので、フォークして直すことにも制約はない。

参照ソース

・AgriciDaniel/claude-canvas（公式リポジトリ・README・SKILL.md・templates） — 機能一覧・12テンプレート・6レイアウトアルゴリズム・品質ゲートの定義。canvas_template.py と templates/*.json は既知バグの確認元
・issue #1 — README install commands fail: no marketplace manifest and plugin add doesn’t exist — 導入コマンドが通らない事象の報告と、ラッパーmarketplaceによる回避手順
・issue #5 — canvas_template.py: NameError ‘SCRIPT_DIR’ — post_layout を持つテンプレートで発生する例外の報告
・JSON Canvas — an open file format for infinite canvas data — Obsidianチームが策定したCanvasファイル形式の一次仕様