obelisk

Obelisk

Obsidian 用のインラインコメントと GitHub 形式の変更提案です。

文章を選択してコメントを残し、必要に応じてワンクリックで適用できる置き換え案を提案できます。コメントはノート自体のフロントマターに保存されるため、同期、git、エクスポート、名前変更を行ってもファイルとともに保持されます。

オベリスク（†）は、古代の編集者が写本の余白に描き、この箇所には異論があることを示した記号です。

ステータス

開発初期段階です。アンカリング、装飾、サイドバー、変更提案、エージェント連携を実装済みです。このプラグインは Obsidian コミュニティプラグインディレクトリで公開されており、CLI と MCP サーバーは obelisk-mcp として npm で公開されています。大規模な保管庫での動作確認はまだ行っていません。

インストール

設定 → コミュニティプラグイン → 閲覧で Obelisk を検索し、インストールして有効化してください。アップデートも同じパネルから行えます。

ディレクトリの掲載ページにあるObsidian に追加ボタンからも、プラグインを追加できます。

機能

• あらゆる箇所にコメントできます。 テキストを選択して右クリックし、コメントを追加します。
• どこでも Markdown を使えます。 コメントと返信は通常の Markdown で、入力中は「編集」と「プレビュー」を切り替えられます。リンク、リスト、コールアウト、埋め込み、数式は、ノートと同じようにサイドバーに表示されます。
• 編集案を提案できます。 提案は GitHub と同じように、コメント内に記述するフェンス付きの ```suggestion ブロックです。引用箇所との差分と「適用」ボタンが表示されるため、ひとつのコメントで説明と変更案を提示でき、返信で別の案を提案することもできます。元のテキストが変更されている場合、適用は拒否されます。適用するとコメントも解決済みになります。編集案で質問に答えられていない場合に備えて、再開もできます。
• サイドバー。 ノート内のコメントを文書の順序で表示するほか、並べ替えの切り替えで新しい順に表示できます。コメントをクリックすると、エディターが該当箇所までスクロールします。チップで未解決コメント、提案を含むコメント、または特定エージェントのレビューを絞り込めます。解決済みコメントも非表示にせず、グレー表示でリストに残ります。ノート内では引き続きハイライトされるためです。
• テキスト内のハイライト。 コメントが付いた箇所はハイライトされ、†マーカーをクリックするとサイドバーでコメントが開きます。
• フロントマターに保存されます。 obelisk キーの下に通常の YAML として保存されます。読みやすく、差分を確認でき、移植も可能です。
• 編集後も維持されます。 コメントは引用したテキストにアンカーされるため、Obsidian の外で行った編集も含め、ノートのほかの箇所を編集しても追従します。引用箇所自体を編集または削除するとコメントは切り離され、サイドバーにフラグが表示されます。何もハイライトされなくなりますが、別の箇所に移動したり、削除されたりすることはありません。テキストを元に戻すと再び紐づきます。解決済みコメントは通常、求めていた編集が行われたときに切り離されるため、フラグの対象外です。
• いつものエディターを使えます。 コメントは Obsidian 独自の Markdown エディターで記述するため、Cmd+B、リストの継続、[[ の自動補完、ライブプレビューを、ノートと同じようにコメント内で使えます。
• スレッド形式の返信。 コメントに返信でき、返信はコメントと一緒に保存されます。すべて Markdown で記述できます。
• 編集できます。 カードの 編集 ボタンを使うか、該当箇所を右クリックすると、コメントや返信を、提案ボタンも含め、最初に書いたときと同じ入力欄で書き直せます。編集した本文にはその旨が表示されます。アンカーはそのままなので、コメントの内容を変更しても、何についてのコメントかは変わりません。
• 削除できます。 カードの 削除 からコメント全体を、または返信のヘッダーにあるゴミ箱アイコンから返信ひとつを削除できます。スレッドのひとつの発言を削除しても、会話全体は削除されません。どちらも確認ダイアログではなく、取り消し操作が提示されます。
• エージェントから利用できます。 コマンドラインツールと MCP サーバーを使うと、Obsidian の外から同じコメントを読み書きできるため、モデルがノートをレビューしてサイドバーにコメントを追加したり、残されたコメントに返信したりできます。モデルのコメントにはバッジが付き、レビュー一回分はヘッダーのひとつのチップにまとめられ、チップから すべて非表示 にできます。詳しくは以下をご覧ください。

データ形式

---
obelisk:
  - id: cq7fk2m9x
    author: zach
    created: 2026-08-29T14:02:11.000Z
    body: |-
      This paragraph does two things at once.

      ```suggestion
      The horse bolted.
      ```
    anchor:
      from: { line: 12, col: 0 }
      to: { line: 12, col: 47 }
      quote: The horse, which had been standing there, bolted.
---

コメントは Markdown のひとまとまりです。編集案は、コメント内のフェンス付き ```suggestion ブロックとして記述します。その内容は適用時にアンカーされた範囲を正確に置き換えるため、ひとつのコメントに文章、リンク、編集案をまとめて含められます。

コメントのアンカーとなるのは quote です。行と列の範囲には、コメントを書いた時点での箇所が記録されます。サイドバーの順序を決め、引用文が複数回出現する場合の判定に使われます。この範囲が書き換えられることはありません。行数はフロントマターブロックの次の行から数えるため、コメントを追加してもほかのコメントが無効になることはありません。

モデルが書いたコメントには、追加で origin キーがあり、モデルと、そのレビューで作成されたすべてのコメントに共通する ID が記録されます。このキーがないコメントは人が書いたものです。そのため、すでにボルトに保存されているデータを移行する必要はありません。

エージェント

Obsidian の外から、同じコメントを利用できます。モデルがノートをレビューすると、その指摘が、すでに開いているノートのサイドバーに表示されます。また、依頼するコメントを残すと、モデルがそれを読み、編集を行ってコメントを解決します。

npm install -g obelisk-mcp            # puts `obelisk` and `obelisk-mcp` on PATH

obelisk list note.md
obelisk comment note.md --quote "The horse, which had been standing there, bolted." \
  --body "Two clauses fighting over one sentence." --run r7k2mq

MCP を話すエージェントでは、サーバーを登録してください。

claude mcp add obelisk --scope user -- npx -y obelisk-mcp

登録はすべての保管庫に適用されます。ツールはエージェントが実行されている保管庫で動作し、絶対パスを指定すれば、別の保管庫にあるノートにもアクセスできます。公式 MCP レジストリからインストールするクライアント向けに、サーバーは io.github.zachhannum/obelisk として登録されています。

エージェントがサーバーを起動します。 stdio 経由で MCP を話します。セッション開始時にエージェントがプロセスを起動し、セッション終了時に終了させるため、ポートもデーモンも必要ありません。セッションごとにプロセスを一つ使うことで、そのセッションのコメントにサイドバーで同じ実行チップが表示されます。セッションでは起動したプロセスが維持されるため、新しいバージョンのパッケージが使われるのは次のセッションからです。すぐに切り替えるには、/mcp から再接続してください。

登録を確認するには、claude mcp list を実行するか、セッション内で /mcp を実行してください。エージェントを介さずにサーバー自体を確認するには、次を実行します。

printf '%s\n' \
  '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"smoke","version":"0"}}}' \
  '{"jsonrpc":"2.0","method":"notifications/initialized"}' \
  '{"jsonrpc":"2.0","id":2,"method":"tools/list"}' \
  | npx -y obelisk-mcp

ハンドシェイクの後、4 つのツールが表示されます。ここでサーバーが失敗する場合、エージェントでも同じように失敗します。

MCP を話さないエージェントでは、docs/agents-fragment.md を保管庫の AGENTS.md または CLAUDE.md に貼り付けてください。

覚えておくべきルールは一つです。引用文がアンカーです。 行番号はアンカーになりません。モデルに行番号を尋ねると、もっともらしい誤った番号が返されることがあります。エラーに見えないままコメントが別の段落に付いてしまうため、--near-line は引用文が同一の場合の選択にのみ使い、obelisk list からコピーした番号を指定してください。--quote はノート内に一字一句違わず記載されている必要があります。記載がない場合や、2 回以上記載されている場合は、何も書き込まれず、その理由が表示されます。obelisk list は本文に番号を付けて表示するため、正確なテキストをコピーできます。

書き込みはフロントマターのみを対象とし、本文のバイト列はそのまま維持されるため、Obsidian でノートを開いている間も安全です。また、書き込み前にファイルを再読み込みし、途中で変更されていた場合は処理を拒否します。

開発

npm install
npm run dev      # watch build, plugin only
npm run build    # typecheck, then main.js plus dist/cli.mjs and dist/mcp.mjs

src/core/ は Obsidian をインポートしない部分で、モデル、アンカーの計算、YAML、4 つの動詞が含まれています。プラグイン、CLI、MCP サーバーは、これを使う 3 つのフロントエンドです。

site/ はドキュメントサイトです。独立した Astro プロジェクトであり、独自に npm install を実行します。npm run build の対象には含まれません。

テスト用の保管庫にリポジトリをシンボリックリンクして、試してください。

ln -s "$PWD" /path/to/vault/.obsidian/plugins/obelisk

ライセンス

MIT