English | 日本語 · README · ドキュメント一覧
NeedMarkは画面へのコメントをいつもの修正作業につなげます。UIを選び、コメントと対象情報、任意の画像を保存し、AIにローカルファイルを確認させ、最後に自分で結果を確かめます。MITライセンスで、アカウント、MCPサーバー、特定のエージェントSDKは必須ではありません。操作UIはReactに依存せず、ホスト型サービスNeedBackには接続しません。
Node.js 22.12以降と、npm・Yarn・pnpmのいずれかを使います。アプリケーションのプロジェクトにNeedMarkを導入します。
pnpm add -D needmark # npm install -D needmark / yarn add -D needmark
pnpm exec needmark init
pnpm dev # いつもの開発コマンドこのガイドのCLIコマンドはpnpmで記載しています。npmではnpx needmark、Yarn（classic・Plug'n'Play）ではyarn needmarkに読み替えてください（例: npx needmark init）。初期設定の案内とAIへの指示には、プロジェクトのロックファイルに合ったコマンドが入ります（パッケージマネージャー）。
ターミナルでの初期設定は英語で表示します。最初に推奨設定（レビュー画面はターミナルの言語、コメントはこのコンピューターだけに保存、スクリーンショットはページを描き直して作成、プロジェクトを認識できた場合は開発サーバーへの接続）を示し、そのまま使うかを尋ねます。nと答えると、各項目を説明付きの番号から選べます。フラグで指定した項目は尋ねません。非対話実行ではすべての選択肢をフラグで指定します。ターミナルがない場合、--connect=yesを指定しない限りプロジェクトのファイルは変更しません。
pnpm exec needmark init --share=local --capture=dom --language=ja --connect=yes初期設定はneedmark.config.tsと用途に応じたGitの除外ルールを作成し、既存ルールを残します。既存の設定は上書きしません。設定があるプロジェクトで再実行すると、initはその設定を残し、開発サーバーへの接続だけを提案します。旧プロジェクトとの互換性は移行を参照してください。インストールだけではアプリやAIは起動しません。
default exportは信頼できるローカルのTypeScript設定で、CLIと各アダプターが共有します。
import type { NeedMarkOptions } from 'needmark';
export default {
language: 'ja',
capture: 'dom',
outputDir: '.needmark/feedback',
} satisfies NeedMarkOptions;| オプション | 動作 |
|---|---|
enabled |
falseにすると、この設定を使う全員のNeedMarkを止めます。NeedMarkを止めるを参照してください。 |
origins |
Viteで許可する完全一致のオリジン配列。任意。スキームとポートを含め、ワイルドカードやパスは使えません。省略するとlocalhost、127.0.0.1、[::1]をポートを問わず許可するので、Viteが別のポートで起動しても動作します。--hostで公開したLANのアドレス、トンネル、独自のローカルドメインなど別のホスト名でレビューする場合だけ指定します。指定した配列はループバックの既定値を置き換えます。プロキシの待ち受け先は指定しません。 |
language |
'en'または'ja'。UIの初期値は'ja'。明示した値はCLIの指示文の言語にも使われます。 |
capture |
'dom'、'tab'、'none'。初期値は'dom'。 |
outputDir |
publicの外にあるコメント専用フォルダー。新規プロジェクトの既定値は.needmark/feedback。Viteはそのroot、プロキシはプロジェクトrootから解決します。 |
editor |
任意の'vscode'または'cursor'。検証済みのローカルソース位置へのリンク。対応アプリとプロトコルハンドラーが必要です。 |
contextAttributes |
対象情報とプロキシのソース照合に使う、安全な小文字HTML属性名を最大6個指定。例: ['data-feature', 'data-ticket']。 |
onFeedbackChange |
APIの保存完了後に実行する任意のNodeコールバック。失敗はログに残し、保存を失敗にしません。CLI・Git・直接編集では呼びません。 |
onSubmit |
任意のNodeコールバック。{ feedback, prompt, directory, detail, language? }を受け取り完了を待ちます。設定するとウィジェットに送信操作が現れます。 |
CLIと引数なしのneedmark()は現在のプロジェクトディレクトリからだけ設定を読み込み、不正な設定では起動を停止します。変更は次のCLI実行かプロキシ再起動で反映されます。needmark.config.tsやViteのプラグイン設定を変更した場合は開発サーバーを再起動してください。コメントファイルを設定としてimportすることはありません。
有効なブラウザの言語設定がlanguageより優先されます。レビュー設定から変更でき、保存範囲はオリジンごとです。NeedMarkの操作ラベルとUIのコピー・送信で作る指示文は選択中の言語を使います。CLIのexportは明示した設定言語を使い、未指定なら英語です。既存のフォーマッター直接呼び出しも既定では英語を維持します。
コメント、返信、取得したページのテキスト、既存のコメントは入力どおりに残ります。技術メタデータ、JSONキー、識別子、コマンド名は英語のままです。外部ライブラリーやブラウザのエラーは元の言語で表示される場合があり、すべてのメッセージの翻訳を保証する設定ではありません。
同意すると、initはいつもの開発コマンドでツールバーが出るようにNeedMarkをつなぎます。変更するのは開発用の設定だけで、アプリのソースと本番ビルドには触れず、変更した行を表示します。
| プロジェクト | initが変更するもの |
|---|---|
vite.config.*（React、Vue、SvelteなどのViteプロジェクト） |
import { needmark } from 'needmark'を追加し、pluginsの先頭にneedmark()を入れる |
astro.config.* |
importを追加し、vite.pluginsにneedmark()を入れる。必要ならvite: { plugins: [...] }を作る |
next devを実行するdevスクリプト |
先頭にneedmark dev --を付ける。Next.jsなどの開発サーバーを参照 |
変更はプロジェクトと一緒にコミットされるため、開発サーバーを起動する全員にツールバーが表示されます。initが読めるのは、defineConfig({...})、素のオブジェクト、名前付きの定数、オブジェクトを返す関数で書かれた設定です。それ以外の形には手を付けず、下の手動の手順を表示します。あとからpnpm exec needmark init --connect=yesでつなぐこともできます。pnpm exec needmark removeは接続で追加したものだけを取り除き、needmark.config.tsと保存済みのコメントは残します。
NEEDMARK=off（0、false、noも可）を付けて開発サーバーを起動すると、自分だけNeedMarkなしで動きます。NEEDMARK=onなら、設定で止めていても自分だけ有効にできます。needmark.config.tsのenabled: falseは全員分を止めます。止めている間、Viteプラグインは何も追加せず、needmark dev -- <コマンド>はいつものポートでコマンドを実行するだけです。
手動でつなぐ場合は、既存のVite設定にプラグインを追加します。pre順序でJSXをコンパイルするプラグインより前に置いてください。
import { defineConfig } from 'vite';
import { needmark } from 'needmark';
export default defineConfig({
plugins: [needmark()],
});引数なしの場合、開発サーバーの起動時に現在のディレクトリのneedmark.config.tsを読み込みます。CLIと同じファイルです。needmark(settings)やneedmark({ outputDir: 'reviews' })のように設定を渡すと、その設定だけを使い、ファイルは読みません。
通常のVite開発コマンドを実行し、localhost、127.0.0.1、[::1]または指定したオリジンで開きます。プラグインはViteのHTML変換を使い、その変換を通らずにフレームワークが描画したHTMLにはウィジェットを末尾に追記します。開発serve時だけ動作します。vite previewと本番ビルドには入りません。ローカルの.jsx・.tsxのネイティブタグと入口HTMLにソース情報を付けますが、他のテンプレート、SSR、生成ソースを一律には対応付けません。ウィジェットは最上位の文書だけに表示されます。同一オリジンでアクセスできる子ページは親から選べ、直接開くと専用ツールバーが表示されます。
AstroはViteで動くため、viteオプションに同じプラグインを追加し、いつもどおりastro devを実行します。
// astro.config.mjs
import { defineConfig } from 'astro/config';
import { needmark } from 'needmark';
export default defineConfig({
vite: { plugins: [needmark()] },
});AstroはViteのHTML変換を通さずにページを描画するため、プラグインは各HTMLレスポンスの末尾にウィジェットのscriptを追記します。.astroテンプレートにはソース位置を付けず、コメントにはDOMの情報とファイルの手掛かりを残します。
package.jsonの開発コマンドの前にneedmark dev --を付けます。initがNeedMarkをNext.jsにつなぐときと同じ形です。
"scripts": { "dev": "needmark dev -- next dev" }これでpnpm devを実行すると、いつも開くポートでツールバー付きのアプリが表示されます。ポートは、コマンドに-p・--portで指定した値（コマンドからは取り除きます）、なければPORT、なければ3000です。--の前に--portを付けて指定することもできます。NeedMarkがhttp://localhost:<ポート>で待ち受け、空いているポートをPORTに入れてコマンドを起動するため、サーバーはPORTを読む必要があります。Next.jsや多くのNodeサーバーは読みます。Ctrl+Cで両方を止め、コマンドの終了コードを引き継ぎます。
PORTを読まないサーバーは、いつもどおり起動してから、隣でプロキシを起動します。
pnpm exec needmark dev --target=http://localhost:3000 --origin=http://localhost:4190レビュー先のhttp://localhost:4190を開きます。対象は必須で、レビュー先の既定値はこのURLです。両者はlocalhost、127.0.0.1、[::1]の異なる完全一致のループバックHTTPオリジンが必要で、レビュー先にはポートも必要です。既存CSP、アプリ内の絶対URL、フレームワークのオリジン検証はそのまま適用され、通常の開発設定の調整が必要な場合があります。アプリのimportや本番ビルドは変更しません。Ctrl+Cで停止します。
コマンドは言語、撮影、保存先、エディター、追加属性、コールバックを共有設定から読み込みます。--capture=dom|tab|noneと--directoryで設定を上書きできますが、撮影方法はブラウザ設定が引き続き優先です。コードから使う場合、needmark/proxyのstartReviewProxyに必須のtarget・origin、任意のroot（既定は現在のディレクトリ）と共通オプションを渡し、close()で停止できるレビューサーバーを取得します。ソース検索には対応するReact開発メタデータ、ローカルソースマップ、現在のローカルJSX識別子が必要です。利用できなくてもDOM情報とファイル検索の手掛かりは使えます。
ツールバーは画面下部の中央に表示され、持ち手やボタンを含むツールバーのどこからでもドラッグして移動できます。右端のNeedMarkロゴのボタンでたたむと、そのボタンだけを残して小さくなります。もう一度押すとツールが戻ります。たたんでいる間もショートカットは使えます。ボタンにポインターを重ねるかフォーカスすると、名前・できること・ショートカットが表示されます。パネルはヘッダーをドラッグして移動できます。ヘッダーはスクロールしても上部に固定され、移動したパネルは閉じるまでその位置に留まります。
| ボタン | 目的 |
|---|---|
| コメント（＋アイコン） | 画面の場所を選んでコメントを残す。NeedMarkの基本の道具です。 |
| ピンの表示 | 保存したコメントのピンを表示・非表示にする。 |
| 一時停止 | アニメーション・動画・タイマーを止める。カルーセルや動く要素の、ある瞬間をコメントするときに使います。停止中はボタンが再生アイコンに変わります。 |
| コメント一覧 | コメントの確認・返信・解決と、AIへの受け渡し。一覧と設定は、それぞれのボタンの上に中央揃えで開きます。 |
| 設定 | 言語・撮影方式・投稿者（設定した場合だけ表示）・AIへの情報量など。撮影方式とAIへの情報量は、ラベル横の i アイコンにポインターを重ねると説明が表示されます。 |
「コメント」は1つの道具で、操作の仕方によって選ぶ対象が変わります。選択中はツールバーの中身が1行の案内、この節へ移動する ? リンク、選択を終える × ボタン（Escでも可）に入れ替わり、終了するとアイコンに戻ります。狭い画面でもツールバーが読めるよう、下の操作一覧はツールバーではなくこのガイドに載せています。
| 操作 | 選ぶもの |
|---|---|
| クリック | 要素 |
| ドラッグ | 自由な範囲（ホイールでスクロールするか、ウィンドウの端にポインターを寄せると、見えている画面の外まで広げられる） |
| Shift＋クリック・ドラッグ | 複数の要素（以降はクリックで追加・解除、Enterで完了、Backspaceで最後を戻す） |
| Ctrl/Cmd＋クリック | 重なりの下にある要素 |
| Alt/Option＋ドラッグ | 文字の一部（誤字や文言のコメント） |
複数選択はShift＋クリックかShift＋ドラッグで始まります。以降はShiftなしのクリックで追加・解除でき、ツールバーには件数と 選択を完了 が表示されます。
クリック前にポインターを重ねると、対象の枠・タグ・取得できる名前と、ローカルのメタデータで分かるコンポーネントを確認できます。ポインターを動かさずにCtrl/Cmdを押す・離すだけでも、重なりの下の対象のプレビューに切り替わります。名前は探索範囲を限定したラベル・文字・IDからの手掛かりで、完全なアクセシブルネームの計算ではありません。フォームの値は読み取らず、ソース検索のリクエストも送りません。監視しているページ・ルートの変化、スクロール、サイズ変更、新しい選択操作でプレビューを消し、保存画像にも操作UIと一緒に含めません。プレビューの動作と制約（英語）も参照してください。
- Ctrl/Cmd＋クリックで、最前面とは独立した下の対象を探します。空のコンテナーや非表示の要素が複数重なっていても、内容や操作部品を優先します。空の視覚要素だけの場合は表示領域が最小の対象を選びます。最前面のopen Shadow DOMやアクセス可能な同一オリジンiframeの内側を優先し、次に外側の対象を探します。下の対象がなければ最前面を選び、アプリのオーバーレイは隠しません。修飾キーを離しても完了せず、Enterか完了ボタンで終了します。
- 複数選択では、選んだ各要素に対象情報と番号付きの枠が付きます。Escapeはまず進行中のドラッグだけを取り消して以前の選択を残し、次に選択を終了します。範囲検索が上限に達した場合は不完全である旨を表示し、クリックや追加ドラッグで対象を増やせます。
コメントのパネルには撮影画像があり、その下のコメント欄の上で カテゴリ を選べます。修正（既定）、相談、質問 の3つです。修正はAIにコードの変更を依頼します。相談と質問は回答を求めるもので、AIへの指示ではコメントに返信で答え、コードは変更しないよう伝えます。カテゴリはcomment.mdとAIへの指示に入り、相談と質問は一覧にタグとして表示します。
保存（コメント欄でCtrl/Cmd+Enter）を押すと、一覧を開かずにすぐ次の対象を選べる状態に戻ります。やめるときはEscか終了ボタンを押し、一覧はツールバーから開きます。コメントの入力中は、選んだ対象に点線の枠が表示されます。ページをスクロールすると枠は消えます。撮影画像は見出しとコメント欄の間に表示し（クリックで拡大）、AIに渡すソースの場所はフォームの下に折りたたんだ1行で表示します。
コメント を押すとすぐに選択を始めます。needmark.config.tsと 設定 で保存した値を使います。複数人で同じファイルをレビューする場合は、設定 で投稿者名を入力してください。
| キー | 動作 |
|---|---|
| Shift+C、Ctrl/Cmd+Shift+F | 選択の開始・終了 |
| Shift+P | アニメーションの一時停止・再開 |
| Shift+H | ツールバーとピンの表示・非表示 |
| Ctrl/Cmd+Enter | コメント・編集・返信を保存 |
| Enter / Backspace | 複数選択の完了 / 最後の選択を戻す |
| Esc | 進行中の操作やパネルを閉じる |
入力欄やIMEの変換中はページ全体のショートカットは動きません。設定の キーボードショートカット で無効にできます。ピンは未対応のコメントだけに表示します。
以前の版でコメントなしで保存した対象の参照も読み込めます。専用の表示で区別し、検索、ピン、対象の表示、解決、返信を利用できます。新しい参照はウィジェットからは作りません。
| 方法 | 選択と制約 |
|---|---|
dom |
共有許可は不要。同一オリジンでアクセス可能なiframeを含む現在のDOMを描画します。非対応CSS、動画、クロスオリジン内容は実際の表示と異なる場合があります。 |
tab |
現在のタブの共有許可が必要。ウィンドウ・画面共有は拒否し、取得したストリームは停止かページ終了まで再利用します。ブラウザが検証できない場合は自分で現在のタブを選びます。 |
none |
コメントと対象情報を画像なしで保存。撮影に失敗した場合もこの方法に切り替わり、入力した文章を保ったまま通常どおり保存できます。 |
保存画像ではパスワード欄とdata-needmark-redact領域をマスクし、旧data-needback-redactも認識します。クロスオリジンiframeやclosed Shadow DOMの内部を隠す場合はiframeやホスト自体を指定してください。ブラウザのライブ共有ストリームはマスクしません。撮影中の対象、ルート、ビューポート・iframeの形状、秘匿領域の変化で撮影を拒否する場合があります。採用した画像は取得時の形状情報と一緒に保存します。音声・動画の録画はしません。画像は拡大・移動できるビューアーで確認できます。完全な安定性・描画上の制約は撮影の詳細（英語）を参照してください。
コメントごとのUUIDフォルダーにcomment.md、context.json、任意のscreenshot.pngを保存します。新規プロジェクトは.needmark/feedback、デモはdemo/.needmark/feedbackを使います。ステータスの正本はJSONです。対象の参照にはintent: "reference"と空のコメントを記録します。参照を追加する前に共有先の読み取り側も更新してください。旧版のNeedMarkは空のコメントを拒否し、コメントと参照が混在する一覧を読めない場合があります。操作中でないUIはCLI・Gitの変更を反映し、編集中の内容を捨てません。
一覧のヘッダーには プロンプトをコピー（コピーのアイコン）・検索・絞り込み・⋮ のアイコンがあります。検索を押すとヘッダー全体が キーワード検索 の入力欄になり（コピーのアイコンは横に残ります）、Escか閉じるボタンで検索を解除します。絞り込みのメニューでは このページのみ（ピンと同じページ。localhostと127.0.0.1のどちらで開いても同じ）と 解決済みも表示 を組み合わせて選べます。既定では解決済みを表示しません。⋮ メニューの すべて解決済みにする と すべて削除 は、一覧に表示中の項目が対象です。削除は同じパネルの中で確認してから実行し、一部の失敗も報告します。プロンプトをコピー は表示中の未対応の修正依頼をコピーします（件数はツールチップに表示し、コピーすると少しの間、成功色のチェックに変わります）。詳細からは1件だけコピーできます。カードには投稿者（未設定ならゲスト）を1行で、投稿からの時間、詳細と同じくコメントの上にカテゴリのタグ、コメントの先頭2行と、コメントしたページのパスを表示します。投稿者の横のチェックアイコンで解決済みにしたり未対応に戻したりできます。一覧で解決済みにした項目は、一覧を開き直すまで表示したままにします。カードを押すと詳細が開きます。別のページのカードは、そのページへ移動してから詳細と対象を表示します。compact・standard・detailed・forensicで含める情報量を選び、既定はstandardです。完全な根拠はファイルに残ります。検証済みの位置、親の手掛かり、ファイル候補は区別されるため、現在のコードと画像を照合してください。コピーするとボタンが少しの間、成功色のチェックに変わります。クリップボードが使えない場合はトーストで知らせ、画面内の手動コピー欄を使えます。通知は常に画面下部中央のトーストで表示し、削除や返信の保存などUIで分かる結果は通知しません。
pnpm exec needmark list
pnpm exec needmark export --detail compact
pnpm exec needmark watch
pnpm exec needmark reply <id> '余白を調整し、チェックが通りました。' --author Codex # 省略時はAgent
# ユーザーが結果を確認した後:
pnpm exec needmark resolve <id>
pnpm exec needmark reopen <id>いつものAIにプロジェクトと保存画像へのアクセスを渡します。画像の理解には画像対応のAIが必要です。コメントとDOMの文章はレビュー資料として扱い、実行しないでください。AIは変更と検証を返信で報告し、人が確認するまで未対応のまま残します。詳細を開くと、ページ上の対象がすぐに枠で示されます。ヘッダーには戻るボタン、VS Codeで開く のアイコン（エディターを設定している場合。Cursorも可）、プロンプトをコピー のコピーアイコン（解決済みの項目でも使えます。コピーすると少しの間、成功色のチェックに変わります）、解決にする のチェックアイコン（解決済みになると成功色の塗りつぶしに変わり、もう一度押すと未解決に戻る）、閉じるボタンが並ぶため、ページ上で修正を確かめてそのまま承認できます。撮影画像の上には投稿者名と投稿からの時間（「2日前」「たった今」など）、編集・削除 を開く ⋮ メニューがあります。撮影画像の下にカテゴリのタグ（変更は 編集 から）とコメントがあります。コメントと返信ではMarkdown（太字、斜体、コード、リスト、引用、見出し、リンク）が使え、Webのリンクは新しいタブで開きます。返信は投稿者名と投稿からの時間つきで並びます。編集 を選ぶとコメントや返信がその場で編集フォームに変わるため、パネルのほかの部分は動きません。下部の返信欄は1行から始まり、入力に合わせて伸び（上限を超えると欄の中でスクロール）、矢印のボタンかCtrl/Cmd+Enterで送信します。返信はどれも ⋮ メニューから編集・削除できます。コメントと返信は誰でも編集・削除でき、返信を編集しても投稿者名は元のまま残ります。送信 で返信を残せます。参照とresolvedは修正用の指示と送信から除外します。参照だけを選んだ場合、修正コマンドや根拠ファイルへのパスを含まない中立な文章を出力します。UI・CLIには編集、返信、削除もあります。
CLIの保存操作は設定のoutputDirを使います。保存先を明示すると設定の読み込みを省略します。list・export・watchの後、ステータス・編集・削除のIDの後、または返信の--directoryで指定できます。ソースチェックアウトではビルド後にnode dist/cli.js ...を使います。watchはCLI・Git・直接編集の変更を監視します。任意の送信操作はonSubmitの完了を待ちますが、AIの起動、画像バイトのアップロード、コメントの消去、解決はしません。受け手にはローカル画像へのアクセスが必要です。失敗、配信、再試行の制約はコールバックの動作（英語）を参照してください。
MCPに対応したAIエージェント（Claude Code、Codex、Gemini CLIなど）は、needmark mcpを通じてコメントを直接読み書きできます。追加のサーバーやアカウントは不要で、ネットワークのポートも開きません。プロジェクトのフォルダーで登録します。
# Claude Code
claude mcp add needmark -- pnpm exec needmark mcp
# Codex
codex mcp add needmark -- pnpm exec needmark mcpAIからは次のツールを使えます。
| ツール | 内容 |
|---|---|
needmark_list_feedback |
未対応（既定）などのコメント一覧 |
needmark_get_feedback |
コメントの全情報とスクリーンショット画像 |
needmark_reply |
返信する（質問への回答、作業報告） |
needmark_resolve |
要約を返信に残して解決済みにする（人の確認後） |
needmark_watch |
新しいコメントが来るまで待って、まとめて受け取る |
needmark_export_prompt |
AI向けの修正指示文を作る |
画像はファイルパスではなく画像そのものとして渡るため、画像に対応したAIならコメントした画面を直接確認できます。
ハンズフリー運用：AIに次のように伝えると、ブラウザでコメントするたびにAIが拾って対応します。
needmark_watch をループで呼んでください。届いたコメントごとに needmark_get_feedback で内容と画像を確認し、
修正して、検証結果を needmark_reply で報告してください。
質問のコメントには返信で答え、解決済みにするのは私が確認してからにしてください。「止めて」と言うまで続けてください。
詳しい動作はMCPサーバー（英語）を参照してください。
--share=localはコメントをGitから除外し、--share=gitは用途に応じた除外ルールでコメントフォルダーだけを共有対象にします。ファイルにはページ内容や画像が含まれるため、通常のコミットで何を含めるか判断してください。CLIはcommit・push、コメント内容の実行、別のチェックアウトへのリアルタイム送信をしません。
CLIと引数なしのneedmark()は、needmark.config.tsがない場合だけneedback.config.tsを読みます。新設定が不正なら旧設定へ戻らず停止します。outputDir未指定時は.needmark/feedbackがない場合だけ既存の.needback/feedbackを使います。両方あれば新保存先が優先で、選択時にコメントの統合・移動・削除はしません。
initはどちらかの設定名が存在すると停止します。旧バージョンのコメントフォルダーだけがある場合は保存先を引き継ぎ、除外ルールもそこを対象にします。ブラウザの設定とツールバー位置はneedmark-*キーを優先し、新キーが未設定の場合だけneedback-kit-*を読みます。新しい保存は新キーを使い、旧キーを削除しません。旧コマンド名・パッケージ名の別名は提供しません。
API・保存境界、ソース検証、iframeの対象同定、アニメーション一時停止、検証範囲はアーキテクチャリファレンス（英語）を参照してください。