kongyo-yome-preview

Kongyo Yome Preview

@kongyo2/yome (github.com/kongyo2/yome) は .md をブラウザで開き保存ごとにライブリロードする CLI。Claude が作った / 編集した md をユーザーに提示するときは、会話への貼り付けではなく yome 起動で「URL を渡す」のが第一選択。

いつ使うか

• ユーザーが「md 見せて」「プレビュー」「ブラウザで開いて」「yome で」と言った
• Claude が長文の md (設計書、調査メモ、レポート、議事録、TODO リスト) を作って、ターミナル貼り付けでは見づらいとき
• 連続して md を編集する流れで、保存ごとの反映をユーザーに確認させたいとき
• Mermaid / KaTeX / GitHub Alerts など、生 md では読みにくいリッチ要素を含むとき

使わない場面:

• 数行で済む短いメモ / コードスニペット (会話に直接書く)
• .html, .txt, .json など md 以外 (yome は md 専用)
• ユーザーが「プレビュー要らない」と明示
• ヘッドレス / CI / リモートシェルなどブラウザが開けない環境

クイックスタート (最短成功パス)

ad-hoc に 1 ファイルだけ見せる デフォルト はこれ。yome は per-port の session を JSON で永続化するので、無印で起動すると同じ port で前に開いた md がタブに復活する。--no-restore-session を付けると 読まず・書かず の完全 ephemeral になる。

npx -y @kongyo2/yome@latest "<absolute-md-path>" --no-restore-session

成功時 stdout に http://localhost:6275 系の行が出るので、ユーザーには URL を 1 行で渡す:

ブラウザで http://localhost:6275/ を開いてください。保存するたびに自動でリロードされます。

yome は起動するとデーモン化して親プロセスがすぐ exit するので、Bash tool の run_in_background: true は 推奨だが必須ではない。ただし --foreground を付けたとき、もしくは npx 初回ダウンロードで時間がかかる場合のために bg にしておくのが安全。

必要入力 / 前提環境

入力	必須	不足時の扱い
表示する md の絶対パス	必須	Glob/Bash で確定する。曖昧ならユーザーに確認
target (グループ名)	任意	既定 default。複数 md を 1 つのサーバーで分けたい時だけ指定
port	任意	既定 6275。競合時だけ --port 6276 などに変える
Node.js >= 20.10.0	必須	node --version で確認。不足ならユーザーに更新を案内
ローカルにブラウザがある	必須	リモート/ヘッドレスでは「いつ使うか」の対象外

Decision Table

状況	次の操作
デフォルト: ad-hoc に 1 ファイル見せて忘れる	npx -y @kongyo2/yome@latest "<file>" --no-restore-session
連続編集を session に残し再起動でも復元したい	--no-restore-session を 外して 通常起動 (+ --target <name> で名前分け)
既存サーバー有無を確認	npx -y @kongyo2/yome@latest --status (orphan backup も surface される)
複数 md を 1 サーバーで別タブにしたい	--target spec / --target log でグループを分ける
既に session が汚れていてリセットしたい	npx -y @kongyo2/yome@latest --clear --port <n> --yes (--yes で確認プロンプトを抜ける。--shutdown だけでは backup は残る)
動的に生成した md (一度きり)	<some-cmd> | npx -y @kongyo2/yome@latest --no-restore-session
ポート競合 (EADDRINUSE)	--port 6276 等に変える
ファイルを 1 つだけタブから外す	--close "<file>"
自動オープンが鬱陶しい (2 回目以降)	--no-open を追加
過去に残った orphan backup を探す	--status で (saved session backup only) 表示行を探し、--clear --port <n> で削除

コピペ資産

起動 (Bash tool 側で run_in_background: true を推奨)

# 単一ファイル ad-hoc (推奨デフォルト)
npx -y @kongyo2/yome@latest "<absolute-md-path>" --no-restore-session

# session を残す通常起動 (連続編集向け、target で名前分け推奨)
npx -y @kongyo2/yome@latest "<file>" --target spec

# 複数ファイル + グループ
npx -y @kongyo2/yome@latest "<file1.md>" "<file2.md>" --target spec --no-restore-session

# ディレクトリ再帰 watch (session 必須なので no-restore は付けない)
npx -y @kongyo2/yome@latest -w -R "<dir>" --target watch

# stdin から (一度きりレンダリング)
<command-producing-md> | npx -y @kongyo2/yome@latest --no-restore-session

# ポート/バインド指定 (既定 localhost:6275 は変えなくてよい)
npx -y @kongyo2/yome@latest "<file>" --port 6276 --bind 127.0.0.1 --no-restore-session

サーバー操作

npx -y @kongyo2/yome@latest --status              # 起動中 + orphan backup を一覧
npx -y @kongyo2/yome@latest --status --json       # スクリプトで処理する場合
npx -y @kongyo2/yome@latest --shutdown            # 全停止 (backup は残る — 仕様)
npx -y @kongyo2/yome@latest --shutdown --port 6275  # 1 port だけ停止
npx -y @kongyo2/yome@latest --clear --port 6275 --yes  # session backup ごと完全削除 (--yes で確認を skip)
npx -y @kongyo2/yome@latest --restart             # 状態を保ったまま再起動
npx -y @kongyo2/yome@latest --close "<file>"      # グループから 1 ファイルだけ外す
npx -y @kongyo2/yome@latest --unwatch "<glob>"    # watch パターン解除