Caotang

Caotang

Caotang は、小説やその他の長編フィクションを書くためのライティングスタジオです。原稿はお使いのマシンに保存されます。AI エージェントも原稿を扱えます。計画や下書きは承認を待ち、小さな変更はすぐに反映されます。また、最近の各ターンは、Settings で設定したチェックポイントの上限内で取り消せます。

Caotang は、Scrivener の書き手にはおなじみの構成を備えています。章やシーンをまとめるバインダー、コルクボード、インスペクター、登場人物や場所をまとめるコデックスがあり、コンパイルすると Word、EPUB、Markdown、プレーンテキストに書き出せます。さらに、脚本シーン（Fountain）、分岐する会話（Ink）、動画プロンプトパック付きのストーリーボードを編集する機能もあり、コンパイルでこれらの形式にも書き出せます。異なるのはエージェントです。プロバイダーの API キーを用意すると、アプリ独自のコマンドを通じて動作します。エージェントが計画を提案し、承認または変更したうえで、プロジェクトに変更を加える各ターンでチェックポイントが作成されます。Settings で設定した上限内であれば、復元できます。

caotang.app でお試しいただくか、caotang.app/app から直接アプリを開いてください。

Caotang は無料で、MIT ライセンスで公開されています。アカウント、サブスクリプション、利用量のメーター、Caotang のサーバーはありません。モデルプロバイダーを利用する場合は、そのプロバイダーに直接料金を支払います。

現在利用できる機能

• プロジェクト。 ブラウザーでプロジェクトを作成、開く、名前変更、削除できます。タイトル、著者、言語、ISBN、表紙を設定できます。プロジェクトを .caotang バンドルとしてエクスポートし、再度インポートできます。Chrome または Edge では、プロジェクトフォルダーを開いたり、フォルダーに保存したりできます。このブラウザーがすでに保持しているプロジェクトのフォルダーは、同じ本が含まれていればそのプロジェクトとして開き、別のタブで開いているプロジェクトのフォルダーは拒否されます。Caotang が行っていない変更を上書きして保存する前や、別のプログラムが削除した caotang.json を書き戻す前に、確認を求めます。フォルダーを開くと、そのフォルダーの執筆セッションがこのブラウザーに取り込まれます。
• バインダー。 章とシーンで構成される原稿と、コンパイルされないリサーチセクションです。ドラッグして並べ替え、名前変更、ステータスやラベルの設定、削除、取り消しができます。テキスト、ステータス、ラベル、単語数、キーワード、最近の日付で絞り込めるフィルターバー（保存済みフィルター付き）と、単語数の目標、スプリントタイマー、執筆履歴、停止したタブが保持していた単語数を表示するフッターがあります。
• コルクボード。 章のシーン、または原稿の章を、3種類のサイズのカードで表示します。ドラッグして並べ替えられます。
• インスペクター。 選択した項目のあらすじ、メモ、キーワード、ステータスとラベル、コーデックスへのリンク、シーンの宣言、および台詞のコンテナー設定を表示します。
• エディター。 シーンは Markdown 形式で、入力と同時に保存されます。単語数、1日の目標、集中モードを利用できます。エージェントの下書きはシーンに表示され、プレビューバーで確認できます。
• 脚本。 シーンは Fountain 形式で、Script ビュー、Source ビュー、Pages ビューがあります。Pages ビューでは、Source ビューの行を開けます。.fountain または .fdx の脚本をセクションとシーンとしてインポートできます。Final Draft ファイルは、Final Draft 自体との照合がまだ行われていません。
• 台詞。 コンテナーは Ink ストーリーで、アウトライン、分岐グラフ、検出結果、行 ID が含まれます。互いに分岐するノットのグループごとに1つのコンテナーとして .ink ストーリーをインポートできます。または、インポートで取り除かれるロジックのレポートを確認したうえで、Twee 3 ストーリー（.twee）を1つのコンテナーとしてインポートできます。
• ストーリーボード。 画像（選択、ドロップ、貼り付けで追加）付きのショットカード、アニマティックの合計時間、脚本のカバレッジ、対象となる各動画モデル向けのプロンプト、および JSON、Markdown、CSV としてエクスポートできるプロンプトパックがあります。
• コーデックス。 キャラクター、場所、オブジェクト、ロア、サブプロットなどの項目を、別名、含めるポリシー、除外する語句、各名前が登場する文書の一覧とともに管理できます。
• エージェントへの指示とメモリ。 常時適用する指示はプロジェクトのルートにある CAOTANG.md に保存され、画面に表示される1,500トークンの上限内で、すべてのリクエストに適用されます。エージェントが保持するメモは memory フォルダー内のプレーンファイルで、読み取り、編集、削除ができます。エージェントが書き込めるのは、承認したカードの中だけです。
• スキル。 エージェント向けの再利用可能な執筆指示（「三人称一元視点で執筆する」など）です。ほかのツールも読み取れる標準の Agent Skills フォルダーとしてプロジェクトに保存されます。エージェントにスキルを知らせる前に、各スキルを読み、承認します。スキルを変更した場合も、再度確認が求められます。スキルはエージェントを導くものであり、承認が必要なものには何も変更を加えません。
• マクロ。 承認したプランを、いくつかの値を後から入力できるマクロとして保存し、設定から再実行できます。実行結果はほかのプランと同じカードに表示され、取り消し操作1回で元に戻せます。ルールと権限モードは引き続き適用されます。マクロを実行できるのはあなただけで、エージェントは実行できません。
• フック。 エージェントに守らせるチェックを記述します。使用禁止の単語、変更禁止のステータス、守るべき長さ、合格必須の整合性チェックなどを指定でき、エージェントが呼び出されるたびに、その前後で実行されます。フックは警告を出したり、理由を添えて手順を停止し、無効化された「承認」ボタンを表示したり、エージェントにメモを残したりできます。フック自体が何かを承認することはありません。最終的な判断には引き続きルールと権限モードが適用され、フックを追加または削除できるのはあなただけです（設定にフック用のパネルが追加されるまでは、プロジェクトファイルで手動で操作します）。フックを参照してください。
• 検出結果。 コーデックスとシーンの宣言に照らした原稿の簡易スキャンと、プランを承認した後にのみ実行されるモデルレビューがあります。検出結果は重大度別にまとめられ、該当箇所が引用されます。理由を添えて項目を却下する、修正済みとしてマークする、または エージェントに修正を依頼 でエージェントに送ることができます。実行履歴には各実行が保存されます。
• エージェント。 エージェントパネルにプラン、1ステップのカード、下書きプレビューを表示します（設定で選択した場合は、エージェントが追加したテキストをシーン内に保持し、変更箇所だけをマークして承認または却下できます）。チェックポイントと復元機能に加え、各ターンで送受信した内容を表示する トレース タブもあります（内容は開いているタブ内にのみ保持され、リクエストに応じてエクスポートされます）。実行中のターンを停止したり、メモで進行方向を指示したり、処理中に次のメッセージをキューに追加したりできます。モード コントロールで、カードへの応答方法を「プランのみ」、「確認」（既定）、「編集を承認」、「自動」から選べます。質問があった場合にターンを停止する制限も設定できます。モデル呼び出しが5回以上必要なプランは、執筆中にバックグラウンドで実行でき、適用前に下書きを確認できます。長時間の読解作業では、読み取りと提案のみを行うヘルパーエージェントに読解を任せることもできます。提案が行われるのは、承認したプランに含まれている場合だけです。主要プロバイダー（Anthropic、OpenAI、Google、xAI、Mistral、DeepSeek、OpenRouter など）向けのプリセット、追加した OpenAI 互換エンドポイント、またはキー不要の組み込みデモプロバイダーで動作します。モデルが対応している場合はネイティブのツール呼び出しを使用し、モデルレビューをプランのステップとして実行したり、接続して有効にした MCP サーバーのツールを呼び出したりできます（下記参照）。
• エクスポート。 原稿全体または一部を Markdown、プレーンテキスト、Word（.docx）、EPUB 形式でエクスポートできます。脚本、台詞、ストーリーボードでは、Fountain、Final Draft（.fdx。Final Draft 自体との照合はまだ行われていません）、ページ番号付き脚本 PDF、Ink ストーリー、台詞一覧、ショットリスト、ストーリーボードのコンタクトシート（PDF。番号入りの空白フレームに絵を描き、描画の写真を対応するショットにドロップして追加することもできます）もエクスポートできます。整合性レポートも作成できます。レシピにはエクスポート設定が保存されます。
• 設定。 プロバイダープロファイル、エージェントのコンテキスト予算、1日の目標と自動保存の遅延時間、整合性チェック、ライトテーマとダークテーマ、チェックポイントの上限、MCP とツール、データを設定できます。
• MCP とツール。 設定から、外部の Model Context Protocol サーバーに Streamable HTTP で接続できます。各サーバーのツール一覧は、ツールを使用する前に確認でき、ツールを無効にすることもできます。サーバーが読み取り用として信頼され、ツールが読み取り専用の場合に限り、有効なツールはエージェントによってすぐに呼び出されます。それ以外の呼び出しには、あなたの承認が必要です。
• MCP サーバーとしての Caotang。 ほかの AI ツールからプロジェクトフォルダーを読み取り、その文書、メモ、コーデックスをリソースとして追加し、Caotang がシーン向けに収集したコンテキストを含むプロンプトを実行できます。書き込みを許可すると、内容を変更でき、確認が必要な変更はすべてホスト側で確定されます。MCP サーバーとしての Caotangを参照してください。 このビルドにはまだ含まれていません：デスクトップラッパーです。docs/USER-GUIDE.md にほかの項目とともに記載されており、docs/ROADMAP.md に実装順が記載されています。

要件

• Node.js。 package.json の engines フィールドでは、22 系の Node 22.12 以降、24.x、および 26 以降が許可されています。継続的インテグレーションでは、最低バージョンの 22.12.0 と Node 24 をテストします。Node 26 は許可されていますが、テスト対象ではありません。
• pnpm 12.9.1。packageManager で固定されています。Node 22.12.0 では、まず npm install --global [email protected] を実行して Corepack を更新してください。バンドルされている Corepack 0.29.4 では、pnpm の現在の署名キーを検証できません。その後、corepack enable を実行してください。
• ブラウザー。 アプリは最新のブラウザー向けに作られています。エンドツーエンドテストでは、すべてのプルリクエストで Chromium、Firefox、WebKit を対象にテストを実施します。Firefox と WebKit のテストスイートは、毎晩および手動実行時にも実施されます。プロジェクトフォルダーを開いて保存するには、Chrome または Edge、あるいは Chromium ベースの別のブラウザーが必要です。バンドルはどのブラウザーでも動作します。
• デスクトップレイアウトには、幅 960 px 以上のウィンドウが必要です。幅が 1100 px 未満の場合、ツールバーは 2 行目に折り返され、サイドパネルが狭くなります。幅が 960 px 未満（スマートフォン、または縦向きに持ったタブレット）の場合、Caotang は狭いレイアウトになります。バインダーはドロワーに、インスペクターはシートになり、コルクボード、ストーリーボード、会話分岐グラフ、脚本のページビュー、MCP とツール、および Markdown とプレーンテキスト以外のコンパイル形式には「デスクトップで開いてください」と表示されます。エミュレートした Chromium ではテストされていますが、実機のスマートフォンではテストされていません。また、同期機能はないため、バックアップをエクスポートしてください。

インストールと実行

リポジトリをクローンした後、リポジトリのルートで次を実行します。

pnpm install
pnpm dev

pnpm dev を実行すると、http://127.0.0.1:5173 でアプリが起動します。

本番ビルドを作成するには、pnpm build を実行してから pnpm --filter @caotang/desktop preview を実行します。ビルドは apps/desktop/dist/ に出力され、その隣に THIRD-PARTY-NOTICES.md が配置されます。プレビューはデフォルトで http://127.0.0.1:4173 から配信します。次の 2 点にご注意ください。

• ビルドはオリジンのルートで動作するため、CAOTANG_BASE を指定してサブパス向けにビルドした場合（セルフホストを参照）を除き、プレビューと同様にルートから配信してください。
• プロジェクトはオリジンごとに保持されます。オリジンはアドレスとポートの組み合わせです。http://127.0.0.1:5173 で作成したプロジェクトは、http://127.0.0.1:4173 には表示されません。プロジェクトを移動するには、バンドルをエクスポートしてください。

セルフホスト

Caotang は静的ファイルなので、GitHub Pages、Netlify、Cloudflare Pages、S3 バケット、ご自身のマシン上の nginx など、どの静的ホストでも配信できます。実行するサーバー部分はありません。

1. ビルドします：pnpm install を実行し、続けて pnpm build を実行します。サイトは apps/desktop/dist/ 内のすべてのファイルと、その隣にある THIRD-PARTY-NOTICES.md で構成されています。フォルダー全体をコピーしてください。
2. HTTPS で配信してください。 ブラウザーで Caotang が使用する WebCrypto による鍵の封印とフォルダーアクセスが利用できるのは、セキュアなオリジン（https://、またはご自身のマシン上の http://localhost と http://127.0.0.1）だけです。
3. オリジンのルートで配信してください（https://writing.example.com/）。または、CAOTANG_BASE を使ってサブパス向けにビルドします。CAOTANG_BASE=/caotang/ pnpm build を実行すると、https://example.com/caotang/ で動作するビルドが作成されます。デフォルトでは、ビルドのアセットパスは / から始まります。
4. フォルダーへの保存には Chromium ブラウザー（Chrome、Edge、Brave、Arc など）が必要です。これらのブラウザーには File System Access API が備わっています。それ以外のブラウザーでは、プロジェクトはブラウザー内に保存され、.caotang バンドルとして移動できます。

プロジェクトはオリジンごとに保存されます。あるホストで作成したプロジェクトは、別のホストには表示されません。移動するには、バンドルをエクスポートしてください。

ビルドの index.html には、Content-Security-Policy がすでに <meta> タグで記述されています。ヘッダーを送信できるホストでは、同じポリシーをヘッダーとして送信し、<meta> タグでは設定できない保護（frame-ancestors）を追加できます。

Content-Security-Policy: default-src 'self'; script-src 'self'; style-src 'self'; img-src 'self' data: blob:; font-src 'self' data:; connect-src *; worker-src 'self'; frame-src 'none'; object-src 'none'; base-uri 'self'; form-action 'none'; frame-ancestors 'none'
X-Content-Type-Options: nosniff
Referrer-Policy: no-referrer

connect-src * は意図的な設定です。エージェントはブラウザーから直接、設定した任意のプロバイダーおよび MCP サーバーと通信します。制限を厳しくする場合は、使用するプロバイダーと、ローカルモデルのプリセット（Ollama、LM Studio、llama.cpp）を使用する場合は http://127.0.0.1:* を指定してください。

Netlify または Cloudflare Pages では、apps/desktop/dist/（またはビルドごとにコピーされるように apps/desktop/public/）にある _headers ファイルにヘッダーを記述してください。

/*
  Content-Security-Policy: default-src 'self'; script-src 'self'; style-src 'self'; img-src 'self' data: blob:; font-src 'self' data:; connect-src *; worker-src 'self'; frame-src 'none'; object-src 'none'; base-uri 'self'; form-action 'none'; frame-ancestors 'none'
  X-Content-Type-Options: nosniff
  Referrer-Policy: no-referrer

nginx の場合：

server {
    listen 443 ssl;
    server_name writing.example.com;
    root /var/www/caotang;   # the contents of apps/desktop/dist

    add_header Content-Security-Policy "default-src 'self'; script-src 'self'; style-src 'self'; img-src 'self' data: blob:; font-src 'self' data:; connect-src *; worker-src 'self'; frame-src 'none'; object-src 'none'; base-uri 'self'; form-action 'none'; frame-ancestors 'none'" always;
    add_header X-Content-Type-Options nosniff always;
    add_header Referrer-Policy no-referrer always;

    location / {
        try_files $uri /index.html;
    }
}

リポジトリの Pages workflow は caotang.app をデプロイします。ルートには site/ のランディングページ、llms.txt、robots.txt、サイトマップが配置され、CAOTANG_BASE=/app/ を指定して作成した同じビルドが /app/ に配置されます。

テスト

pnpm verify                             # lint, typecheck, and the unit tests in packages/ and test/
pnpm exec playwright install chromium   # once, for the browser the pull-request end-to-end tests use
pnpm test:e2e                           # the Chromium Playwright suite
pnpm exec playwright install firefox webkit  # once, for the optional cross-browser suite
CAOTANG_E2E_BROWSERS=all pnpm exec playwright test --project=webkit  # run a cross-browser project

エージェントのゴールデンライティングタスクは pnpm verify 内で実行されます。各タスクでは、コミット済みのカセットをモックプロバイダーで再生します。API キーもネットワーク接続も不要で、プロンプトやツールの説明によってモデルに記録時とは異なる内容が送られる場合は失敗します。カセットは合成データ（手書きの回答）であるため、プロンプトとテストハーネスを検証するものであり、モデルについては何も示しません。実際のモデルを使った記録とモデルのベンチマークは、まだ利用できません。

pnpm verify では、デスクトップの e2e/unit にある純粋なモデルのテストは実行されません。これらは Playwright のテストです。pnpm test:e2e を実行すると、開発サーバーのテストスイートと、本番ビルドのスモークテスト（e2e/prod-smoke.spec.ts）も実行されます。このテストでは、専用ポートで vite preview を使用します。

エンドツーエンドテストスイートは専用の開発サーバーを起動します。ただし、CI 外で CAOTANG_E2E_PORT が設定されていない場合は、ポート 5173 ですでに起動しているサーバーを再利用します。Caotang の別のコピーと並行して実行するには、各チェックアウトに専用ポートを割り当ててください。たとえば、CAOTANG_E2E_PORT=5183 pnpm test:e2e のようにします。PowerShell では、先に $env:CAOTANG_E2E_PORT = 5183 を設定します。本番プレビューにはそのポートに 1000 を加えたポートが使われます。CAOTANG_E2E_PREVIEW_PORT を設定した場合は、その値が使われます。

継続的インテグレーション（.github/workflows/ci.yml）では、Node 22.12.0 と 24 を使った verify マトリックスを実行します。各ジョブでは、エンジンのバージョンを厳密にチェックする固定インストールを行った後、pnpm verify、pnpm build、バンドルサイズのチェック、MCP サーバーパックの作成、CLI バンドルのビルドを実行します。Node 22.12 の CI では、packageManager の指定と SHA-512 を照合してから pnpm の tarball を直接インストールします。Node 24 では Corepack を使用します。Node 24 の Chromium エンドツーエンドテストスイートは独立したジョブとして並行実行され、office-interop（openpyxl と LibreOffice を使った .xlsx コーパス）および pdf-validate（pdf.js、qpdf、Poppler、Ghostscript、MuPDF）も実行されます。別のワークフローでは、プルリクエストに対して Firefox と WebKit でのテストを実行し、毎晩および手動でも実行します。各ブラウザーのテストは 2 つのジョブに分割され、結果は 1 つの HTML レポートにまとめられます。シャードが失敗した場合はレポートがアップロードされます。ローカルでこれらのプロジェクトを有効にするには、CAOTANG_E2E_BROWSERS=all を設定してください。フォルダーアクセスのテストは Chromium 以外ではスキップされ、e2e/non-chromium-storage.spec.ts ではそれらのブラウザーが使用するバンドルのみのパスを確認します。

プロバイダープリセットの実際の API キーを使ったチェックである e2e/provider-smoke.spec.ts は、CAOTANG_SMOKE_<PRESET> キーが設定されている場合にのみ実行されます。お使いのマシンで実行するか、メンテナーが provider-smoke ワークフローを手動で実行します（gh workflow run provider-smoke.yml -f presets="anthropic deepseek"）。プルリクエストでは実行されません。providers-browser-cors.md を参照してください。

スクリプト化されたデモは e2e/demo.spec.ts です。3 章構成の物語を作成し、エージェントにシーンの下書きを作成させて承認した後、コルクボード上で物語の順序を入れ替え、Word ファイルにまとめます。その後、ファイルを解凍して構造を確認します。デモでは、キー不要の組み込みデモプロバイダーを使用します。

キーとプライバシーについて

• ご自身のキーをご利用ください。 Settings › Providers でプロバイダーを追加します。プリセット（接続先と認証情報が入力済み）またはご自身の汎用エンドポイントを選び、モデルを選択してキーを貼り付けます。保存すると、Caotang はプロバイダーのモデル一覧を取得して動作を確認します。
• キーはこのブラウザー内にとどまります。 ページからエクスポートできないキーで暗号化され、プロジェクトファイルに書き込まれることはありません。暗号化により、保存されたキーをストレージから読み取れないようにします。ただし、Caotang を開いている間にページ内で実行されるコードからキーを保護するものではありません。
• リクエストは選択したプロバイダーに送られます。 エージェントは、各タスクの役割に対応するプロファイルのエンドポイントにのみリクエストを送ります。ローカルモデルのプリセット（Ollama、LM Studio、llama.cpp）は、ご自身のコンピューター上のサーバーと、ループバックアドレスへのプレーンな http のみで通信するため、テキストはそのマシン内にとどまります。それ以外のすべてのプロバイダーでは https が必要です。組み込みのデモプロバイダーは、ネットワークリクエストを一切行いません。
• エージェントが作業すると、テキストはそのプロバイダーに送られます。 エージェントが必要とするプロジェクトの部分が、各リクエストとともに送信されます。エージェントパネルには、送信されなかった内容が表示されます。「Findings」タブでモデルにレビューさせる場合は、計画を承認した後に、モデルが読み取るテキストが送信されます。
• MCP サーバーは、有効にするまでオフです。 Settings › MCP & tools はデフォルトでオフになっており、オフの間はどのサーバーにも接続しません。有効にしてサーバーに接続すると、Caotang はそのサーバーのアドレス（https、またはご自身のコンピューター上の http）にリクエストを送信し、ツールの一覧取得と、エージェントがツールを呼び出す前の確認を行います。エージェントがツールを呼び出すと、その呼び出しに選んだ引数がサーバーに送られ、結果が Caotang に返されます。Caotang は接続していないサーバーには接続しません。
• アカウントも、Caotang のサーバーも、分析もありません。 プロジェクトはブラウザー内に保存されます。どこでも開けるコピーを保管するには、バンドルをエクスポートしてください。

ディスク上のプロジェクト

プロジェクトはフォルダーです。

caotang.json          the manifest: the binder tree, the codex, the vocabulary, recipes, filters and goals
caotang.json.bak.1..3 the three previous manifests
coherence.json        the findings and check runs, beside the manifest
tasks.json            the recurring agent tasks, definitions only (when each last ran stays in the browser)
docs/                 one file per scene, note or dialogue container, named by id: .md, .fountain or .ink
codex/                one file per codex entry
assets/               images: storyboard pictures and the cover
exports/              compiled files
sessions.jsonl        writing sessions, appended to and read back when the folder opens
.caotang-mcp.lock     present while an MCP server is running on the folder

完全な形式については、docs/architecture/project-format.md を参照してください。バンドルは同じフォルダーを ZIP 形式にしたものです。

MCP サーバーとしての Caotang

Caotang は、Model Context Protocol を介してプロジェクトフォルダーを外部の AI ツールに提供できます。詳細なリファレンスは packages/mcp-server/README.md を参照してください。

サーバーを一度ビルドします。

pnpm --filter @caotang/mcp-server build

これにより、node（22 以降）で実行できる単一ファイル packages/mcp-server/dist/caotang-mcp.mjs が作成されます。ホストがインストールできる MCP バンドルを作成するには、次を実行します。

pnpm --filter @caotang/mcp-server run pack

これにより、packages/mcp-server/dist/caotang-mcp-0.1.0.mcpb が作成されます。または、最新のリリースから caotang-mcp-<version>.mcpb をダウンロードしてください。SHA-256 は SHA256SUMS に記載されています。バンドルにはサーバー、マニフェスト、通知、ライセンスが含まれます。マニフェストは、このパッケージが固定している MCPB CLI によって検証されます。ホストではプロジェクトフォルダーと、デフォルトでオフになっている Allow changes 設定を指定します。バンドルには署名がなく、実際の MCPB ホストで実行されていません。検証と stdio 経由での実行は済んでいます。

プロジェクトフォルダーを HTTP で、127.0.0.1 のみに提供します。

node packages/mcp-server/dist/caotang-mcp.mjs serve --project ~/Writing/my-novel

--allow-writes を追加するか、CAOTANG_MCP_ALLOW_WRITES=true を設定しない限り、サーバーは読み取り専用です。書き込みを許可すると、7 つのツールは変更を即時に適用します（meta.set、notes.append、synopsis.set、filter.save、goal.save、coherence.setFindingStatus、shots.annotate）。9 つのツールでは、書き込みが行われる前に、ホスト上で呼び出しごとに確認する必要があります（binder.restructure、codex.write、codex.import、doc.import、export.compile、notes.replace、vocabulary.upsert、scene.apply、dialogue.apply）。まだプロジェクトのないフォルダーに新しいプロジェクトを作成するには、--create "New Book" を追加します。ドキュメントファイル、コーデックスファイル、またはマニフェストのコピー（caotang.json.*）がすでにあるフォルダーでは --create は拒否されるため、それらを引き継ぐことはできません。 トークン。 HTTP では、サーバーの起動時にベアラートークンが一度だけ表示されます。トークンを自分で選ぶには、サーバーを起動する前に CAOTANG_MCP_TOKEN に16文字以上の値を設定してください。すべてのリクエストで Authorization: Bearer <token> を送信する必要があります。

Stdio。 ホスト自身にサーバーを起動させるには、--stdio を追加してください。ホストのプロセス境界がポートとトークンの代わりになります。

node packages/mcp-server/dist/caotang-mcp.mjs serve --project ~/Writing/my-novel --stdio

ホストの接続。 HTTP のエンドポイントは http://127.0.0.1:7433/mcp です。--port を指定しない場合、ポートは7433です。mcpServers エントリーを受け取るホストには、次の設定が必要です。

{
  "mcpServers": {
    "caotang": {
      "type": "http",
      "url": "http://127.0.0.1:7433/mcp",
      "headers": { "Authorization": "Bearer <token>" }
    }
  }
}

ツールに加えて、サーバーはプロジェクトのテキストをリソースとして提供します。これらは意図的に添付して使用します（Claude Code では @caotang:caotang://doc/…、Cursor ではリソースピッカーを使用します）。また、ジョブ用に Caotang が作成するコンテキストをホストのモデルに渡す5つのプロンプトも提供します。draft-scene、fill-synopsis、continuity-check、codex-from-doc、revise-with-codex です。リソースには文書全体が含まれます。2 MiB を超える文書は切り詰められることなく、拒否されます。プロンプトはホストのモデル上で実行されるため、プロンプトに含まれるテキストは、ホストがツール経由で文書を読み取る場合と同様に、そのモデルへ送信されます。Caotang はモデルを呼び出さず、キーも保持しません。サーバーの README の「Resources」と「Prompts」を参照してください。

接続する前に、次の3点を確認してください。

• 確認が必要な変更は、ホストが確認を表示できない場合、何も書き込まずに拒否されます。ホストは MCP elicitation に対応している必要があります。
• 2025年のプロトコルリビジョンを使用するホストが HTTP 経由で変更を確認するには、elicitation を宣言し、セッション開始時にサーバーが返す Mcp-Session-Id を保持する必要があります。サーバーが保持できる接続は最大16件です。30分間アイドル状態の接続は切断され、16件すべてが使用中の場合、新しいホストには 503 が返されます。セッションを保持できないホストは、--stdio 経由で接続するか、stdio で動作する .mcpb バンドルをインストールしてください。
• サーバーを --allow-writes 付きで実行している間は、サーバーを停止するか、保存に関する各確認にチェックを入れてから、Caotang アプリでフォルダーを保存してください。サーバーのロックを上書きして保存する前にアプリが確認を求めますが、保存を確定すると、サーバーが書き込んだ内容が上書きされる場合があります（サーバーの README の「Known gaps」を参照してください）。

モデルが必要なツールである scene.draft、synopsis.fill、continuity.scan、coherence.review、shots.derive、prompt.draft、prompt.variant、dialogue.draft は、サーバーがプロバイダーキーを保持しないため、MCP 経由では利用できません。シーンと会話文については、代わりにホスト自身のモデルが作成します。scene.brief と dialogue.brief は Caotang のエージェントが送る内容をモデルに渡し、scene.apply と dialogue.apply は確認後にモデルのテキストをプロジェクトに反映します。確認はレビューではないため、まずモデルが作成した内容を読んでください。元に戻すと文書が復元されます。詳細はホストのモデルによる下書き作成を参照してください。既存の文章を Caotang に取り込むでは、利用可能なインポートツール doc.import と codex.import について説明しています。書き込みが許可されている場合、ホストが確認すると export.compile で原稿、単一の項目、または保存済みレシピを、EPUB を含む任意のエクスポート形式にコンパイルできます。

バンドルをインストールする

1. 上記の pack コマンドで caotang-mcp-0.1.0.mcpb をビルドするか、最新のリリースからダウンロードします。
2. ファイルを Claude Desktop などの MCPB ホストにドラッグするか、ホストで開きます。ホストに、バンドル名、説明、2 つの設定を示すダイアログが表示されます。
3. Project folder で、Caotang プロジェクトがすでに保存されているフォルダーを選択します。
4. アシスタントにプロジェクトを変更させたい場合を除き、Allow changes はオフのままにします。オフの場合、アシスタントはプロジェクトを読み取ることしかできません。オンにしても、一部の変更は先にホストで確認を求められます。
5. ホストに、バンドルが署名されていないという警告が表示され、Install Anyway が提示されることがあります。この警告は、現在の署名ツールで作成したバンドルをホストが拒否するため、ホストがファイルの発行元を特定できないことを意味します。コードはオープンソースであり、pack コマンドを使ってソースから同じファイルをビルドできます。自分でビルドした場合、またはこのプロジェクトのリリースから入手した場合にのみ、インストールしてください。

サーバーはコンピューター上で stdio 経由で実行され、ネットワークポートは開きません。バンドルをアンインストールするとサーバーが削除され、プロジェクトフォルダーはそのまま残ります。ダイアログの文言は、ホストやバージョンによって異なります。

このバンドルは署名されておらず、実際のホストでまだテストされていません。packages/mcp-server/HOST-CHECKS.md に確認項目と結果が記載されていますが、現時点では結果はありません。リリースには、ファイルの SHA-256 が SHA256SUMS に記載されています。

コマンドラインからの Caotang

caotang agent はプロジェクトフォルダーでエージェントを1ターン実行して終了します。ターミナル、Makefile、cron ジョブ、CI から利用できます。指定がない限り読み取り専用です。--write を指定しなければフォルダー内は変更されず、変更されるはずのファイルは差分として出力されます。pnpm --filter @caotang/cli build でビルドすると、packages/cli/dist/caotang.mjs が書き出されます（単一ファイルです。node で実行し、fonts/ フォルダーを隣に置いてください）。

# The demo provider: no key, no network. Prints the reply, exits 0, writes nothing.
node dist/caotang.mjs agent -p "Check the manuscript for continuity problems." --mock --project ~/Writing/my-novel

# A review with your own key, read-only. The key comes from the environment, never from a flag.
CAOTANG_API_KEY=... node dist/caotang.mjs agent -p "Check the manuscript for continuity problems." \
  --provider openrouter --project ~/Writing/my-novel --output-format json

# Approve every card the plan shows, save the folder, and print what changed.
CAOTANG_API_KEY=... node dist/caotang.mjs agent -p "Fill in the synopses for Chapter 1." \
  --provider openrouter --project ~/Writing/my-novel --permission approve-all --write

フラグ	意味
-p <intent>	指示内容です。-p - を指定すると、標準入力から読み込みます。
--project <dir>	プロジェクトフォルダーです（デフォルト：作業ディレクトリ）。
--mock or --provider <preset>	デモ用プロバイダー、またはプロバイダーのプリセットです（--base-url、--model、--thinking で詳細を指定できます）。
--key-env <VAR>	キーを保持する環境変数です（デフォルト：CAOTANG_API_KEY）。キー自体を指定するフラグはありません。指定すると ps やシェルの履歴に表示されてしまうためです。
--permission <mode>	read-only（デフォルト）：すべてのカードがキャンセルされます。auto：カードが不要な変更は実行され、すべてのカードがキャンセルされます。approve-all：表示された内容どおりにすべてのカードが承認されます。ただし、プロバイダーが途中で打ち切ったドラフトは承認されません。
--approve-tools <tool,...>	approve-all と併用します。すべてのステップが指定したツールのいずれかである場合に限り、カードを承認します。ほかのステップが1つでも含まれるカードは、全体がキャンセルされます。
--write	ターン終了後にフォルダーを保存します。auto または approve-all が必要です。
--plan-file <plan.json>	作成したプラン { "steps": [{ "tool", "params", "expect" }] } を、プランナーを呼び出さずに実行します。
--output-format	text（デフォルト）、json（ターン終了時に1つのオブジェクトを出力）、または stream-json（イベントごとに1行を出力し、各カードの decision 行の後に結果を出力）です。
--max-model-calls <n>	1ターンで実行できるモデル呼び出しの最大回数です（デフォルト：8）。

標準出力には選択した形式の出力のみが含まれ、進捗状況と注記は標準エラーに出力されます。終了コードは、ターンが完了した場合は 0、内部エラーの場合は 1、コマンドラインの指定が誤っているかプロジェクトのないフォルダーが指定された場合は 2、別の書き込み元（アプリ、または caotang-mcp serve）がフォルダーを使用中の場合は 3、ターンで入力が必要な場合（権限モードによってカードがキャンセルされた、上限に達した、またはプロバイダーでエラーが発生した場合）は 4、競合の場合は 5、検証に失敗した場合は 6、SIGINT と SIGTERM の後は 130 および 143 です。--write を指定した実行の取り消し履歴はコマンドで終わるため、フォルダーを git で管理してください。caotang mcp serve は、caotang-mcp serve と同じフラグで MCP サーバーを起動します。caotang scan はモデルを使わずに継続性チェックを実行します。詳しくはCI での継続性チェックを参照してください。

CI での継続性チェック

caotang scan は、ブラウザー、モデル、キーを使わずに、プロジェクトフォルダーに対して「Findings」タブの決定論的なチェックを実行します。そのため、Git リポジトリで管理しているプロジェクトは、毎晩、または原稿に変更があるプルリクエストごとにチェックできます。

node dist/caotang.mjs scan --project ~/Writing/my-novel                          # a report in the terminal; exit 7 if an error is open
node dist/caotang.mjs scan --format github --fail-on warning --summary ../report.md  # annotations on the files, the Markdown report in a file outside the folder

フラグ	意味
--project <dir>	プロジェクトのフォルダー（デフォルト：作業ディレクトリ）。
--scope <scope>	full（デフォルト）または changed。full はすべてのドキュメントを読み込みます。changed は最後に保存された実行以降に編集されたドキュメントのみを読み込みます。--write を指定しない場合、その実行の記録は更新されないため、CI では full を使用します。
--checks <id,...>	presence.expected,timeline.overlap など、これらのチェックのみを実行します（デフォルト：すべて）。
--format	text（デフォルト）、markdown（整合性レポート）、json、または github（検出結果ごとにワークフローコマンドを出力するため、それぞれファイルと行に表示されます）。
--fail-on <level>	error（デフォルト）、warning、info、または never：未解決の検出結果が実行失敗となる重大度です。
--write	この実行結果を含む coherence.json を保存します。指定しない場合、フォルダーは読み取り専用となり、その後もすべてのファイルはバイト単位で同一です。
--summary <file>	Markdown レポートもこのファイルに書き込みます。パスが $GITHUB_STEP_SUMMARY と同じパスに解決される場合のみ追記されるため、ほかのステップの後に続けられます。それ以外のファイルは全体が上書きされます。--write を指定しない場合、--summary にはプロジェクトフォルダーの外にあるファイルを指定する必要があります。
--help, -h	使用方法を表示して、終了コード 0 で終了します。

スキャンに問題がない場合、または --fail-on never が設定されている場合の終了コードは 0 です。未解決の検出結果が --fail-on 以上の場合は 7、該当するものがなく、--fail-on が never 以外の場合に、ドキュメントまたはコーデックスのファイルが UTF-8 テキストではないためチェックされなかった場合は 8 です（出力にそのファイル名が示され、スキャンは一部のみとなります）。内部エラーの場合は 1、コマンドラインの指定が誤っている場合、またはプロジェクトを含まないフォルダーの場合は 2、別の書き込み処理がフォルダーをロックしている場合は 3 です（--write の指定時のみ。フォルダーのロックを取得します）。アプリで却下済みまたは修正済みとマークされ、coherence.json にコミットされている検出結果は、出力にも実行失敗の判定にも含まれません。coherence.json を読み込めない場合は修復せず、検出結果を再計算し、却下した結果が失われたことを出力に示します。スキャンでは対話のチェックも実行します。ドキュメントはプロジェクト内のファイルから読み込むため、脚本内の検出結果は .fountain ファイルに、対話コンテナー内の検出結果は .ink ファイルに記録されます。

ワークフロー。 docs/ci/continuity-scan.yml は、プロジェクトのリポジトリ内の .github/workflows/ にコピーして使う GitHub Actions ワークフローです。毎晩、手動で、また docs/、codex/、caotang.json または coherence.json に変更があるプルリクエストで実行されます。プロジェクトのフォルダーはリポジトリのルートである必要があります。スキャンのステップでは --project を渡さず、パスフィルターもルートを前提としているため、プロジェクトがサブフォルダーにある場合は、そのステップに --project <dir> を追加し、フィルターにもそのフォルダーを追加してください。このワークフローが要求するのは contents: read のみで、シークレットを保持せず、pull_request_target も使用しません。npx は実行せず、Caotang のリリースから caotang.mjs をダウンロードし、ファイルに記載された SHA-256 と照合します。この値はリリースの SHA256SUMS に記載されています。このテンプレートはリリース v0.1.0 に固定されているため、コピーしたまま使用できます。後のリリースに切り替えるには、そのリリースの SHA256SUMS を参照してバージョンとハッシュを両方設定してください（pnpm --filter @caotang/cli build を実行すると、同じファイルがローカルに書き込まれます）。

出力内容。 注釈とジョブログには、原稿からの短い引用が含まれます。検出結果には対象箇所の引用が含まれるためです。公開リポジトリでは、誰でもそれらを読めます。問題になる場合は、リポジトリを非公開にするか、出力を公開しないステップで --format text を指定してスキャンを実行してください。

CI ではモデルレビューを実行しません。 CI で実行するのは決定論的なチェックのみです。モデルレビューは提供していません。実行にはリポジトリのシークレットにキーが必要となり、キーがデバイスの外に出る唯一の場所となるほか、定期実行に伴う費用も発生するためです。追加される場合は、定期タスクに適用されているタスクごとのオプトインと呼び出し上限の対象となり、別途スコープを限定したキーと読み取り専用のツール許可リストを使用します。

Scripting Caotang

エージェントは、承認ポリシーをカードの代わりに設定して、プロジェクトフォルダーに対して Node スクリプト、CLI、または CI から実行することもできます。パッケージは @caotang/sdk です。README には、デモプロバイダー、独自のキーを使った読み取り専用レビュー、フォルダーに書き込むすべて承認の実行という 3 つの例があります。変更は保存するまでメモリ内にとどまり、diff() で事前に確認できます。また、キーはメモリ内に保持され、プロバイダーにのみ送信されます。

ドキュメント

• docs/USER-GUIDE.md：執筆者向けガイドです。
• CHANGELOG.md：リリース内容と既知の制限事項です。
• docs/ARCHITECTURE.md：モジュール構成、データモデル、設計原則です。
• docs/architecture/：モジュールごとの仕様です。agent-harness.md ではエージェントのツールについて、extensibility.md では MCP クライアントとサーバーについて説明しています。
• docs/ROADMAP.md：実装済みの機能、現在開発中の機能、今後の予定です。
• docs/decisions.md：継続中の決定事項を、決定者とともに 1 行ずつ記載しています。
• CONTRIBUTING.md と SECURITY.md：コントリビューションの方法と、脆弱性の報告方法です。

Caotang の構築方法

Caotang は、オーナーの指示のもと、AI コーディングエージェントを使って構築されました。docs/decisions.md で [owner] のタグが付いた決定事項はすべて、人が決定したものです。

ライセンス

Caotang は MIT License のもとで公開されています。詳しくは LICENSE をご覧ください。THIRD-PARTY-NOTICES.md には、ビルドに含まれるサードパーティパッケージとそのライセンスが記載されています。node tools/third-party-notices.mjs --write を実行すると再生成できます。コミット済みの内容がロックファイルと一致しなくなると、テストは失敗します。