korg-ledger

英語 · 简体中文 · 繁體中文

korgex

ターミナルで使えるAIコーディングの相棒 — 作業の証拠もきちんと残します。

korgexに英語でやりたいことを伝えるだけです。たとえば 「失敗しているテストを修正して」「ヘルスチェックのエンドポイントを追加して」 と頼めば、コードを読み、変更を加え、テストを実行し、何をしたのかを正確に示してくれます。無料のオープンソースで、お好みのAI（Claude、ChatGPT、Gemini、Grok、ご自身のコンピューターで動かすプライベートモデルなど）と連携するため、特定の企業に縛られることはありません。

korgexの特長： 実行したすべての内容が、後から確認できる改ざん防止記録に保存されます。誰かがその記録をたった1文字でも変更すれば、korgexはそれを証明できます。信頼できると期待するだけでなく、監査できるコーディングアシスタントです。

_{開発者向け：ターミナルネイティブで、計画を優先し、AnthropicとOpenAIの両方のツール利用プロトコルに対応。OpenAIまたはAnthropic互換モデル（Ollamaを介したローカルモデルを含む）で動作し、あらゆるMCPサーバーに接続できます。ライブストリーミングに対応し、すべての実行をハッシュチェーン化された因果関係台帳に記録します。記録は korgex verify で検証できます。MITライセンスです。}

$ korgex "add a /healthz endpoint that returns 200 with uptime"
➤ Read(file_path=/app/routes.py)
➤ Edit(file_path=/app/routes.py, old_string=..., new_string=...)
➤ Bash(command=pytest tests/test_routes.py -q)
✓ Added GET /healthz returning {"status": "ok", "uptime_seconds": ...}

$ korgex verify
  ✓ ledger intact — 7 events, hash-chain + causal DAG verified

---

目次

• インストール
• クイックスタート
• REPL — 対話しながら作業
• 仕組み
• 検証可能な推論
• ツール
• 機能
• 安全性とサンドボックス
• CLI リファレンス
• 環境変数
• マルチモデルルーティング
• MCP 連携
• プラグイン
• ストリーミング TUI
• アーキテクチャ
• プロジェクト構成
• 開発とテスト
• ビルドとリリース
• トラブルシューティング
• 既知の制限事項
• ライセンス

---

インストール

PyPI から（推奨）

pip install -U korgex          # or, for an isolated global CLI:
uv tool install korgex@latest

Python ≥ 3.10 が必要です（3.10、3.11、3.12、3.13 でテスト済み）。

ソースから／最新の main

git clone https://github.com/New1Direction/korgex.git && cd korgex && pip install -e .
# or, without cloning:
pip install git+https://github.com/New1Direction/korgex.git

---

クイックスタート

# 1. Connect a provider (interactive — saves to ~/.korgex/config.json)
korgex setup
# …or just export a key; any of these works:
export ANTHROPIC_API_KEY="sk-ant-..."
export OPENAI_API_KEY="sk-proj-..."
export KORGEX_API_KEY="sk-or-v1-..." KORGEX_API_URL="https://openrouter.ai/api/v1"   # OpenRouter
export KORGEX_API_URL="http://your-gpu-box:8000/v1"   # self-hosted vLLM/llama.cpp → korgex --model Qwen2.5-Coder-32B "…"

# 2. Run the agent on a naked prompt
korgex "fix the failing test in tests/test_auth.py"

# 3. Or pick a model / mode
korgex --model claude-sonnet-4-6 "refactor src/handler.py"
korgex --mode plan "design a rate limiter for the API"
korgex --quiet "list the python files in src/"     # no TUI — pipe-friendly

# 4. Prove the run wasn't altered afterward
korgex verify

プロンプトを指定せずに korgex をそのまま実行すると、対話型 REPL が起動します。

---

REPL — ここでライブに作業

引数なしで korgex を実行すると、ストリーミング形式のマルチターンセッションが始まります。MCP サーバーに接続し、プロジェクトのルールを読み込み、セッションごとの巻き戻しログを保持します。

スラッシュコマンド

コマンド	内容
/loop <task>	タスクリストを無人で実行します。完了するまでターンごとに自動で続行します。上限が設定されており、Ctrl-C で停止できます。
/diff [n]	直近のターン（またはターン n）での変更を色付きで表示します。
/rewind [n]	元に戻せるポイントを一覧表示するか、プロンプト n より前の状態にファイルを復元します。
/skills · /skills curate	korgex が習得したスキル（✦）を一覧表示します。curate は重複に近いスキルを統合します。
/tasks · /jobs	ライブのタスクリストと、バックグラウンドのシェルジョブを表示します。
/plan [on|off]	プランモードを切り替えます。エージェントのプランを承認するまで読み取り専用です。
/model [id]	料金付きのモデルメニューを表示するか、セッション中に使用中のモデルを切り替えます。
/verify · /cost	セッションの記録を検証し、記録されたトークンから推定費用（$）を表示します。
/resume [id]	以前のセッションのトランスクリプトをコンテキストに読み込み、中断したところから続行します。
/<name> [args]	カスタムコマンドを実行します。.korgex/commands/ 内の Markdown プロンプト、または /code-review、/build-fix、/checkpoint などの組み込みコマンドを実行します。
/clear · /help · /exit	会話をリセット · ヘルプを表示 · 終了します。

インラインショートカット

• @path/to/file — ファイルを指定すると、その内容がターンに取り込まれます：refactor @src/auth.py to use @src/db.py。
• !command — その場でシェルコマンドを実行します：!git status、!pytest -q。

プロジェクトルール。 korgex init は AGENTS.md を作成します。korgex は各セッションでこれを自動的に読み込み、さらに親ディレクトリ内のネストされた AGENTS.md と .korgex/rules/*.md も読み込むため、プロジェクトのスタイルに従います。

プロンプトキャッシュにより、システムプロンプトとツールがターンをまたいで保持されます（OpenAI/Gemini/Grok/DeepSeek では自動、Claude/Qwen では cache_control のブレークポイントを使用）。KORGEX_CACHE_STATS=1 を設定すると、ターンごとのキャッシュヒットを確認できます。各ヒットは記録にも残るため、korgex cost ではキャッシュされたトークンに実際の割引料金を適用し、キャッシュによる節約額も表示します。これは korgex verify で検証できます。

---

仕組み

flowchart TD
    U["You — prompt or REPL"] --> CLI["korgex CLI / REPL"]
    CLI --> AG["KorgexAgent loop<br/>plan → act → verify"]
    AG -->|model id| PB{Provider}
    PB -->|"claude / anthropic/*"| ANT["Anthropic SDK"]
    PB -->|everything else| OAI["OpenAI-compatible SDK<br/>OpenAI · OpenRouter · Ollama · Grok · DeepSeek"]
    ANT --> TR["Tool router<br/>(src/tool_abstraction.py)"]
    OAI --> TR
    TR --> BT["Built-in tools<br/>Read · Edit · Bash · Grep · …"]
    TR --> MCP["MCP servers<br/>(any in mcp.json)"]
    TR --> CA["CodeAct kernel<br/>code = the action (opt-in)"]
    BT --> LED[("korg-ledger<br/>hash-chained + causal DAG")]
    MCP --> LED
    CA --> LED
    LED -. "verify · trace · why · cost" .-> U

エージェントは設計上、特定のプロバイダーに依存しません。ツールスキーマはプロバイダーごとに変換され（Anthropic では {name, description, input_schema}、OpenAI では {type:"function", function:{…}}）、レスポンスは共通の形式に正規化され、ツールの結果はプロバイダーが想定するメッセージ構造に合わせて整形されます。組み込み、MCP、CodeAct のいずれのツール呼び出しも、実行時に記録へ書き込まれます。

---

検証可能な認知

簡単に言うと： korgex は、読み込むファイルや実行するコマンドなど、行うすべてのことを記録簿に記録します。各記録は、チェーンのリンクのように直前の記録とつながって封印されるため、後から誰かが記録を一つでも変更、追加、削除すると、チェーンが目に見えて壊れます。その結果、AI が実際に何をしたかを示す、誠実で検証可能な証拠が得られます。監査、コンプライアンス、デバッグ、あるいは安心のために役立ちます。私たちの知る限り、これを行うコーディングエージェントはほかにありません。

内部では、各実行を不透明なログではなく、改ざん検知可能な因果台帳に記録します。各イベントは、直前のイベントにハッシュでリンクされ（prev_hash／entry_hash）、さらに原因となったイベントにも因果関係でリンクされます（triggered_by）。そのため、セッション全体が改ざんされていないことを暗号学的に証明でき、編集、削除、並べ替え、挿入があれば検知し、問題のイベントを特定できます。

flowchart LR
    subgraph chain["korg-ledger — each event hash-linked to the last"]
      direction LR
      E0["prompt<br/>a1f3"] --> E1["Read<br/>7c0e"] --> E2["Edit<br/>b42d"] --> E3["Bash: pytest<br/>9d11"]
    end
    E3 --> V{{"korgex verify"}}
    V -->|chain intact| OK["✓ proven unaltered"]
    V -->|"edit / splice / reorder"| BAD["✗ localized to the bad event"]

korgex verify                 # prove the recorded run wasn't altered (exit 0/1, CI-friendly)
korgex trace                  # the causal trace — what the agent did + what caused it
korgex why src/auth.py        # walk the causal chain back from a file change to its prompt
korgex recall "rate limiter"  # pull lean, verified context for a query — retrieve, don't carry
korgex cost                   # estimated $ spend for the session, from recorded token counts
export KORG_LEDGER_HMAC_KEY=… # make the chain tamper-PROOF, not just tamper-evident

メモリのドリフト。 記憶された事実は、情報源の sha256 ベースラインにひも付けられています。そのため、情報源に変更が加わると、古くなったことが正確なシグナルとして示され、保持／更新／破棄の判断自体も台帳に記録されます。

korgex drift                  # scan persistent memories for drift vs their source baselines (exit 0/1)

既存の監査ログに証明を添えて共有できます。 korgex audit を使うと、すでに実行したセッション（Claude Code のログを自動検出します）を検証可能なチェーンにインポートできます。--html を追加すると、受信者のブラウザーで自らを再検証する単一の自己完結型ファイルが作成されます。意図的にチェーンを壊して誰でも証拠を実感できる、ライブの改ざんテストも含まれます。セットアップも、導入の同意も、ネットワーク呼び出しも不要です。

korgex audit --html audit.html
#   audited <session> → 2,319 ledger events
#   chain:  ✓ INTACT — tamper-evident, cryptographically verifiable
#   report: audit.html  ← open in any browser; it re-verifies itself

korgex import transcript.json     # replay any vendor's session into a korg-ledger@v1 journal
korgex trajectory --out train.jsonl   # export the journal as a provenance-stamped training trajectory

証明書を相手に渡せます。 korgex receipt は、実行内容を証明する単一のポータブルファイルを作成します。イベント（そのためオフラインで検証できます）、平易な言葉による --claim、概要、そして自分の鍵を使って誰が証明したかを示す任意の --sign が含まれます。受信者は korgex receipt verify <file>（終了コード 0／1）で確認するか、--html を開いて自動的に再検証される様子を見るだけです。スクリーンショットではなく、証明可能な成果物です。

korgex receipt --claim "shipped /healthz + passing test" --sign --html receipt.html
#   ✓ receipt minted — 5 events, 3 tool calls, 2 files, $0.0078
#   signed by b251a84c… (your korgex identity) · tip 46263017…
#   receipt.html  ← open in any browser; it re-verifies itself

korgex receipt verify receipt.korgreceipt.json   # ✓ VALID / ✗ INVALID (CI-gateable)

CI でゲートできます。 verify-ledger GitHub Action を任意のリポジトリに追加すると、エージェントの台帳または証明書を検証できない場合にビルドを失敗させられます。生成元のツールを一切信頼する必要はありません。

- uses: New1Direction/korgex/.github/actions/verify-ledger@main
  with:
    path: ".korg/journal.json"            # or "**/*.korgreceipt.json"
    pubkey: ${{ vars.KORG_SIGNER_PUBKEY }}  # optional: pin the signer

モデルごとのリアルタイムな信頼性データについては、Self-Coding Bench をご覧ください。

---

ツール

エージェントには、モデル向けの高水準ツールが 23 個（Claude Code スタイル）表示されます。それぞれに、使い方、エッジケース、アンチパターンを網羅する詳細な説明があります。内部では、これらのツールが約 60 個のハンドラー（src/tools_impl.py）に処理を振り分けます。

ツール	目的
Read · Write · Edit	ファイルを読み込みます。作成／上書きします。文字列をピンポイントで置換します（内部では SEARCH/REPLACE に変換されます）。
Bash · BashOutput	タイムアウトを指定してシェルコマンドを実行します。長時間実行されるバックグラウンドジョブの状態を確認します。
Grep · Glob	正規表現で内容を検索します（利用可能な場合は ripgrep を使用します）。パターンに一致するファイルを一覧表示します。
Agent · Orchestrate	サブタスクをサブエージェントに委任します。サブエージェントの並列 DAGを実行します（機能をご覧ください）。
TaskCreate · TaskUpdate	複数ステップの作業をタスクリストとして追跡し、更新します。
AskUserQuestion	任意で複数選択肢を含む、確認の質問をします。
Skill · ToolSearch	インストール済みのスキルを呼び出します。キーワードを使って実行時にツールを検索します。
WebFetch · WebSearch	URL を読みやすいテキストとして取得します。ウェブを検索します。
Recall	セッションをまたぐメモリから、関連する事実を取得します（ドリフトをチェックします）。
Retrieve	content-ref に封印された大きなツール結果の正確なバイト列を取得します。
BusSend · BusInbox	検証可能なエージェントメッセージバスで送受信します（改ざん検知可能な調整機能）。
python (オプトイン)	CodeAct — Python をアクションとして実行し、ツールを関数として利用できます。
NetCapture (オプトイン)	自分で作成したアプリの HTTP(S) 通信を監査可能な形でキャプチャします。cURL を使わずに API 呼び出しをデバッグできます。
RemoteSignTip (オプトイン)	自分が管理するリモート署名者を使って台帳の先端に署名します（鍵はホスト外に保管されます）。

---

機能

コアとなるファイル／シェル／検索のループに加え、korgex にはいくつかの高度なシステムが搭載されています。リスクの高い機能はオプトインで、デフォルトでは無効（環境変数を1つ設定するだけ）で、どの機能も検証可能な台帳に記録されます。

• CodeAct — アクション空間としてのコード（KORGEX_CODEACT_ENABLE=1）。永続的で、燃料計測機能を備えた Python カーネルです。モデルがツールを関数として呼び出すコードを記述するため、ターンごとにツールを1つ呼び出す方式よりも効率的です。ネストされた実行トレースは台帳に記録されます。有効にすると、バックエンドが存在する環境ではデフォルトでカーネルがOS によってサンドボックス化されます。Linux では bubblewrap、macOS では Seatbelt を使用し、ネットワークなし＋ワークスペースへの書き込みのみ（KORGEX_CODEACT_ISOLATION=auto／required／off）に制限します。
• マルチエージェント・オーケストレーション（KORGEX_PARALLEL_AGENTS と Orchestrate ツール）。サブエージェントの DAG を並行して実行します。台帳ネイティブで検証可能であり、ネストは厳密に1階層までに制限され、各サブ実行は親の下にチェーンされます。
• 監査可能なネットワークキャプチャ（KORGEX_NETCAPTURE_ENABLE=1）。作成したアプリ／スクリプトを、ローカル CA 署名のキャプチャプロキシ経由で実行し、すべての HTTP(S) 通信の構造化・秘匿化済みトレースを取得します。プロセス単位でキャプチャのみを行い、記録前にシークレットをマスクします。
• 検証可能なブラウザー（KORGEX_BROWSER_STEALTH、KORGEX_BROWSER_EVAL）。CDP 駆動のスナップショット→操作型ブラウザー自動化で、台帳に記録されます。ステルス機能はオプトインです。
• リモート署名（KORGEX_REMOTE_SIGNER_*）。自身が所有し、管理する HTTP 署名サービスを介して台帳の先端に署名できるため、署名キーをエージェントのホスト以外（別のマシンや HSM）に置けます。フェイルクローズ方式で、ベアラートークン、ホスト許可リスト、任意の公開鍵ピンニング、ローカル署名検証に対応します。
• 検証可能なエージェントバス（korgex bus、KORG_BUS_*）。エージェントは Ed25519 署名付きの改ざん検知可能な korg-ledger ジャーナルを介して連携します。「誰が何を言ったか」は主張ではなく署名によって示されます。
• リコール＋メモリー — ソースのベースラインとのドリフトチェックを行う、セッションをまたいだメモリーです（検証可能な認知）。
• ローカルモデル（korgex local）。ハードウェア対応アドバイザー（CPU／RAM／GPU／VRAM に基づき、llmfit 経由で適合度をスコア化した候補を順位付け。任意）を使って、ローカルの Ollama モデルをデフォルトとして設定できます。Apple Silicon では、korgex local --omlx により、稼働中の omlx MLX サーバー（OpenAI 互換、継続的バッチ処理＋階層型 KV キャッシュ）を対象にできます。引数なしでは、サーバーが提供しているモデルを一覧表示します。--omlx --use <model-id> を指定すると、そのモデルをデフォルトとして設定できます（デフォルト以外のポートを使う場合は --omlx-url を追加します）。korgex は推論を再実装するのではなく、ローカルのエンドポイントを参照するだけです。

---

安全性とサンドボックス

• 破壊的コマンドのガード（デフォルトで有効。KORGEX_COMMAND_GUARD）。ホワイトリスト優先で、引用符とコメントを考慮した Bash（および CodeAct ブリッジ）向けの安全策です。明らかに破壊的なコマンドを拒否します。ブロックは、台帳に改ざん検知可能な command_guard.block イベントとして記録されます。
• 送信／情報流出のガード（フラグモードではデフォルトで有効。KORGEX_EGRESS=off|flag|redact|block）。送信ツール（WebFetch／WebSearch／BusSend／browser_navigate／MCP／ネットワークを使用する Bash）を介して環境外に出るデータを、形式に基づいて検査します。シークレットの形式（台帳のマスキング機能と同じパターンを使用）や大きなエンコード済みデータを検出します。flag は警告し、egress.flag 判定を記録しますが、変更もブロックもしません（追加のみ）。redact は送信ペイロードが外部に出る前にシークレットをマスキングします。block は拒否します。検出内容はすべて、改ざん検知可能な台帳の判定として記録され、記録には検出された 形式 のみが含まれます。生のシークレットは記録からマスキングされるため、共有可能な台帳が情報流出経路になることはありません。KORGEX_EGRESS_ALLOW／KORGEX_EGRESS_DENY（カンマ区切りのホスト）で、宛先の制御をオプトインで有効にできます。
• Bash サンドボックス（KORGEX_SANDBOX=modal|docker|direct|auto）。シェル実行の隔離方法を制御します。
• CodeAct の OS 隔離 — コードカーネルはデフォルトでサンドボックス内で実行されます（Linux／bubblewrap・macOS／Seatbelt）。フェイルクローズにするには KORGEX_CODEACT_ISOLATION=required、無効にするには =off を設定します。
• 編集の確認。 重要なファイルに対する Edit／Write の差分は、TUI で [y/N] の確認を求めます。編集ポリシーは KORGEX_EDIT_POLICY で設定できます。
• 強力な機能はすべて、デフォルトではオプトインです。 CodeAct、NetCapture、リモート署名、ブラウザーのステルス機能は、明示的に有効にするまでオフです。

---

CLI リファレンス

$ korgex --help
usage: korgex [-h] SUBCOMMAND ...

korgex — autonomous coding agent. Pass a naked prompt to run the agent, or use a subcommand.

サブコマンド以外の引数はすべてプロンプトとして扱われます：korgex "create hello.txt with 'hi'"。

フラグ

フラグ	目的
--model MODEL	モデルを上書きします（例：claude-sonnet-4-6、gpt-4o、openai/gpt-4o-mini）。常に --mode より優先されます。
--mode {plan,execute,explore,review,debug,research}	モードに基づいてモデルを選択します（複数モデルのルーティングを参照）。
--mcp	起動時に mcp.json から MCP サーバーを読み込みます。
--quiet / -q	ストリーミング TUI を無効にし、最終結果のみを表示します。パイプ、スクリプト、CI で使用します。
--version / -V	korgex のバージョンを表示して終了します。
--resume	前回のセッションを再開し、検証可能な台帳からその会話履歴を再生します。プロンプトを指定すると、セッションを再開して実行します。引数なしの korgex --resume は、そのコンテキストで REPL を再度開きます。

サブコマンド

サブコマンド	動作
korgex setup	モデルプロバイダー（いずれか）に接続します。キーとデフォルトモデルを ~/.korgex/config.json に保存します。
korgex init	リポジトリ用のスターター AGENTS.md を生成します（スタックとテスト／ビルドコマンドを検出し、既存ファイルは上書きしません）。
korgex skills	スキルを一覧表示します。install <ref> ／ search <query> ／ adopt <dir> で、オープンな Agent-Skills カタログ から（ローカルディレクトリ、git URL、または owner/repo[@skill] を指定して）trust: installed として取得します。check ／ update [name|all] で git ソースのスキルを更新し、export <name|all> [claude|cursor|codex|<dir>] で korgex のスキル（自己学習したものを含む）を別のエージェントに出力します。
korgex sessions	このリポジトリの台帳にある最近のセッションを一覧表示します（korgex --resume で再開できます）。
korgex commands	カスタムスラッシュコマンド（組み込み、プロジェクト、ユーザー）を一覧表示します。REPL で /<name> と入力して実行します。
korgex local	このマシンに適したローカルモデルを提案し、必要に応じて接続します。
検証可能な認知
korgex verify [journal]	台帳のハッシュチェーンと因果 DAG が完全であることを検証します（終了コード 0／1、CI に対応）。
korgex trace	因果的な認知トレースを表示します。エージェントが行ったことと、その原因を確認できます。
korgex why <path>	因果チェーンをさかのぼり、ファイルが変更された理由をプロンプトまで追跡します。
korgex cost	台帳に記録されたトークン数から、セッションの推定費用（$）を表示します。
korgex drift	永続メモリをスキャンし、ソースのベースラインとの乖離を検出します（終了コード 0／1）。
korgex audit [--html f]	実行済みのセッションを、検証可能な台帳に監査します（Claude Code のログを自動検出します）。
korgex import <file>	別のベンダーのセッション記録を、korg-ledger@v1 ジャーナルに再生します。
korgex trajectory	ジャーナルを、検証可能で出所情報が付与されたトレーニング軌跡としてエクスポートします。
korgex bus	改ざん検知可能な korg-ledger ジャーナルを介して、検証可能なエージェントメッセージバスを提供します。
MCP と統合
korgex mcp	mcp.json 内の stdio またはリモート（URL と認証情報）サーバーを追加／一覧表示／削除して、MCP サーバーを管理します。
korgex mcp-server	korg-ledger MCP サーバーを実行します（stdio 経由の JSON-RPC）。任意の MCP ホストから検証／監査／インポートできます。
korgex diag <path>	ファイルの言語サーバー診断情報（エラー／型）を報告します。可能な範囲で実行します。
ダッシュボード／エディター
korgex acp	stdio 経由で korgex を Agent Client Protocol エージェントとして実行し、ACP エディター（Zed など）から操作できるようにします。ツール呼び出しのアクティビティと返信テキストをリアルタイムでストリーミングします。
korgex serve · dashboard	FastAPI ダッシュボードを起動します（デフォルトは 127.0.0.1:8090）。VS Code サイドカーを開くかどうかを選択できます。
korgex status · stop	バックグラウンドのバックエンドの状態を報告／終了します。
korgex install-extension	コンパイル済みの .vsix をローカルの VS Code にインストールします。

エディターからkorgexを操作する（ACP）

korgexはエージェントとしてオープンなAgent Client Protocolに対応しているため、ACP対応エディターから直接操作できます。エディターのエージェントパネルで、ベンダーを問わず検証可能なエージェントを利用できます。Zedでは、settings.jsonに外部エージェントとしてkorgexを追加します。

{
  "agent_servers": {
    "korgex": { "type": "custom", "command": "korgex", "args": ["acp"], "env": {} }
  }
}

Zedでは、各外部エージェントに"type": "custom"が必要です。これがないとZedはagent_serversブロック全体を拒否し（"missing field type"）、korgexが表示されません。Zedの（最小限のGUI）PATHからkorgexが見つからない場合は、commandにバイナリのフルパスを指定してください（例：~/.local/bin/korgex）。設定を編集すると、Zedはホットリロードします。それでもkorgexが表示されない場合は、Zedを完全に終了してから再起動してください。

次に、Agent PanelのNew Threadメニューからkorgexを選択します。動作中は、エディターにリアルタイムのtool_callアクティビティ（読み取り／編集／実行／検索のカードと、編集内容のインライン差分プレビュー）が表示され、返信テキストがストリーミングされます。これらは同じ改ざん検知可能な台帳によって裏付けられているため、korgex verifyでセッション全体を検証できます。（エディターはメッセージごとにプロンプトターンを処理します。埋め込みの@fileコンテキストと貼り付けたリソースも受け付けます。）

デフォルトでは、korgexは自由に動作します。エディターで編集を承認する（Allow / Allow-don't-ask-again / Rejectの選択肢を含むsession/request_permissionプロンプトを表示する）には、KORGEX_EDIT_POLICY=askを指定して実行します。

{ "agent_servers": { "korgex": { "type": "custom", "command": "korgex", "args": ["acp"], "env": { "KORGEX_EDIT_POLICY": "ask" } } } }

---

環境変数

コア

変数	用途	デフォルト
ANTHROPIC_API_KEY	モデル ID に「claude」が含まれるか、「anthropic/」で始まる場合に使用されます。	—
OPENAI_API_KEY	Anthropic 以外のモデルで使用されます。	—
KORGEX_API_KEY / KORGEX_API_URL	OpenAI 互換エンドポイント（OpenRouter、Ollama、vLLM など）用の汎用キーとベース URL です。	— / https://api.openai.com/v1
KORGEX_MODEL	--model と --mode のどちらも指定されていない場合のデフォルトモデルです。	claude-sonnet-4-6
KORGEX_PROVIDER	モデル ID の自動判定を上書きし、トランスポート（openai|anthropic）を強制します。	自動判定
KORGEX_MAX_ITERATIONS	エージェントループを中断するまでの最大反復回数です。	30
KORGEX_MCP	1 にすると、mcp.json から MCP サーバーを自動読み込みします。	未設定
KORGEX_SANDBOX	modal|docker|direct|auto — bash の分離方式です。	auto
KORGEX_DASHBOARD_HOST	ダッシュボードのバインド先ホストです。デフォルトは localhost です。認証を終端するプロキシの背後にある場合にのみ、0.0.0.0 を設定してください。	127.0.0.1

機能（オプトイン）

変数	用途
KORGEX_LEAN_CONTEXT · KORGEX_LEAN_CONTEXT_TOKENS	履歴全体を保持する代わりに、プロンプトに関連する、検証済みの簡潔な台帳コンテキストを挿入します（デフォルトの予算は 800）。これにより、小規模なモデルやセルフホスト可能なモデルでループを実行できます。
KORGEX_CODEACT_ENABLE · KORGEX_CODEACT_ISOLATION	CodeAct コードカーネルを有効にします。OS 分離は auto（デフォルト — 利用可能な場合はサンドボックスを使用：Linux/bubblewrap、macOS/Seatbelt）、required（安全側に倒して失敗）、off から選択します。
KORGEX_NETCAPTURE_ENABLE	監査可能な HTTP(S) キャプチャツールを有効にします。
KORGEX_PARALLEL_AGENTS	マルチエージェントオーケストレーションの並行数です。
KORGEX_REMOTE_SIGNER_TOKEN · _ALLOWED_HOSTS · _PUBKEY · _REQUIRE_HTTPS	リモート署名者の認証、ホスト許可リスト、固定キー、HTTPS の強制を設定します。
KORGEX_BROWSER_STEALTH · KORGEX_BROWSER_EVAL	ブラウザーのステルスモードを設定し、ページ内での evaluate を許可します。
KORGEX_COMMAND_GUARD	破壊的なコマンドのガードを切り替えます（デフォルトで有効）。
KORGEX_EDIT_POLICY	編集の確認ポリシーです。
KORGEX_WEBHOOK_SECRET · KORGEX_WEBHOOK_ALLOW_UNSIGNED	GitHub webhook の HMAC シークレットです。ローカル／開発用途で KORGEX_WEBHOOK_ALLOW_UNSIGNED=1 を明示的に設定しない限り、署名のない webhook は拒否されます。

台帳とバス

変数	用途	デフォルト
KORG_JOURNAL_PATH	永続的な JSONL 台帳です。コンテンツアドレス指定された blob はその隣に書き込まれます。	.korg/journal.jsonl
KORG_LEDGER_HMAC_KEY	設定すると、チェーンは HMAC キーで保護され、改ざんの証明が可能になります。単に改ざんの痕跡を検出できるだけではありません。	未設定
KORG_BUS_AGENT · KORG_BUS_JOURNAL · KORG_BUS_KEY	検証可能なバス用のエージェント ID、バスジャーナル、Ed25519 キーです。	—

プロバイダー判定ルール：モデル ID に「claude」が含まれるか、「anthropic/」で始まる場合は Anthropic SDK が使用されます。それ以外の場合は OpenAI 互換 SDK（OpenAI、OpenRouter、Ollama、DeepSeek、vLLM など）が使用されます。KORGEX_PROVIDER=openai を設定すると、claude／anthropic/* ID を OpenAI 互換エンドポイント経由で実行できます（例：OpenRouter 経由の Claude）。

---

マルチモデルルーティング

--mode は作業の種類に適したモデルを選択します。

モード	モデル	生成パラメーター
plan	Opus 4.7	max_tokens=64000、thinking={budget_tokens: 20000}、temperature=0.7
execute	Sonnet 4.6	max_tokens=64000、temperature=0.3
explore	Opus 4.7	max_tokens=32000、temperature=0.5
review	Sonnet 4.6	max_tokens=16000、temperature=0.3
debug	Haiku 4.5	max_tokens=16000、temperature=0.2
research	Opus 4.7	max_tokens=32000、temperature=0.7

明示的に指定した --model は、常に --mode より優先されます。どちらも指定しない場合のデフォルトは Sonnet 4.6 です。

korgex --mode plan "architect a multi-tenant billing system"
korgex --mode debug "trace why this 500 is happening"
korgex --mode execute "implement the plan we just made"

---

MCP 連携

簡単に言うと、MCP は AI 向けのオープンな「アプリストア」標準です。korgex はこれを使って、独自の接続処理を追加することなく、外部サービス（GitHub、ファイル、データベースなど）に接続できます。

korgex にはネイティブの MCP（Model Context Protocol）クライアントが含まれています。mcp.json に設定された MCP サーバーは、すべてエージェントのツールとして利用できるようになります。korgex mcp で CLI から管理できます（stdio、またはリモート URL と認証を使うサーバーの追加／一覧表示／削除）。また、korgex mcp catalog ／ korgex mcp add <alias> を使えば、プリセットを一つのコマンドで設定できます。知っておくと便利なものとして、korgex mcp add mise を実行すると、mise 独自のエージェント向けサーバーが接続されます。エージェントはプロジェクトのツールバージョン、環境変数、実行可能なタスク（および run_task）を取得でき、すべてレジャーを通じて検証できます。

korgex 自体も MCP サーバーです

korgex mcp-server は、検証可能な認知基盤を JSON-RPC/stdio 経由で公開するため、どの MCP ホスト（Claude Desktop、Cursor など）からも次の機能を呼び出せます。

• korg_verify — korg-ledger のジャーナルが改ざんされておらず、完全性が保たれていることを証明します。
• korg_audit — ホストエージェント自身の Claude Code ログを監査します（インポートと検証）。設定は不要です。
• korg_import — ベンダーのセッショントランスクリプトを、検証可能な連鎖型レジャーにインポートします。

{ "mcpServers": { "korg-ledger": { "command": "korgex", "args": ["mcp-server"] } } }

MCP Registry に登録されています — mcp-name: io.github.New1Direction/korg-ledger。

設定と使用方法

{
  "mcpServers": {
    "github":     { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-github"],     "env": { "GITHUB_TOKEN": "ghp_..." } },
    "filesystem": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"] }
  }
}

korgex --mcp "create a GitHub issue summarizing today's bug"

エージェントは起動時に各サーバーのツールを検出し、ユーザー向けのツール一覧に登録して、呼び出しを元のサーバーにルーティングします。サーバーの障害はログに記録されてスキップされるため、エージェントがクラッシュすることはありません。

---

プラグイン

フォークせずに korgex を拡張できます。register(registry) 関数を定義した .py ファイルを ~/.korgex/plugins/（グローバル）または <repo>/.korgex/plugins/（プロジェクト内）に配置すると、起動時にエージェントのループへフックされます。

# ~/.korgex/plugins/notify.py — ping me when a file is edited
def register(reg):
    @reg.on("post_tool")
    def on_edit(payload):
        call = payload["call"]
        if call["name"] in ("Edit", "Write"):
            print(f"  ✎ touched {call['args'].get('file_path')}")

ライフサイクルフック： on_user_prompt（各ターンの開始時）、pre_tool（ツールの実行前）、post_tool（ツールの実行後）、on_stop（実行終了時）。プラグインはプロセス内で実行され、完全なアクセス権を持つため、信頼できるものだけをインストールしてください。また、フェイルセーフです。インポートに失敗したもの、register がないもの、例外を発生させたものは記録され、起動をクラッシュさせることなくスキップされます。

---

ストリーミング TUI

stdout が TTY の場合、エージェントは Rich を使って出力をリアルタイムにストリーミングします。Anthropic の思考ブロックは薄いイタリック体で表示され、テキストは一文字ずつ表示されます。ツール呼び出しには一時的なスピナー（⠋ Read(file_path=src/foo.py)）が表示され、重要な編集では [y/N] による差分確認が行われ、Ctrl+C による中断にも適切に対応します（強制終了するには 2 回押します）。stdout がパイプに接続されている場合、CI 環境の場合、または --quiet を指定した場合、ストリーミングは自動的に無効になります。OpenAI／OpenRouter のストリーミングも同じレンダラーを経由します。ツール呼び出しの差分はチャンク間で蓄積されます。

---

アーキテクチャ

システム概要

flowchart TD
    U["You — CLI / REPL / ACP editor<br/>(src/cli.py · repl.py · acp.py)"] --> AG

    subgraph core["KorgexAgent loop — src/agent.py (plan, act, verify)"]
        AG["Agent loop: run_task()<br/>system prompt + memory + task list"]
        GATE["Per-call gates<br/>plan-mode · edit-policy · command / egress guard · hooks"]
        AG --> GATE
    end

    AG -->|"normalize tool-use shape"| PROV{"Provider<br/>(model id / KORGEX_PROVIDER)"}
    PROV -->|"claude family"| ANT["Anthropic SDK"]
    PROV -->|"everything else"| OAI["OpenAI-compatible SDK<br/>OpenAI · OpenRouter · Ollama · Grok · Nous · Venice · Gemini"]
    ANT --> GATE
    OAI --> GATE

    GATE --> TR["Tool router<br/>src/tool_abstraction.py"]
    TR --> BT["Built-in handlers<br/>file · Bash · search · git · GitHub · browser"]
    TR --> CA["CodeAct kernel<br/>Python-as-action, fuel/mem-metered (opt-in)"]
    TR --> MCP["MCP servers<br/>src/mcp_client.py"]

    BT --> LED
    CA --> LED
    MCP --> LED
    GATE -. "every decision + result" .-> LED

    LED[("korg-ledger · src/korg_ledger.py<br/>append-only · hash-chained · causal DAG")]
    LED --> HEAL["Test gate + self-heal<br/>src/test_gate.py · self_healing.py"]
    HEAL -->|"red, retry"| AG
    LED --> VERIFY["verify · trace · why · audit · receipt<br/>Ed25519 signing"]
    VERIFY --> U

ツールルーティング — モデル向けの安定した名前から内部ハンドラーへ

User tool call (LLM-visible):     Internal handler (src/tools_impl.py):
─────────────────────────────     ─────────────────────────────────────
Read(file_path=...)         →     tool_read_file(filepath=..., context=...)
Write(file_path=..., ...)   →     tool_write_file(filepath=..., ...)
Edit(file_path, old, new)   →     tool_replace_with_git_merge_diff(merge_diff="<<<<<<< SEARCH ...")
Bash(command=...)           →     tool_run_in_bash_session(command=...)

ルーター（src/tool_abstraction.py）は _TOOL_ROUTING から名前を検索し、param_map またはカスタム adapter を適用して、ハンドラーが受け付けない kwargs を除外し、context={'repo_root': cwd} を自動注入します。また、例外を {"error": ...} に変換するため、単一のツール障害によってループ全体が停止することはありません。MCP 由来のツールは _TOOL_ROUTING を経由せず、MCPServerManager.call_tool() を通じてディスパッチされます。

エージェントのループ

flowchart TD
    S(["prompt"]) --> SEND["LLM.send(messages, tools)"]
    SEND --> Q{tool calls?}
    Q -->|no| F(["final result"])
    Q -->|yes| RT["route_tool_call(name, args)"]
    RT --> REC["record event → korg-ledger"]
    REC --> APP["append tool_result to messages"]
    APP --> SEND

計画を先に行うシステムプロンプトは、エージェントに計画、検証、変更前の診断を促し、ビルド成果物を決して変更しないよう指示します（src/agent.py の SYSTEM_PROMPT）。レジャーはネイティブの Python で実装されており（src/korg_ledger.py、src/ledger_spec.py）、外部ランタイムは必要ありません。

---

プロジェクト構成

korgex/
├── src/
│   ├── agent.py              # KorgexAgent — main loop, provider branching, streaming
│   ├── cli.py · repl.py      # argparse dispatch · interactive REPL
│   ├── tool_abstraction.py   # USER_TOOLS registry + router + MCP integration
│   ├── tools_impl.py         # ~60 internal handlers (file ops, git, GitHub, web, …)
│   ├── model_router.py       # mode → model mapping (plan/execute/debug/…)
│   ├── korg_ledger.py · ledger_spec.py · signing.py   # verifiable ledger + Ed25519
│   ├── codeact/              # code-as-action kernel (fuel-metered, isolated, traced)
│   ├── orchestrate.py        # multi-agent DAG orchestration
│   ├── recall.py · memory.py · memory_drift.py        # cross-session memory + drift
│   ├── command_guard.py · sandbox.py                  # destructive-cmd floor · bash sandbox
│   ├── netcapture.py · remote_signer.py · browser.py  # opt-in capability modules
│   ├── structured_output.py · skills.py · local_model.py
│   ├── mcp_client.py · dashboard.py · interactive.py
│   └── ...
├── docs/                     # CLI reference, comparison, getting-started, tools-reference, …
├── spec/korg-ledger-v1/      # the ledger spec (SPEC.md, EVENTS.md)
├── tests/                    # ~1,657 passing tests
├── .github/workflows/        # Linux CI (3.10–3.13) + PyPI publisher (OIDC)
├── pyproject.toml
└── README.md

---

開発とテスト

git clone https://github.com/New1Direction/korgex.git && cd korgex
uv venv .venv && source .venv/bin/activate      # or python -m venv .venv
uv pip install -e ".[dev]"                       # pytest, build, ruff, …

ruff check src/                                   # lint
pytest -q                                         # the full suite

pyproject.toml がパッケージの依存関係に関する信頼できる唯一の情報源です。requirements.txt はソースチェックアウトとレガシーな自動化との互換性を保つためのミラーとして維持されています。開発には、追加機能を指定した編集可能インストールを推奨します。

テストスイートには 1,600 件以上のテストがあり、実際の LLM 呼び出しはありません（すべてユニットテストです）。プッシュと PR のたびに、Linux CI で Python 3.10、3.11、3.12、3.13 を対象に実行されます。主な対象領域：エージェントループ（ルーティング、プロバイダーのスキーマ、モード／モデルの解決、ループガード、停滞分類器、コンパクション）、ツール（あいまい一致を使った Edit、編集の鮮度、バックグラウンド Bash、ウェブ）、検証可能な台帳（ハッシュチェーン＋因果 DAG、編集箇所の秘匿、Ed25519 署名付きバス）、CodeAct（カーネルの分離、燃料、ツールブリッジ）、MCP（名前空間付きマルチサーバールーター、OAuth の更新、完全なラウンドトリップ）、プロンプトキャッシュ、スキル（信頼階層、自己学習、キュレーター）、REPL。

---

ビルドとリリース

リリースは自動化されています。pyproject.toml の version を更新し、CHANGELOG.md を更新して main にマージしたら、GitHub Release を作成します。すると PyPI 公開ワークフローが release: published をトリガーに起動し、OIDC Trusted Publishing を通じてアップロードします（デジタル証明書付き）。トークンを手動で扱う必要はありません。

gh release create vX.Y.Z --title "vX.Y.Z" --notes "…"   # → triggers .github/workflows/publish.yml → PyPI

ローカルでビルドして内容を確認するには、python -m build を実行し、続けて python -m twine check dist/* を実行します。

---

トラブルシューティング

korgex: No API key found — ANTHROPIC_API_KEY、OPENAI_API_KEY、KORGEX_API_KEY のいずれかを設定するか（OpenAI 以外のエンドポイントでは KORGEX_API_URL も設定してください）、korgex setup を実行してください。

ModuleNotFoundError: No module named 'anthropic'（または openai、rich）— 依存関係がインストールされていません。pip install -e . を実行してください（pyproject.toml に記載されたすべての依存関係がインストールされます）。

エージェントがツール呼び出しを延々と繰り返す — 上限を下げてください：export KORGEX_MAX_ITERATIONS=10 を実行し、--quiet を指定すると最終状態だけを確認できます。

--mcp の起動が遅い — クライアントは各サーバーに同期的に接続し、ハンドシェイクを待ちます。mcp.json に到達不能なエントリーがあると、それぞれタイムアウトしてからスキップされます。停止中のサーバーを削除するか、korgex mcp で管理してください。

verify が破損を報告する — それが本来の動作です。変更または継ぎはぎされたイベントを検出し、その位置を特定しています。報告された seq_id がチェーンの不整合が始まる位置です。

---

既知の制限事項

現時点で存在する制限事項です。PR を歓迎します。

• OpenAI のストリーミングでは、Anthropic よりレンダリングされるイベントが少なくなります。 Anthropic は思考ブロックとメッセージ差分の使用量を出力しますが、OpenAI が出力するのはテキストとツール呼び出しのチャンクだけです。どちらも正しくレンダリングされますが、TUI は Anthropic のほうが情報豊富です。
• ダッシュボードの認証は実装されていません。 デフォルトでは 127.0.0.1 にバインドされます。認証を終端するリバースプロキシを前段に設置せずに KORGEX_DASHBOARD_HOST=0.0.0.0 を設定しないでください。
• VS Code サイドカーはダッシュボード用のレガシーな付属機能です。 korgex の主なインターフェースはターミナル REPL です。

---

ライセンス

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

---

関連プロジェクト

• Model Context Protocol — korgex がクライアントとサーバーの両方として実装する、オープンな MCP 標準です。
• korg · korgchat — korg-ledger を中心とする、より広範なエコシステムです。
• llmfit — korgex local が基盤として利用する、ハードウェアを考慮したローカルモデルのアドバイザーです（任意）。