wctx

コーディングエージェントのためのワークスペースコンテキスト。

あなたのシステムは複数のリポジトリにまたがっています。エージェントのコンテキストも同様であるべきです。

wctx capture --summary "what this session figured out"   # at the end of a session
wctx search  "has anyone looked at this?"                # from any other repo, later

Session in Repo A
        ↓
discovers behavior in Repo B
        ↓
wctx
        ↓
fresh session in Repo B retrieves it

コーディングエージェントのセッションはリポジトリにスコープされます。なぜなら、ファイルが編集されるのはそこだからです。しかし、調査対象のシステムはそうではありません。したがって、UIリポジトリでのセッションでバグが実際にはSDKにあると突き止めても、1週間後にSDKで新しいセッションを開くと、その知識は失われています。

wctxは、完了したエージェントセッションを構造化されたエビデンスに基づくエンジニアリングコンテキストに変換し、MCPを介して将来のセッションに提供します。ローカルファースト：クラウドアカウント不要、埋め込み不要、トランスクリプトのアップロード不要。

2分でわかるデモ

pnpm install
pnpm demo

APIキーもネットワークも不要。3つの合成リポジトリを構築し、そのうちの1つから完了したセッションをインポートし、別のリポジトリから平易な言語で質問します：

$ wctx search "Has the selfie session expiration issue already been investigated?" --repo websdk-demo

  3 result(s) · 4 candidates · 14ms · searched websdk-demo plus 2 related repositories

  1. WebSDK uploadSessionImage does not retry after session expiration  [finding]
     from websdk-demo · session ses_8d3fb1a5 · commit 45a4cab · confidence 0.87
     · matches the query text
     · same repository
     · matches symbol uploadSessionImage

  3. Verify UI delegates selfie upload to the WebSDK  [finding]
     from verify-ui-demo · session ses_8d3fb1a5 · commit b041200 · confidence 0.95
     · matches the query text
     · verify-ui-demo uses websdk-demo (direct consumer)
     · high stated confidence (0.95)

そしてSDKファイルが変更され、エビデンスが信頼できなくなります：

$ wctx evidence verify ev_9ae81278
  before: current — The repository is still at the source commit b60a991; nothing has changed.
  after:  stale   — All 1 referenced file(s) changed in b60a991..1ceeaa4. Re-read the code
                    before relying on this.

完全なウォークスルー：docs/demo.md。

Related MCP server: obsmcp

インストール

Node 22以上とgitが必要です。

pnpm install
pnpm build
npm link        # optional: puts `wctx` on your PATH

wctx init       # creates ~/.wctx
wctx doctor     # checks database, git, adapters, and prints MCP setup hints

MCPのセットアップ

claude mcp add wctx -- wctx mcp

または、Codexやその他のMCPクライアントの場合：

{ "mcpServers": { "wctx": { "command": "wctx", "args": ["mcp"] } } }

7つのツール。段階的な開示のために順序付けられており、コンテキストウィンドウ内で手頃な価格を維持できます：

wctx mcp-infoは、サーフェスとクライアント設定のスニペットを出力します。

セッションで学んだことを記録する

セッションの最後に1つのコマンド。セッションをインポートし、エビデンスを1ステップで記録します。デフォルトでは実行中のセッションを使用します：

wctx capture --summary "Traced the upload failure into the SDK" \
  --finding "SDK swallows the 419 :: uploadSessionImage returns it as terminal, no retry" \
  --repo my-sdk \
  --file "src/session/upload.ts#uploadSessionImage"

または、エージェントに「学んだことを記録して」と依頼するだけで、エージェントが自身のセッションIDでfinalize_sessionを呼び出します。内部IDを知る必要はなく、1回のセッションで繰り返し呼び出すと、セッションを重複させるのではなくエビデンスが蓄積されます。

プロアクティブにするには

エージェントがこれを行うのは、何かが指示した場合のみです。最も強力な場所はプロジェクト独自のエージェントファイルです。これらはすべてのリクエストで読み取られます：

wctx instructions          # print the guidance
wctx instructions --write   # install it into CLAUDE.md / AGENTS.md (idempotent)

ガイダンスでは、いつ検索するか（重要なことを調査する前）、いつ記録するか（根本原因、根拠のある決定、苦労して得た制約、未解決の質問、驚き）、そして何を記録しないかをカバーしています。これが、使い忘れるツールと、自然に蓄積されるツールの違いです。

サマリーがまったく提供されない場合、wctx captureはセッションの記録されたツールアクティビティ（ファイル数、コマンド、エラー、変更されたファイル）から事実に基づいたサマリーを導出します。意図的に退屈にしています：ツール呼び出しから物語を創作することは、このプロジェクトが作成することを拒否する、まさに自信過剰なナンセンスだからです。

中核概念

ワークスペース — リポジトリを超えた論理的なプロダクト。コンテキストの境界。リポジトリは編集の境界のままです。このプロジェクトはエージェントの書き込み範囲を広げることは一切しません。

リポジトリ — 登録されたgitチェックアウト。実パスで識別されるため、同じリポジトリがシンボリックリンクやサブディレクトリを通じて2回登録されることはありません。複数のワークスペースに所属できます。

関係 — 宣言された、方向性のある、型付きのエッジ（uses、depends_on、calls、imports、consumes_api、provides_api、shares_schema_with、related）。トラバーサルは両方の方向のエッジをたどります。なぜなら、verify-uiがwebsdkを使用している場合、websdk内のセッションでもverify-uiが学んだことを必要とするからです。

セッション — Xirp、Claude Code、または汎用JSONLからの正規化されたコーディングエージェントセッション。cwd、ブランチ、コミット、メッセージ、ツールアクティビティを含みます。

エビデンス — 発見、決定、変更、未解決の質問、既知の問題、アーキテクチャノート、または制約。それが関するリポジトリにアタッチされ（多くの場合、セッションが実行されたリポジトリとは異なる）、関係するファイルとシンボル、およびそれが真であったコミットを含みます。

鮮度 — 参照されたファイルがそのコミット以降に変更されたかどうかに関するgitベースの判定：current、possibly_stale、stale、またはunknown。

アーキテクチャ

Xirp · Claude Code · Codex · generic JSONL
                  ↓
          session adapters              ← the only code that knows a vendor format
                  ↓
        NormalizedSession
           ↓            ↓
  transcript copy   deterministic extraction (files, commands, errors — no LLM)
                        ↓
              structured evidence (findings, decisions, questions)
                        ↓
              workspace catalog · SQLite + FTS5 + git
                        ↓
              CLI  ·  MCP  ·  web UI          ← one service layer, no duplicated logic

詳細、および各境界の背後にある理由：docs/architecture.md。

Xirp統合状況

Xirpは実際の文書化された読み取りパスを公開していることが判明したため、アダプタはスタブではなく本物です。

アダプタは両方のスキーマ文字列を固定し、未知のバージョンでは推測せずに大きな失敗をします。未検証のままのものとその再現方法を含む完全なエビデンス：docs/research/xirp.md。

セキュリティ

何もあなたのマシンから離れません。クラウドなし、テレメトリなし、埋め込みAPIなし、トランスクリプトのアップロードなし。依存関係リスト全体は @modelcontextprotocol/server、better-sqlite3、commander、および zod です。

• トランスクリプトは、あなたのデータディレクトリにコピーされます（Claude Codeは30日後に自身のものを削除します）。編集済みのコピーも一緒に保存され、編集済みのコピーのみが提供されます。

• 編集は、秘密鍵、JWT、認可ヘッダー、AWS/GitHub/Slack/OpeAI/Gogleトークン、認証されたURL、秘密の割り当てを対象とします。これはベストエフォートのパターンマッチであり、トランスクリプトが共有しても安全であるという保証ではありません。

• エージェントに返されるエビデンスは、過去の信頼できないデータとしてラベリングされ、指示のような行（"すべての以前の指示を無視せよ"）は中世されます。緩和策であり、免疫ではありませｎ。

• すべてのgit呼び出しは引数配列を使用し、シェル文字列は使用しません。FTS5クエリは構築され、絶対に補間されません。

• トランスクリプトの削除とエビデンスの削除は独立した操作です。

詳細：docs/security.md。

既存のツールとの比較

機能の主張は各プロジェクト自身のREADMEからのもので、2026-08-13に確認済みです。ここでは、他のプロジェクトが何かをできないとは主張しません。

各プロジェクトのメモリ境界、キャプチャメカニズム、アイデアとして再利用されたものを含む完全な調査：docs/research/competitive-landscape.md。

評価

合成の15クエリ、28アイテムのコーパス（pnpm eval）において、関連する過去のセッションが15/15のクエリでトップ5に登場し、11/15で1位になりました。ローカル検索レイテンシの中央値は1.6 msでした。プレーンなFTS5にワークスペーストポロジを追加しても、このコーパスではヒット率は変わりませんでしたが、MRRが0.839から0.867に改善され、リポジトリの帰属精度が向上し（0.93 → 1.00）、無関係なリポジトリからの結果が排除されました（クエリあたり0.20 → 0.00）。

コーパスは小さく、合成であり、クエリを書いた同じ人物によって書かれました。これが数字の読み方に何を意味するかは、docs/evaluation.mdに詳述されています。

制限事項

正直なリストの完全版は KNOWN_LIMITATIONS.md です。最も重要な3つは以下の通りです。

• 検索はキーワードベースです。 FTS5はトークンにマッチします。字句の重複が全くない完全に言い換えられたクエリは見逃す可能性があります。構造的なブーストは部分的にしか補償しません。

• 新しさは検証ではありません。 これは「参照されたファイルが変更されたか？」という問いには答えますが、「この主張はまだ正しいか？」には決して答えません。変更されていないファイルでの動作の変更は見えません。

• 関係は宣言され、推論されるものではありません。 宣言されていない関係はランキングから見えません。

Roadmap

コアループの改善度合いの高い順に並べています。

1. ハーネスの stop フックによる自動セッション終了（現在は手動）。

2. バージョン間および codex / gemini ハーネスにおける Xirp アダプターの堅牢化。

3. 競合検出と置き換え提案 — スキーマは両方をサポートしていますが、何も入力されていません。

4. 既存の CatalogProvider シームの背後での Backstage / Portal の catalog-info.yaml インポート。

5. ほぼ重複した所見を含む、より難しい評価用コーパス。トポロジーが順序付けだけでなく 発見 に役立つかどうかをテストするため。

Contributing

CONTRIBUTING.md を参照してください。pnpm typecheck && pnpm lint && pnpm test が成功し、pnpm demo がクリーンなクローンから認証情報なしで動作する必要があります。

Attribution and non-affiliation

wctx は、Xirp、Spotify Portal、Backstage、MCP の公開アイデアに触発された独立したオープンソースの実験です。

Spotify との提携や推奨はありません。

比較表に記載されているプロジェクトのソースコードは一切コピーされていません。Backstage の Component/System の区別はデザインのインスピレーションとして使用されており、ランタイム依存関係としてではなく、Backstage インスタンスは必要ありません。

License

MIT。 LICENSE を参照してください。