KAIRAN

Claude Code / Codex などの agent が生成した markdown / HTML を、tool call ひとつでブラウザに表示するローカル MCP サーバー。

• 何個の agent から接続されても、表示サーバーは 1 つ・port は 1 つ（初回 tool call で自動起動、全員がいなくなると自動停止）

• セッションには表示名を付けられる（start_session で agent が付け、ブラウザからいつでも変更できる）。ID は日時ベース（0814-1345）で自動採番され、URL に出る

• サイドバーの各セッションから改名・アーカイブ・完全削除ができる。ファイルは表示中のツールバーから削除できる（どちらも元に戻せない）

• URL は http://localhost:5766/<セッションID>/<ファイル名>。全 URL が deep link

• 同じ名前で再 publish すると新リビジョンとして積まれ、リビジョン間の差分（unified / side-by-side）が見られる

• 3 ペイン UI（セッション / ファイル / ビュー）+ SSE live update。新着 publish への自動追従は「新着に追従」トグルで制御

• agent が終了したセッションは自動で archive され、サイドバーの「archived」トグルで表示できる。kairan restart を挟んでも、生きている agent のセッションは active のまま残る

• agent を閉じて --resume / --continue で開き直すと、同じセッションに戻る（Claude Code のセッション ID を鍵にしている。この ID を持たない agent では従来どおり毎回新しいセッションになる）。セッションができるのは最初に kairan を使った時点なので、agent を立ち上げただけでは何も増えない

• markdown は GFM + shiki シンタックスハイライト + mermaid 図に対応。HTML は iframe でそのまま実行できる

• publish された HTML は kairan と同一オリジンで動く。実行中の文書にそのままインラインコメントを付けられるようにするための設計で、引き換えに文書のスクリプトは kairan の API（セッション・ファイルの削除、レビュー送信、ローカルファイルを開く操作）を叩ける。信頼できない HTML を publish しないこと（markdown 側は本体画面の script-src 'self' で inline handler を禁止している）

• タブの favicon がステータスを示す。あなたの対応待ち（未回答の質問・agent がレビュー送信を待っている）があれば赤バッジ、タブを開いている間に届いた未読の publish があれば青バッジ。タブタイトルにも対応待ちの件数が出る

• 表示中のファイルを「Finder で表示」「エディタで開く」「ダウンロード」できる。Finder / エディタは path で publish されたファイルを localhost から見ているときだけ出る（cloudflare tunnel 等のリモート閲覧ではダウンロードのみ）

• publish 時に macOS 通知センターへ通知（設定で off 可）。terminal-notifier が入っていれば通知クリックでそのファイルをブラウザで開ける（brew install terminal-notifier。無ければ osascript 通知にフォールバック、クリック遷移なし）

• 人間 → agent のフィードバックにも対応。文書にインラインコメントを付けて GitHub PR レビューのように一括送信でき（request_review で agent が受け取る）、agent からの選択肢つき質問（ask_user）にブラウザ上で回答できる

  • 選択範囲へのインラインコメントは markdown・HTML のどちらの表示でも使える（HTML は実行したまま。ソース表示ではファイル全体へのコメントのみ）

  • 本文の横に常時並ぶコメントカードは markdown 表示だけ。HTML では iframe が内側でスクロールして位置を追えないため、ハイライトの hover / クリックでカードを出す

セットアップ

bun install
bun link   # `kairan` コマンドをグローバルに登録

Claude Code

claude mcp add --scope user kairan -- kairan mcp

Codex CLI

# ~/.codex/config.toml
[mcp_servers.kairan]
command = "kairan"
args = ["mcp"]

Related MCP server: feedback-mcp-server

tool

start_session

このプロセスのセッションを開始し、人間向けの表示名を付ける。最初の publish の前に一度呼ぶと、サイドバーでどの agent のセッションか見分けられる。以後 session を省略した tool call はここで始めたセッションに載る。

戻り値: { sessionId, label, url }

publish

markdown / HTML をブラウザに表示する。path（ファイルパス）か content（文字列）のどちらかを渡す。

戻り値: { url, sessionId, fileId, revision, pendingFeedback }（pendingFeedback は未受領フィードバック件数）

path で publish したファイルは元の絶対パスが記録され、ブラウザの「Finder で表示」「エディタで開く」から開ける（content で publish し直すと記録は消える）。パス自体は API の応答にも list_files にも出ない。

list_files

自セッション（または session で指定したセッション ID）の publish 済みファイル一覧。

request_review

人間にブラウザでのレビューを依頼し、送信されるまでブロックする。人間側はコメントを下書きとして溜め、総評とともに「送信」した時点でまとめて返る（GitHub PR レビューと同じモデル。コメント 0 件 + 総評空の「コメントなしで返す」も可）。timeout（デフォルト 20 分、timeout_seconds で変更可）で「まだフィードバックなし」が返るので、続けて待つ場合は再度呼ぶ（再呼び出しループで何時間でも待てる）。

戻り値には各コメントの commentId・対象ファイル・引用文（選択範囲）・本文と、総評・スレッド返信・未回収の質問回答が含まれる。

ask_user

選択肢つきの質問カードをブラウザに表示し、回答されるまでブロックする。複数 question を 1 カードに積め、各 question は選択肢 + 自由記述（常設）を持つ。人間は全問に答えてから送信する。file を渡すとその質問がどのファイルの話かサイドバーにバッジ表示される。timeout 後に同じ質問で再度呼ぶと既存カードを再利用して待ち直す（カードは増えない）。

reply_comment

request_review / list_feedback が返した commentId へのスレッド返信。resolve: true でコメントを解決済みにできる（人間側から再オープン可）。

list_feedback

ブロックせずに、送信済み・未受領のフィードバック（レビュー・質問回答）を回収する。agent が待っていない間に送信されたぶんの回収用。各項目は一度だけ返る。

CLI

kairan status    # デーモンの稼働確認
kairan restart   # デーモンの再起動（コード・設定変更の反映用）
kairan stop      # デーモンの停止（通常は不要: 全接続が消えると自動停止する）
kairan daemon    # デーモンをフォアグラウンド起動（通常は自動起動されるため不要）
kairan relink    # 過去のセッションを agent のセッションに繋ぎ直す（下記）

kairan relink

復帰の鍵（agent のセッション ID）を持たない古いセッションに、Claude Code の履歴から鍵を埋め直す。鍵が無いセッションは --resume で戻れず、開き直すたびに新しいセッションができてしまうため、その復旧用。

• ~/.claude/projects/*/*.jsonl（CLAUDE_CONFIG_DIR を設定していればそちら）から、kairan の tool 呼び出しの結果だけを拾って対応付ける

• 併せて畳まれていて中身が空のセッションを削除する（残したくない場合は --keep-empty）

• --dry-run で何をするかだけ表示できる

• 適用時はデーモンを止めてから DB をバックアップし、終わったら元の状態に戻す。稼働中のセッションからは鍵を奪わない

コード変更の反映

• デーモン側（Web UI・API・レンダリング・通知など大半のロジック）: kairan restart で反映される。稼働中の agent は自動で接続し直すため、セッションは active のまま残る

• stdio ランチャー側（tool 定義・入力解決）: ランチャープロセスは agent が起動・保持しているため kairan 側からは再起動できない。agent の MCP 再接続で反映される（Claude Code は /mcp → Reconnect、または新しいセッションを開始）

設定

~/.kairan/config.json（すべて任意）と環境変数で上書きできる。優先度: 環境変数 > config.json > デフォルト。

設定ファイルのパス自体は KAIRAN_CONFIG_PATH で変更できる。

公開する場合の注意

kairan 自体は認証を持たない。/api/* の POST に入っているのは cross-origin を弾く CSRF 対策であって認証ではなく、Origin ヘッダの無いリクエスト（MCP ランチャー・curl）は意図的に通す。cloudflare tunnel 等で外から届くようにする場合、tunnel 側で認証をかけること（到達できる相手はセッションの一覧取得も完全削除もできる）。

publish された HTML も同一オリジンで動く（実行中の文書にコメントを付けるための設計）。つまり文書のスクリプトは kairan の API を叩けるので、信頼できない HTML を publish しない。ローカルでの利便性を優先した割り切りで、agent が生成した文書を自分で見る用途を想定している。

アーキテクチャ

agent (Claude Code / Codex)
  │ stdio MCP
  ▼
kairan mcp（agent ごとに 1 プロセス。port は使わない）
  │ HTTP（初回 tool call 時にデーモンを自動 spawn・生存申告の SSE を維持）
  ▼
kairan daemon（全体で 1 つ・port 1 つ）── SQLite (~/.kairan/kairan.db)
  │ HTTP + SSE
  ▼
browser（3ペイン UI）

• stdio プロセス = 1 セッション。プロセス終了（= agent 終了）で TCP が切れ、デーモンがセッションを archive する

• デーモンは「active セッション 0 かつ 閲覧タブ 0」になると自動停止する。データは SQLite に永続化されているため、次回起動時も過去セッションを閲覧できる

• 設計判断の経緯: .local/docs/adr/0001-stdio-launcher-shared-daemon.md

開発

bun test            # テスト
bun run typecheck   # tsc
bun run lint        # biome
bun run dev         # デーモンをフォアグラウンド起動