Contexo

Contexo

プロジェクトごとに管理する、AI エージェントの知識のための GitHub です。

開発者が AI エージェントとあるトピックを深く調査しても、その結果である判断、採用しなかった代替案、行き止まりは、その開発者のセッションにしか残りません。Contexo を使うと、チームで整理した知識を共有できるため、すべてのチームメンバーのエージェントが、同じ基準から作業を始められます。知識を再導出する（あるいは、より悪い形で導出する）必要はありません。

仕組み

各プロジェクトには、Markdown ページを格納する .contexo/ ディレクトリが用意されます（llm-wiki と同じ階層構造：raw/sessions/、wiki/concepts/、wiki/entities/、wiki/analyses/ と、常に読み込まれる index.md）。各ページには、作成者、エージェント、タグ、reasoning_summary を記載した YAML フロントマターがあります。

ctx push は選択したページを Contexo サーバーにアップロードし、ctx pull はページを取得します。サーバーの内部では Git リポジトリが使われています。各 push は作成者情報が付いた実際のコミットとなるため、履歴とタイムラインをそのまま利用できます。また、同時書き込みによって変更が分岐した場合は、両方のバージョンを含む 409 が返されます。

エージェントは MCP ツールを介して、自然言語の指示に従って同期を実行します。ユーザーが 「Stripe の知識を contexthub に同期して」 と言うと、エージェントは ctx_push(feature="stripe") を直接呼び出します。

処理の流れ

Dev A's Claude  →  writes wiki/concepts/stripe-subscription.md
                   (including "## Agent Reasoning" — what was considered & rejected)
                ↘
                  ctx push --feature stripe   →   Contexo server (git-backed)
                                                  Dev A authored sha abc123
                                                ↗
Dev B's Claude  ←  ctx pull                ←
                ↓
                  MCP: reads ctx://index, then ctx://wiki/stripe-subscription
                  Sees Dev A's reasoning. Doesn't repeat the dead-ends.

CLI

セットアップ

ctx init                       Create .contexo/, wire MCP (Claude + Cursor if found), install Stop hook
ctx detach [--keep-knowledge]  Reverse `ctx init` (purges .contexo/ by default)
ctx login                      Browser flow: sign in once, mint a token, done
                               (alias for `ctx auth login`; --no-browser to paste)
ctx join <invite-key>          Join an existing repo with a ctxi_… invite key
ctx remote set <url>           Point at a Contexo server
ctx remote set-repo [<id>]     Set the repo ID (interactive picker if omitted)
ctx remote get                 Show current server + repo

同期

ctx push [--feature X] [--tag Y] [--type concept|entity|source|analysis] [--dry-run]
         [--yes] [--show-diff] [--no-preview]
ctx pull [--full]
ctx status                     Local vs server delta
ctx log                        Server timeline (who changed what when)

push の前に、ctx push は各ファイルを [NEW]、[EDIT]、[SAME] としてプレビューし、push によってサーバー上で変更される内容を、セクションごとに要約して表示します。[EDIT] の行がある場合は、確認を求めます。確認を省略するには --yes を指定します（非対話型の使用では必須です）。--show-diff を指定すると、セクションごとの差分全体がインラインで表示され、--no-preview を指定すると、往復処理全体を省略します。

ページの変更履歴を調べる

ctx history <slug> [--type=...] [--limit=N]    Commit timeline for one page
ctx diff <slug> [--from=<sha>] [--to=<sha>]    Section-aware diff between two
                [--type=...] [--json] [--blame]versions (defaults to parent..head)
ctx diff <slug> --local                        Diff your local copy vs server HEAD
                                               (what `ctx push` would change)
ctx evolution <slug> [--limit=N] [--show-diff] Full trajectory in one call: every
                     [--type=...] [--json]     commit + its per-commit diff
                     [--blame]

--blame は、各セクションに見出しを最初に追加したコミットを注釈として表示します（ctx diff と ctx evolution の両方で使用できます）。「このセクションを書いたのは誰？」という質問を調べる際に便利です。

エージェントとの連携

ctx mcp                        Start the MCP server for the local agent (stdio)
ctx mcp install [--tool=X]     Wire the MCP server into an agent: claude|cursor|codex|all
ctx mcp uninstall [--tool=X]   Remove the MCP server wiring
ctx mcp status                 Show agent integrations (MCP + capture hook)
ctx mcp guide                  How to add Contexo to other agents (Windsurf, OpenCode, Hermes, ...)
ctx hooks install|uninstall|status [--tool=claude|codex|cursor|all]   Manage the capture hook
ctx capture status             Show pending capture buffers

対応エージェント（MCP）

エージェント	読み込む MCP 設定	設定方法
Claude Code	./.mcp.json（プロジェクト）	ctx init
Cursor	./.cursor/mcp.json（プロジェクト）	Cursor が検出された場合は ctx init、それ以外は ctx mcp install --tool=cursor
Codex	~/.codex/config.toml（グローバル）	ctx mcp install --tool=codex（グローバルファイルを変更する前に確認します）

ctx mcp サーバーは標準入出力を使う通常の MCP サーバーなので、MCP 対応のエージェントであればどれでも利用できます。ctx init が自動設定するのはプロジェクトローカルの設定のみです（Claude は常に、Cursor は検出された場合）。Codex のグローバル設定は、ctx mcp install --tool=codex でオプトインします。その他のエージェントやハーネス（Windsurf、OpenCode、Hermes、OpenClaw など）については、ctx mcp guide を実行すると、ツールごとの正確な MCP 設定を確認できます。ターンごとの キャプチャ（Stop フック）は、現在 Claude Code、Codex、Cursor で動作します（ctx hooks install --tool=…。エージェントが検出された場合は ctx init が自動でインストールします）。

メンテナンス

ctx update [--check]           Self-update to the latest release (--check: report only)
ctx version [--short]          Print the installed version

ターミナル出力

ctx はターミナル上では出力に色を付け、それ以外ではプレーンテキストを表示するため、パイプやリダイレクトを使っても解析しやすい形式が保たれます。機械向けのインターフェースである ctx mcp、ctx capture turn、シェル補完、--json、ctx version --short では、スタイル情報は一切出力されません。

NO_COLOR=1        Disable colour entirely (honoured automatically)
CTX_THEME=light   Use the light-background palette (default: dark)
CTX_ASCII=1       Use ASCII marks instead of ✔ ▲ ✖ ● (for consoles lacking the glyphs)

MCP

リソース（読み取り専用）：

• ctx://index — 常に読み込まれるナレッジインデックス
• ctx://tags — タグとページの対応表
• ctx://wiki/{slug} — 概念／エンティティ／分析ページ
• ctx://raw/{session-id} — raw/sessions/ 内の生セッション
• ctx://search?q=&type=&tag= — 部分一致とタグ／タイプによるフィルター

ツール（エージェントから呼び出し可能）：

• ctx_write_page — フロントマター付きのナレッジページを書き込む
• ctx_push、ctx_pull、ctx_status — チームサーバーと同期する
• ctx_history、ctx_diff — 編集前にページの変遷を確認する （行単位の git diff ではなく、構造化されたセクション単位の差分）
• ctx_evolution — 1 回の呼び出しでページの全履歴（すべてのコミットと差分）を表示する。 編集前に全体の経緯を確認したい場合に使用します

エージェントが ctx://wiki/<slug> を読み込み、そのページが前回の ctx pull 以降にサーバー上で変更されている場合、応答の先頭に新しい内容を要約する <DRIFT_NOTICE> ブロックが付加されます。エージェントは確認を忘れずに、編集前に変更を把握できます。確認を無効にするには CONTEXO_DRIFT_DISABLE=1 を設定します。ctx status でも変更のあるページが一覧表示されます（確認を省略するには --no-drift を渡します）。

ctx_push で 409 が発生した場合（ほかのユーザーが先にプッシュした場合）、ツールは祖先・自分・サーバーの各バージョンと、競合するセクションの一覧を含む <MERGE_REQUIRED> 指示を返します。エージェントは ctx_write_page で統合したバージョンを書き込み、ctx_push を再実行します。ローカルの同期状態は自動更新されるため、同じ理由で再プッシュが 409 になることはありません。

インストール

Linux、macOS、Windows 向けのビルド済みバイナリ（amd64 + arm64）を用意しています。Go ツールチェーンは不要です。

最も簡単な方法（1 行で実行でき、PATH も自動設定）：

# macOS / Linux
curl -fsSL https://raw.githubusercontent.com/sugihAF/Contexo/main/scripts/install.sh | sh

# Windows (PowerShell)
iwr -useb https://raw.githubusercontent.com/sugihAF/Contexo/main/scripts/install.ps1 | iex

これらのコマンドは、最新の GitHub Release からチェックサム検証済みのバイナリをダウンロードし、ユーザーが書き込み可能なディレクトリ（~/.local/bin、または Windows では %LOCALAPPDATA%\Programs\contexo）に配置します。必要に応じて、そのディレクトリを PATH に追加します。冪等性があるため、再実行しても安全です。

手動（自分でバイナリをダウンロード）： Releases page からプラットフォームに合ったアーカイブをダウンロードし、checksums.txt と照合して検証したうえで、ctx を展開し、PATH に配置します。

Go を使用（すでにツールチェーンがある場合）：

go install github.com/sugihAF/contexo/cmd/ctx@latest

go install でビルドした場合、バージョンは dev と表示され、自動更新できません。アップグレードするには、スクリプトで再インストールするか、go install を再実行してください。

更新

ctx update           # download + install the latest release in place
ctx update --check   # just report whether a newer version exists
ctx version          # show the installed version

ctx update は、新しいバイナリに置き換える前に、そのチェックサムを検証します。対話型コマンドの実行時には、新しいバージョンが利用可能な場合、ctx から 1 行の通知が表示されます。通知を非表示にするには CONTEXO_NO_UPDATE_CHECK=1 を設定します。

ソースからビルド（サーバー + CLI）：

# Linux / macOS
go build -o bin/ctx ./cmd/ctx
go build -o bin/contexo-server ./cmd/contexo-server

# Windows (PowerShell)
go build -o bin\ctx.exe .\cmd\ctx
go build -o bin\contexo-server.exe .\cmd\contexo-server

ctx CLI はどこでも実行できます。contexo-server バイナリは、チームの Contexo インスタンスで実行されるもので、通常は docker/ 内の Docker セットアップを通じて実行します。

サーバーを実行（ホストへのインストール）：

# Linux / macOS
CONTEXO_DATA_ROOT=/var/contexo/repos PORT=8080 ./bin/contexo-server

# Windows (PowerShell)
$env:CONTEXO_DATA_ROOT="C:\contexo\repos"; $env:PORT="8080"; .\bin\contexo-server.exe

サーバーは git を呼び出すため、git が PATH に含まれている必要があります。Docker イメージ（docker/Dockerfile）には git が同梱されています。

アンインストール

プロジェクトごと — 特定のプロジェクトから Contexo を削除します。

ctx detach                   # prompts before purging .contexo/, MCP entries (Claude/Cursor/Codex), .gitignore line, Stop hook
ctx detach --keep-knowledge  # remove the integration but preserve .contexo/
ctx detach -y                # skip the confirmation

ローカルのページがまだプッシュされていない場合、ctx detach は警告を表示するため、先に ctx push を実行できます。

CLI 自体 — インストーラーが配置したバイナリを削除します。

# macOS / Linux
rm ~/.local/bin/ctx

# Windows (PowerShell)
Remove-Item "$env:LOCALAPPDATA\Programs\contexo\ctx.exe"

# installed with `go install` instead? remove it from there:
rm "$(go env GOPATH)/bin/ctx"      # ctx.exe on Windows

ドキュメント

実例を交えた、すべての CLI コマンドと MCP ツールの完全なドキュメントは、docs.contexo.live にあります。

• docs/usage.md — 管理者向けセットアップ + 開発者向けオンボーディング + 日常のワークフロー
• docs/vision.md — Contexo の概要とページ形式

ドキュメントのコマンド一覧を再生成する

ドキュメントサイトでは、実際の cobra ツリーの JSON スナップショットからフラグの表と MCP スキーマを生成しているため、リファレンスがコードと食い違うことはありません。コマンド、フラグ、または MCP ツールを変更したときは、リリースの準備の一環として、必ず再生成してください。

go run -ldflags "-X github.com/sugihAF/contexo/internal/version.Version=$(git describe --tags --abbrev=0)" \
  ./cmd/ctxdocs > ../contexo-landing/apps/docs/src/data/contexo-cli.json

-ldflags のスタンプは重要です。指定しないと、スナップショットに "version": "dev" が記録され、ドキュメントサイトの「ctx に対して生成」という見出しが元に戻ってしまいます。再生成後は、ターミナルトランスクリプトも再キャプチャしてください。contexo-landing のチェックアウトから npm run capture --workspace apps/docs を実行します。そうしないと、サイトに前回のリリースの出力が表示され続けます。

cmd/ctxdocs はビルド時専用のツールです。.goreleaser.yaml がビルドするのは ./cmd/ctx だけなので、リリースバイナリには含まれません。