capsule

---

MCP はエージェントにツールを提供します。スキルはエージェントに手順を提供します。Capsule はエージェントにコンパクトなプロジェクトコンテキストを提供します。

大規模なリポジトリでは、コーディングエージェントが同じファイル、決定事項、規約、セットアップの詳細を何度も探し直すために、トークンを消費してしまいます。Capsule は、大規模なリポジトリで複数のセッションにわたってエージェントを使う場合に、リポジトリの情報を繰り返し探し直すためのコンテキストを 50～70% 削減することを目指しています。

インストール

インストール不要 — npx で直接実行できます（常に最新バージョンを使用します）：

npx capsulectx init

または、パッケージマネージャーでグローバルにインストールします：

# npm
npm install -g capsulectx

# pnpm
pnpm add -g capsulectx

# yarn
yarn global add capsulectx

# bun
bun add -g capsulectx

最新の状態に保つには：

npm install -g capsulectx --prefer-online

ヒント： npx が最も手軽な方法です。手動で更新しなくても、公開済みの最新バージョンが常に実行されます。

クイックスタート

npx capsulectx init

Capsule はリポジトリをスキャンし、必要に応じて AI でカプセルを拡充します（インストール済みの Claude CLI、API キー、またはブラウザベースの AI 向けに生成したプロンプトを使用します）。そして、次のものを作成します：

.capsules/
  index.md
  architecture.md
  setup.md
  api.md
  data.md
  ui.md
  testing.md
  deployment.md

各カプセルは、JSON フロントマターにソースのフィンガープリントを含む Markdown ファイルです：

---json
{
  "name": "api",
  "sources": ["src/api/**"],
  "fingerprints": { "src/api/users.ts": "sha256:..." },
  "updated_at": "2026-06-20T14:00:00.000Z"
}
---

# API Capsule

## Purpose

Request handlers, routes, controllers, and service boundaries.

## Key Files

- `src/api/users.ts`: source file matched by this capsule.

## Decisions

- Record stable decisions here so future agents do not rediscover them.

エージェントは .capsules/index.md を読み、関連するカプセルを選び、古くなっていないかを確認してから、本当に必要なソースファイルだけを調べます。

コマンド

コマンド	説明
capsule init	リポジトリをスキャンし、AI による拡充を（任意で）実行して、すべてのカプセルを書き込みます
capsule enrich	既存のカプセルに対して、AI による拡充を再実行します
capsule apply	AI が生成した JSON を、カプセルの「規約」と「決定事項」に適用します
capsule write <name>	ソースから 1 つのカプセルを更新します（編集内容は保持されます）
capsule refresh <name>	1 つのカプセルを明示的に更新します
capsule refresh --all	検出されたすべてのカプセルを明示的に更新します
capsule get <name>	1 つのカプセルを標準出力に表示します
capsule scan	書き込みを行わず、検出されたソースグループを表示します
capsule stale [name]	前回の書き込み以降に変更されたソースファイルを確認します
capsule estimate <name>	1 つのカプセルで見込まれるトークン削減量を表示します
capsule stats	すべてのカプセルのトークン削減量を表示します
capsule report [name]	再現可能なソース／カプセル／古い状態のトークン削減量を表示します
capsule report --write	証明用の成果物として .capsules/report.md を書き込みます
capsule check	CI 向けの鮮度／設定チェックを行います。カプセルが古い、または存在しない場合はゼロ以外で終了します
capsule --mcp	エージェントとのネイティブ連携用に MCP サーバーを起動します

MCP サーバー

Capsule には MCP サーバーが付属しており、Claude Code やその他の MCP 対応エージェントが、手動でファイルを読み込むことなく、カプセルをネイティブに検出して利用できます。

プロジェクトの .claude/settings.json に追加します：

{
  "mcpServers": {
    "capsule": {
      "command": "npx",
      "args": ["capsulectx", "--mcp"]
    }
  }
}

または、すべてのプロジェクトで有効にするには、グローバルな ~/.claude/settings.json に追加します。

設定すると、エージェントは次のツールを自動的に利用できます：

ツール	機能
capsule_list	すべてのカプセルを鮮度ステータスとともに一覧表示します
capsule_get	カプセルの圧縮コンテキストを読み込みます。古くなっている場合は警告しますが、書き込みは行いません
capsule_refresh	1つまたはすべてのカプセルを明示的に更新します
capsule_stale	ソースが古くなっているカプセルを確認します
capsule_stats	カプセルごとのトークン削減量を表示します
capsule_report	検出による削減効果の証拠を機械可読形式で表示します
capsule_check	CI形式で、古いカプセルや不足しているカプセル、設定を確認します
capsule_init	現在のリポジトリ用にカプセルを生成します

カプセルは、capsule:///index および capsule:///{name} の MCP リソースとしても利用できます。

削減効果の確認

$ capsule report architecture

Capsule: architecture

  capsule       status     source   capsule     stale   saved
  architecture  fresh       9,607       417         0     96%

トークン数は、正確に測定するために cl100k_base トークナイザーを使用します。

CI では、次を実行します：

npx capsulectx check

カプセルが古くなっている場合、不足している場合、または無効な設定によってブロックされている場合は、ゼロ以外の終了コードを返します。

エージェントのワークフロー

AGENTS.md、CLAUDE.md、Cursor のルール、またはエージェントへの指示に追加します：

Before working in this repo:

1. Read `.capsules/index.md` if it exists.
2. Read the capsule matching the task area.
3. Run `capsule stale <name>` when the CLI is available.
4. If stale, inspect changed source files before editing.
5. Update capsules when durable project knowledge changes.

ファイルを読み取れるエージェントであれば、Claude Code、Codex、Cursor、Windsurf、Devin、カスタム MCP エージェントなど、どれでも動作します。

カスタムグループ

Capsule は標準的な構成を標準で検出します。標準外の構成では、.capsules/config.json を追加します：

{
  "groups": [
    {
      "name": "workers",
      "description": "Background jobs, queues, and scheduled tasks.",
      "sources": ["src/workers/**", "src/jobs/**"]
    }
  ],
  "ignore": ["legacy/**"]
}

デフォルトグループと同じ name を持つ groups エントリは、そのグループを上書きします。新しい名前は末尾に追加されます。ignore パターンは、デフォルトの除外リストに追加されます。

公開カプセルファイル形式については、docs/capsule-format.md を参照してください。

デモのビルド

この README のアニメーションは生成された GIF であり、画面録画ツールは不要です。

npm run demo

rsvg-convert（librsvg / librsvg2-tools）と ffmpeg が必要です。このスクリプトは、Retina 向けに 2× でレンダリングした SVG フレームから docs/demo.gif を出力します。scripts/build-demo.mjs を参照してください。

ドキュメントサイト

オープンソース版のドキュメントは docs-site/ にあり、VitePress でビルドします。

npm run docs:dev
npm run docs:build

ステータス

Capsule はまだ初期段階ですが、機能します。現在の機能：

• モノレポ（Turborepo、pnpm workspaces）に対応した、言語に依存しないリポジトリスキャン
• 静的解析：フレームワークの検出、テーブル／モデルの抽出、ルートの検出、環境変数の検出
• init 時の AI による情報拡充 — インストール済みの Claude CLI を起動するか、Claude/OpenAI API を呼び出すか、ブラウザベースの任意の AI（Claude.ai、ChatGPT、Cursor、Windsurf）用のプロンプトを生成します
• 書き込みに配慮した再生成：Conventions と Decisions への人手による編集は更新時に保持されます
• Claude Code／エージェントとのネイティブな統合に対応する MCP サーバー
• ダッシュボードでの実際のトークン数（cl100k_base）と削減量の表示
• TypeScript API サーフェスの抽出
• バイナリファイルのフィルタリング
• 古さの検出とトークン削減量の推定
• 再現可能な report と CI に適した check
• .capsules/config.json によるカスタムグループ設定
• カプセルの指示を含めるための CLAUDE.md、AGENTS.md、.cursorrules、.windsurfrules の自動パッチ適用

ロードマップ：

• ソースの変更を差分比較し、対象を絞った更新を提案する、よりスマートな write
• 実際のエージェントセッションにおける、実行前後のトークンレポート
• capsule check 用の GitHub Action ラッパー

ローカル開発用のインストール

git clone https://github.com/dawitlabs/capsule.git
cd capsule
npm install
npm run build
node dist/cli.js init

ライセンス

MIT