{ "markdown": "

\n \"korgex\n

\n\n

\n \"PyPI\n \"PyPI\n \"Python\n \"CI\"\n \"tests\"\n \"MCP\n \"License:\n

\n\n

\n English · 简体中文 · 繁體中文\n

\n\n# korgex\n\n**An AI coding teammate for your terminal — that keeps the receipts.**\n\nTell korgex what you want in plain English — *\"fix the failing test,\" \"add a healthcheck endpoint\"* — and it reads your code, makes the change, runs the tests, and shows you exactly what it did. It's free and open-source, and it works with whatever AI you prefer (Claude, ChatGPT, Gemini, Grok, or a private model running on your own computer), so you're never locked to one company.\n\n**Why it's different:** everything korgex does is saved to a tamper-proof record you can check later. If anyone alters that record — even by a single character — korgex can prove it. It's a coding assistant you can *audit*, not just hope to trust.\n\nFor developers: terminal-native, plan-first, speaks both the Anthropic and OpenAI tool-use protocols, runs on any OpenAI- or Anthropic-compatible model (incl. local via Ollama), connects to any MCP server, streams live, and records every run to a hash-chained causal ledger you can check with korgex verify. MIT-licensed.\n\n```bash\n$ korgex \"add a /healthz endpoint that returns 200 with uptime\"\n➤ Read(file_path=/app/routes.py)\n➤ Edit(file_path=/app/routes.py, old_string=..., new_string=...)\n➤ Bash(command=pytest tests/test_routes.py -q)\n✓ Added GET /healthz returning {\"status\": \"ok\", \"uptime_seconds\": ...}\n\n$ korgex verify\n ✓ ledger intact — 7 events, hash-chain + causal DAG verified\n```\n\n\n\n---\n\n## Table of Contents\n\n- [Install](#install)\n- [Quickstart](#quickstart)\n- [The REPL — live in it](#the-repl--live-in-it)\n- [How it works](#how-it-works)\n- [Verifiable cognition](#verifiable-cognition)\n- [Tools](#tools)\n- [Capabilities](#capabilities)\n- [Safety & sandboxing](#safety--sandboxing)\n- [CLI reference](#cli-reference)\n- [Environment variables](#environment-variables)\n- [Multi-model routing](#multi-model-routing)\n- [MCP integration](#mcp-integration)\n- [Plugins](#plugins)\n- [Streaming TUI](#streaming-tui)\n- [Architecture](#architecture)\n- [Project structure](#project-structure)\n- [Development & testing](#development--testing)\n- [Building & releasing](#building--releasing)\n- [Troubleshooting](#troubleshooting)\n- [Known limitations](#known-limitations)\n- [License](#license)\n\n---\n\n## Install\n\n### From PyPI (recommended)\n\n```bash\npip install -U korgex # or, for an isolated global CLI:\nuv tool install korgex@latest\n```\n\nRequires Python ≥ 3.10 (tested on 3.10, 3.11, 3.12, 3.13).\n\n### From source / latest `main`\n\n```bash\ngit clone https://github.com/New1Direction/korgex.git && cd korgex && pip install -e .\n# or, without cloning:\npip install git+https://github.com/New1Direction/korgex.git\n```\n\n---\n\n## Quickstart\n\n```bash\n# 1. Connect a provider (interactive — saves to ~/.korgex/config.json)\nkorgex setup\n# …or just export a key; any of these works:\nexport ANTHROPIC_API_KEY=\"sk-ant-...\"\nexport OPENAI_API_KEY=\"sk-proj-...\"\nexport KORGEX_API_KEY=\"sk-or-v1-...\" KORGEX_API_URL=\"https://openrouter.ai/api/v1\" # OpenRouter\nexport KORGEX_API_URL=\"http://your-gpu-box:8000/v1\" # self-hosted vLLM/llama.cpp → korgex --model Qwen2.5-Coder-32B \"…\"\n\n# 2. Run the agent on a naked prompt\nkorgex \"fix the failing test in tests/test_auth.py\"\n\n# 3. Or pick a model / mode\nkorgex --model claude-sonnet-4-6 \"refactor src/handler.py\"\nkorgex --mode plan \"design a rate limiter for the API\"\nkorgex --quiet \"list the python files in src/\" # no TUI — pipe-friendly\n\n# 4. Prove the run wasn't altered afterward\nkorgex verify\n```\n\nRun bare `korgex` with no prompt to drop into the interactive REPL.\n\n---\n\n## The REPL — live in it\n\nRun bare `korgex` for a streaming, multi-turn session. It connects your MCP servers, reads your project rules, and keeps a per-session rewind log.\n\n**Slash commands**\n\n| Command | What it does |\n|---|---|\n| `/loop ` | Grind a task list unattended — auto-continues turn after turn until done, with a hard cap (Ctrl-C stops). |\n| `/diff [n]` | Colored diffs of what changed in the last turn (or turn `n`). |\n| `/rewind [n]` | List undo points, or restore files to BEFORE prompt `n`. |\n| `/skills` · `/skills curate` | List skills korgex learned (✦); curate merges near-duplicates. |\n| `/tasks` · `/jobs` | The live task checklist; background shell jobs. |\n| `/plan [on\\|off]` | Plan mode — read-only until you approve the agent's plan. |\n| `/model [id]` | Show a priced model menu, or switch the live model mid-session. |\n| `/verify` · `/cost` | Verify the session ledger; show estimated $ spend from recorded tokens. |\n| `/resume [id]` | Reload a prior session's transcript into context and continue where you left off. |\n| `/ [args]` | Run a **custom command** — a markdown prompt from `.korgex/commands/` (or a built-in like `/code-review`, `/build-fix`, `/checkpoint`). |\n| `/clear` · `/help` · `/exit` | Reset the conversation · help · quit. |\n\n**Inline shortcuts**\n\n- **`@path/to/file`** — mention a file and its contents are pulled into the turn: `refactor @src/auth.py to use @src/db.py`.\n- **`!command`** — run a shell command right there: `!git status`, `!pytest -q`.\n\n**Project rules.** `korgex init` scaffolds an `AGENTS.md`; korgex auto-reads it — plus any nested `AGENTS.md` up the tree and `.korgex/rules/*.md` — every session, so it follows your house style.\n\n**Prompt caching** keeps the system prompt + tools warm across turns (automatic on OpenAI/Gemini/Grok/DeepSeek; `cache_control` breakpoints on Claude/Qwen). Set `KORGEX_CACHE_STATS=1` to see per-turn cache hits — and every hit is recorded on the ledger, so `korgex cost` prices cached tokens at their real discounted rate (and shows what the cache saved you), provable with `korgex verify`.\n\n---\n\n## How it works\n\n```mermaid\nflowchart TD\n U[\"You — prompt or REPL\"] --> CLI[\"korgex CLI / REPL\"]\n CLI --> AG[\"KorgexAgent loop
plan → act → verify\"]\n AG -->|model id| PB{Provider}\n PB -->|\"claude / anthropic/*\"| ANT[\"Anthropic SDK\"]\n PB -->|everything else| OAI[\"OpenAI-compatible SDK
OpenAI · OpenRouter · Ollama · Grok · DeepSeek\"]\n ANT --> TR[\"Tool router
(src/tool_abstraction.py)\"]\n OAI --> TR\n TR --> BT[\"Built-in tools
Read · Edit · Bash · Grep · …\"]\n TR --> MCP[\"MCP servers
(any in mcp.json)\"]\n TR --> CA[\"CodeAct kernel
code = the action (opt-in)\"]\n BT --> LED[(\"korg-ledger
hash-chained + causal DAG\")]\n MCP --> LED\n CA --> LED\n LED -. \"verify · trace · why · cost\" .-> U\n```\n\nThe agent is provider-agnostic by design: tool schemas are translated per provider (`{name, description, input_schema}` for Anthropic, `{type:\"function\", function:{…}}` for OpenAI), responses are normalized into a common shape, and tool results are formatted in whichever message structure the provider expects. Every tool call — built-in, MCP, or CodeAct — is recorded to the ledger as it happens.\n\n---\n\n## Verifiable cognition\n\n**In plain terms:** korgex keeps a logbook of everything it does — every file it reads, every command it runs. Each entry is sealed to the one before it, like links in a chain, so if anyone later changes, adds, or removes even one entry, the chain visibly breaks. The result is honest, checkable proof of what the AI actually did — for audits, compliance, debugging, or simple peace of mind. As far as we know, no other coding agent does this.\n\n\n\nUnder the hood: every run is recorded to a **tamper-evident causal ledger**, not an opaque log. Each event is hash-linked (`prev_hash`/`entry_hash`) to the previous one *and* causally linked (`triggered_by`) to what caused it — so a whole session can be cryptographically proven intact, and any edit, deletion, reorder, or splice is detected and localized to the offending event.\n\n```mermaid\nflowchart LR\n subgraph chain[\"korg-ledger — each event hash-linked to the last\"]\n direction LR\n E0[\"prompt
a1f3\"] --> E1[\"Read
7c0e\"] --> E2[\"Edit
b42d\"] --> E3[\"Bash: pytest
9d11\"]\n end\n E3 --> V{{\"korgex verify\"}}\n V -->|chain intact| OK[\"✓ proven unaltered\"]\n V -->|\"edit / splice / reorder\"| BAD[\"✗ localized to the bad event\"]\n```\n\n```bash\nkorgex verify # prove the recorded run wasn't altered (exit 0/1, CI-friendly)\nkorgex trace # the causal trace — what the agent did + what caused it\nkorgex why src/auth.py # walk the causal chain back from a file change to its prompt\nkorgex recall \"rate limiter\" # pull lean, verified context for a query — retrieve, don't carry\nkorgex cost # estimated $ spend for the session, from recorded token counts\nexport KORG_LEDGER_HMAC_KEY=… # make the chain tamper-PROOF, not just tamper-evident\n```\n\n**Memory drift.** A remembered fact is anchored to a sha256 baseline of its source, so when the source moves on the staleness is an exact signal — and the keep/refresh/discard reconcile decision is itself recorded to the ledger.\n\n```bash\nkorgex drift # scan persistent memories for drift vs their source baselines (exit 0/1)\n```\n\n**Audit logs you already have — and share the proof.** `korgex audit` imports a session you already ran (auto-discovers your Claude Code logs) into a verifiable chain. Add `--html` and you get a single self-contained file that **re-verifies itself in the recipient's browser** — including a live *tamper test* that breaks the chain on purpose so anyone can feel the evidence. No setup, no buy-in, no network calls.\n\n```bash\nkorgex audit --html audit.html\n# audited → 2,319 ledger events\n# chain: ✓ INTACT — tamper-evident, cryptographically verifiable\n# report: audit.html ← open in any browser; it re-verifies itself\n\nkorgex import transcript.json # replay any vendor's session into a korg-ledger@v1 journal\nkorgex trajectory --out train.jsonl # export the journal as a provenance-stamped training trajectory\n```\n\n**Hand someone a receipt.** `korgex receipt` mints a single portable file that proves what a run did — the events (so it checks **offline**), a plain-language `--claim`, a summary, and an optional `--sign` that attests *who* with your own key. The recipient confirms it with `korgex receipt verify ` (exit 0/1), or just opens the `--html` and watches it re-verify itself. A provable deliverable, not a screenshot.\n\n```bash\nkorgex receipt --claim \"shipped /healthz + passing test\" --sign --html receipt.html\n# ✓ receipt minted — 5 events, 3 tool calls, 2 files, $0.0078\n# signed by b251a84c… (your korgex identity) · tip 46263017…\n# receipt.html ← open in any browser; it re-verifies itself\n\nkorgex receipt verify receipt.korgreceipt.json # ✓ VALID / ✗ INVALID (CI-gateable)\n```\n\n**Gate it in CI.** Drop the [`verify-ledger`](.github/actions/verify-ledger) GitHub Action into any repo to fail the build if an agent's ledger or receipt doesn't verify — zero trust in the tool that produced it:\n\n```yaml\n- uses: New1Direction/korgex/.github/actions/verify-ledger@main\n with:\n path: \".korg/journal.json\" # or \"**/*.korgreceipt.json\"\n pubkey: ${{ vars.KORG_SIGNER_PUBKEY }} # optional: pin the signer\n```\n\nSee [Self-Coding Bench](docs/self-coding-bench.md) for live reliability data across models.\n\n---\n\n## Tools\n\nThe agent sees **23 high-level, model-facing tools** (Claude-Code style), each with a deep description covering usage, edge cases, and anti-patterns. Under the hood they route to ~60 internal handlers (`src/tools_impl.py`).\n\n| Tool | Purpose |\n|---|---|\n| **Read** · **Write** · **Edit** | Read a file; create/overwrite; surgical string-replace (converted to SEARCH/REPLACE internally). |\n| **Bash** · **BashOutput** | Run a shell command with timeout; poll a long-running background job. |\n| **Grep** · **Glob** | Regex content search (ripgrep where available); list files by pattern. |\n| **Agent** · **Orchestrate** | Delegate a sub-task to a sub-agent; run a **parallel DAG** of sub-agents (see [Capabilities](#capabilities)). |\n| **TaskCreate** · **TaskUpdate** | Track and update multi-step work as a task list. |\n| **AskUserQuestion** | Ask a clarifying question with optional multiple-choice. |\n| **Skill** · **ToolSearch** | Invoke an installed skill; discover tools at runtime by keyword. |\n| **WebFetch** · **WebSearch** | Fetch a URL as clean text; search the web. |\n| **Recall** | Pull relevant facts from cross-session memory (drift-checked). |\n| **Retrieve** | Pull the exact bytes of a large tool result that was sealed to a content-ref. |\n| **BusSend** · **BusInbox** | Send/receive on the verifiable agent message bus (tamper-evident coordination). |\n| **python** *(opt-in)* | **CodeAct** — run Python as the action, with tools available as functions. |\n| **NetCapture** *(opt-in)* | Auditable HTTP(S) capture of an app you wrote — debug API calls without cURL. |\n| **RemoteSignTip** *(opt-in)* | Sign a ledger tip via a remote signer you control (key off-host). |\n\n---\n\n## Capabilities\n\nBeyond the core file/shell/search loop, korgex ships several deeper systems. The riskier ones are **opt-in and off by default** (a single env var), and every one of them records to the verifiable ledger.\n\n- **CodeAct — code as the action space** (`KORGEX_CODEACT_ENABLE=1`). A persistent, fuel-metered Python kernel where the model writes code that calls tools as functions — denser than one-tool-call-per-turn. The nested execution trace is recorded to the ledger. When enabled, the kernel is **OS-sandboxed by default** where a backend exists — bubblewrap on Linux, Seatbelt on macOS — confining it to no-network + write-only-workspace (`KORGEX_CODEACT_ISOLATION=auto`/`required`/`off`).\n- **Multi-agent orchestration** (`KORGEX_PARALLEL_AGENTS`, plus the `Orchestrate` tool). Run a DAG of sub-agents concurrently — ledger-native and verifiable, with hard one-level nesting and each sub-run chained under its parent.\n- **Auditable network capture** (`KORGEX_NETCAPTURE_ENABLE=1`). Run an app/script you wrote under a local CA-signing capture proxy and get a structured, redacted trace of every HTTP(S) exchange. Process-scoped, capture-only, secrets masked before they're recorded.\n- **Verifiable browser** (`KORGEX_BROWSER_STEALTH`, `KORGEX_BROWSER_EVAL`). CDP-driven snapshot→act browser automation, ledger-recorded; opt-in stealth.\n- **Remote signing** (`KORGEX_REMOTE_SIGNER_*`). Sign a ledger tip via an HTTP signer **you own and control**, so the signing key can live off the agent host (a separate box, an HSM). Fail-closed: bearer token, host allowlist, optional pubkey pinning, local signature verification.\n- **Verifiable agent bus** (`korgex bus`, `KORG_BUS_*`). Agents coordinate over an Ed25519-signed, tamper-evident korg-ledger journal — \"who said what\" is a signature, not a claim.\n- **Recall + memory** — cross-session memory that is drift-checked against source baselines ([Verifiable cognition](#verifiable-cognition)).\n- **Local models** (`korgex local`). Hardware-aware advisor (CPU/RAM/GPU/VRAM → ranked, fit-scored picks via [llmfit](https://github.com/AlexsJones/llmfit), optional) that can wire a local **Ollama** model as your default. On Apple Silicon, `korgex local --omlx` targets a running [**omlx**](https://github.com/jundot/omlx) MLX server (OpenAI-compatible, continuous batching + tiered KV cache): bare lists the models it's serving, `--omlx --use ` wires it as your default (add `--omlx-url` for a non-default port). korgex doesn't reimplement inference — it just points at the local endpoint.\n\n---\n\n## Safety & sandboxing\n\n- **Destructive-command guard** (on by default; `KORGEX_COMMAND_GUARD`). A whitelist-first, quote/comment-aware floor over `Bash` (and the CodeAct bridge) that refuses obviously destructive commands; a block is a tamper-evident `command_guard.block` event in the ledger.\n- **Egress / exfil guard** (on by default in flag mode; `KORGEX_EGRESS=off|flag|redact|block`). Shape-based inspection of data leaving the box via outbound tools (`WebFetch`/`WebSearch`/`BusSend`/`browser_navigate`/MCP/network `Bash`): detects secret shapes (reusing the ledger redactor's patterns) and large encoded blobs. `flag` warns + records an `egress.flag` verdict but never alters or blocks (additive); `redact` masks the secret in the outbound payload before it leaves; `block` refuses. Every detection is a tamper-evident ledger verdict carrying the finding's *shape* only — the raw secret is redacted from the record, so the shareable ledger never becomes the exfil channel. Opt-in destination control via `KORGEX_EGRESS_ALLOW`/`KORGEX_EGRESS_DENY` (comma-separated hosts).\n- **Bash sandbox** (`KORGEX_SANDBOX=modal|docker|direct|auto`). Controls isolation for shell execution.\n- **CodeAct OS isolation** — sandbox-by-default (Linux/bubblewrap · macOS/Seatbelt) for the code kernel; `KORGEX_CODEACT_ISOLATION=required` to fail closed, `=off` to disable.\n- **Edit confirmation.** Diffs for `Edit`/`Write` on critical files prompt `[y/N]` in the TUI; the edit policy is configurable via `KORGEX_EDIT_POLICY`.\n- **Opt-in by default for anything powerful.** CodeAct, NetCapture, remote signing, and browser stealth are all off until you turn them on.\n\n---\n\n## CLI reference\n\n```\n$ korgex --help\nusage: korgex [-h] SUBCOMMAND ...\n\nkorgex — autonomous coding agent. Pass a naked prompt to run the agent, or use a subcommand.\n```\n\nAny non-subcommand argument is treated as a prompt: `korgex \"create hello.txt with 'hi'\"`.\n\n### Flags\n\n| Flag | Purpose |\n|---|---|\n| `--model MODEL` | Override the model (e.g. `claude-sonnet-4-6`, `gpt-4o`, `openai/gpt-4o-mini`). Always wins over `--mode`. |\n| `--mode {plan,execute,explore,review,debug,research}` | Mode-based model selection (see [Multi-model routing](#multi-model-routing)). |\n| `--mcp` | Load MCP servers from `mcp.json` at startup. |\n| `--quiet` / `-q` | Disable the streaming TUI; only the final result prints. Use in pipes, scripts, CI. |\n| `--version` / `-V` | Print the korgex version and exit. |\n| `--resume` | Resume the last session — replay its transcript from the verifiable ledger. With a prompt: resume + run it; bare `korgex --resume`: reopen the REPL with that context. |\n\n### Subcommands\n\n| Subcommand | Behavior |\n|---|---|\n| `korgex setup` | Connect model providers (any of them) — saves keys + a default model to `~/.korgex/config.json`. |\n| `korgex init` | Scaffold a starter `AGENTS.md` for the repo (detects stack + test/build commands; never clobbers). |\n| `korgex skills` | List skills; `install ` / `search ` / `adopt ` pull from the open [Agent-Skills catalog](https://skills.sh) (local dir, git URL, or `owner/repo[@skill]`) as `trust: installed`; `check`/`update [name\\|all]` refresh git-sourced skills; `export [claude\\|cursor\\|codex\\|]` pushes a korgex (incl. self-learned) skill out to another agent. |\n| `korgex sessions` | List recent sessions in this repo's ledger (resume one with `korgex --resume`). |\n| `korgex commands` | List custom slash commands (built-in, project, user); invoke them in the REPL as `/`. |\n| `korgex local` | Recommend (and optionally wire) a local model that fits this machine. |\n| **Verifiable cognition** | |\n| `korgex verify [journal]` | Prove the ledger's hash-chain + causal DAG is intact (exit 0/1, CI-friendly). |\n| `korgex trace` | Show the causal cognition trace — what the agent did and what caused it. |\n| `korgex why ` | Trace why a file was changed, back through the causal chain to its prompt. |\n| `korgex cost` | Estimated $ spend for the session, from the ledger's recorded token counts. |\n| `korgex drift` | Scan persistent memories for drift against their source baselines (exit 0/1). |\n| `korgex audit [--html f]` | Audit a session you already ran into a verifiable ledger (auto-discovers Claude Code logs). |\n| `korgex import ` | Replay another vendor's session transcript into a korg-ledger@v1 journal. |\n| `korgex trajectory` | Export a journal as a verifiable, provenance-stamped training trajectory. |\n| `korgex bus` | Verifiable agent message bus over a tamper-evident korg-ledger journal. |\n| **MCP & integrations** | |\n| `korgex mcp` | Manage MCP servers — add/list/remove stdio or remote (url+auth) servers in `mcp.json`. |\n| `korgex mcp-server` | Run the korg-ledger MCP server (JSON-RPC over stdio) — verify/audit/import for any MCP host. |\n| `korgex diag ` | Report language-server diagnostics (errors/types) for a file — best-effort. |\n| **Dashboard / editor** | |\n| `korgex acp` | Run korgex as an [Agent Client Protocol](https://agentclientprotocol.com) agent over stdio, so an ACP editor (Zed et al.) can drive it — streams tool-call activity + reply text live. |\n| `korgex serve` · `dashboard` | Start the FastAPI dashboard (`127.0.0.1:8090` by default) with/without opening the VS Code sidecar. |\n| `korgex status` · `stop` | Report / terminate the background backend. |\n| `korgex install-extension` | Install the compiled `.vsix` into your local VS Code. |\n\n### Drive korgex from your editor (ACP)\n\nkorgex speaks the open **Agent Client Protocol** as an *agent*, so an ACP-capable editor can drive it directly — one verifiable, cross-vendor agent in your editor's agent panel. In **Zed**, add korgex as an external agent in `settings.json`:\n\n```json\n{\n \"agent_servers\": {\n \"korgex\": { \"type\": \"custom\", \"command\": \"korgex\", \"args\": [\"acp\"], \"env\": {} }\n }\n}\n```\n\n> Zed requires `\"type\": \"custom\"` on each external agent — without it Zed rejects the whole `agent_servers` block (\"missing field `type`\") and korgex won't appear. If Zed can't find `korgex` on its (minimal GUI) `PATH`, use the full binary path as the `command` (e.g. `~/.local/bin/korgex`). After editing settings, Zed hot-reloads; if korgex still doesn't show, fully quit and reopen Zed.\n\nThen pick **korgex** from the Agent Panel's *New Thread* menu. As it works, the editor shows live `tool_call` activity (read/edit/run/search cards, with an inline diff preview for edits) and streams the reply text — backed by the same tamper-evident ledger, so the whole session stays provable with `korgex verify`. (Editor handles a prompt turn per message; embedded `@file` context and pasted resources are accepted.)\n\nBy default korgex acts freely. To have the **editor approve edits** (a `session/request_permission` prompt with *Allow / Allow-don't-ask-again / Reject*), run it with `KORGEX_EDIT_POLICY=ask`:\n\n```json\n{ \"agent_servers\": { \"korgex\": { \"type\": \"custom\", \"command\": \"korgex\", \"args\": [\"acp\"], \"env\": { \"KORGEX_EDIT_POLICY\": \"ask\" } } } }\n```\n\n---\n\n## Environment variables\n\n**Core**\n\n| Variable | Purpose | Default |\n|---|---|---|\n| `ANTHROPIC_API_KEY` | Used when the model id contains \"claude\" or starts with \"anthropic/\". | — |\n| `OPENAI_API_KEY` | Used for any non-Anthropic model. | — |\n| `KORGEX_API_KEY` / `KORGEX_API_URL` | Generic key + base URL for OpenAI-compatible endpoints (OpenRouter, Ollama, vLLM…). | — / `https://api.openai.com/v1` |\n| `KORGEX_MODEL` | Default model when neither `--model` nor `--mode` is given. | `claude-sonnet-4-6` |\n| `KORGEX_PROVIDER` | Force the transport (`openai`\\|`anthropic`), overriding model-id autodetect. | autodetect |\n| `KORGEX_MAX_ITERATIONS` | Max agent-loop iterations before giving up. | `30` |\n| `KORGEX_MCP` | `1` to auto-load MCP servers from `mcp.json`. | unset |\n| `KORGEX_SANDBOX` | `modal`\\|`docker`\\|`direct`\\|`auto` — bash isolation. | `auto` |\n| `KORGEX_DASHBOARD_HOST` | Dashboard bind host. Defaults to localhost; set `0.0.0.0` only behind an auth-terminating proxy. | `127.0.0.1` |\n\n**Capabilities (opt-in)**\n\n| Variable | Purpose |\n|---|---|\n| `KORGEX_LEAN_CONTEXT` · `KORGEX_LEAN_CONTEXT_TOKENS` | Inject lean, *verified* ledger context relevant to the prompt instead of carrying full history (budget default 800) — lets a smaller/self-hosted model run the loop. |\n| `KORGEX_CODEACT_ENABLE` · `KORGEX_CODEACT_ISOLATION` | Enable the CodeAct code-kernel; OS isolation `auto` (default — sandbox where available: Linux/bubblewrap, macOS/Seatbelt) · `required` (fail closed) · `off`. |\n| `KORGEX_NETCAPTURE_ENABLE` | Enable the auditable HTTP(S) capture tool. |\n| `KORGEX_PARALLEL_AGENTS` | Concurrency for multi-agent orchestration. |\n| `KORGEX_REMOTE_SIGNER_TOKEN` · `_ALLOWED_HOSTS` · `_PUBKEY` · `_REQUIRE_HTTPS` | Remote-signer auth, host allowlist, pinned key, https enforcement. |\n| `KORGEX_BROWSER_STEALTH` · `KORGEX_BROWSER_EVAL` | Browser stealth mode; allow in-page `evaluate`. |\n| `KORGEX_COMMAND_GUARD` | Toggle the destructive-command guard (on by default). |\n| `KORGEX_EDIT_POLICY` | Edit confirmation policy. |\n| `KORGEX_WEBHOOK_SECRET` · `KORGEX_WEBHOOK_ALLOW_UNSIGNED` | GitHub webhook HMAC secret; unsigned webhooks are rejected unless `KORGEX_WEBHOOK_ALLOW_UNSIGNED=1` is explicitly set for local/dev use. |\n\n**Ledger & bus**\n\n| Variable | Purpose | Default |\n|---|---|---|\n| `KORG_JOURNAL_PATH` | Durable JSONL ledger; content-addressed blobs are written beside it. | `.korg/journal.jsonl` |\n| `KORG_LEDGER_HMAC_KEY` | If set, the chain is HMAC-keyed — tamper-*proof*, not just tamper-evident. | unset |\n| `KORG_BUS_AGENT` · `KORG_BUS_JOURNAL` · `KORG_BUS_KEY` | Agent id, bus journal, and Ed25519 key for the verifiable bus. | — |\n\nProvider-detection rule: if the model id contains `\"claude\"` or starts with `\"anthropic/\"`, the Anthropic SDK is used; otherwise the OpenAI-compatible SDK (OpenAI, OpenRouter, Ollama, DeepSeek, vLLM, …). Set `KORGEX_PROVIDER=openai` to drive a `claude`/`anthropic/*` id through an OpenAI-compatible endpoint (e.g. Claude via OpenRouter).\n\n---\n\n## Multi-model routing\n\n`--mode` picks a model appropriate for the work type:\n\n| Mode | Model | Generation params |\n|---|---|---|\n| `plan` | Opus 4.7 | `max_tokens=64000`, `thinking={budget_tokens: 20000}`, `temperature=0.7` |\n| `execute` | Sonnet 4.6 | `max_tokens=64000`, `temperature=0.3` |\n| `explore` | Opus 4.7 | `max_tokens=32000`, `temperature=0.5` |\n| `review` | Sonnet 4.6 | `max_tokens=16000`, `temperature=0.3` |\n| `debug` | Haiku 4.5 | `max_tokens=16000`, `temperature=0.2` |\n| `research` | Opus 4.7 | `max_tokens=32000`, `temperature=0.7` |\n\nExplicit `--model` always wins over `--mode`. Default (neither set) is Sonnet 4.6.\n\n```bash\nkorgex --mode plan \"architect a multi-tenant billing system\"\nkorgex --mode debug \"trace why this 500 is happening\"\nkorgex --mode execute \"implement the plan we just made\"\n```\n\n---\n\n## MCP integration\n\n*Plain version: MCP is an open \"app-store\" standard for AI — it lets korgex plug into outside services (GitHub, your files, a database, …) without custom glue.*\n\nkorgex includes a native MCP (Model Context Protocol) client. Any MCP server in your `mcp.json` becomes part of the agent's tool surface. Manage them from the CLI with `korgex mcp` (add/list/remove stdio **or** remote url+auth servers), and `korgex mcp catalog` / `korgex mcp add ` for one-command presets. One worth knowing: **`korgex mcp add mise`** wires in [mise](https://github.com/jdx/mise)'s own agent-facing server — the agent gets your project's tool versions, env vars, and runnable tasks (plus `run_task`), all verifiable through the ledger.\n\n### korgex *is* an MCP server too\n\n`korgex mcp-server` exposes the verifiable-cognition substrate over JSON-RPC/stdio so any MCP host (Claude Desktop, Cursor, …) can call:\n\n- **`korg_verify`** — prove a korg-ledger journal is tamper-evident-intact;\n- **`korg_audit`** — audit the host agent's own Claude Code logs (import + verify), zero-config;\n- **`korg_import`** — import a vendor session transcript into a verifiable chained ledger.\n\n```json\n{ \"mcpServers\": { \"korg-ledger\": { \"command\": \"korgex\", \"args\": [\"mcp-server\"] } } }\n```\n\nListed in the [MCP Registry](https://registry.modelcontextprotocol.io/) — `mcp-name: io.github.New1Direction/korg-ledger`.\n\n### Configure & use\n\n```json\n{\n \"mcpServers\": {\n \"github\": { \"command\": \"npx\", \"args\": [\"-y\", \"@modelcontextprotocol/server-github\"], \"env\": { \"GITHUB_TOKEN\": \"ghp_...\" } },\n \"filesystem\": { \"command\": \"npx\", \"args\": [\"-y\", \"@modelcontextprotocol/server-filesystem\", \"/tmp\"] }\n }\n}\n```\n\n```bash\nkorgex --mcp \"create a GitHub issue summarizing today's bug\"\n```\n\nThe agent discovers each server's tools at startup, registers them into the user-facing tool list, and routes calls back to the originating server. Server failures are logged and skipped — they never crash the agent.\n\n---\n\n## Plugins\n\nExtend korgex without forking it. Drop a `.py` file into `~/.korgex/plugins/` (global) or `/.korgex/plugins/` (project-local) that defines a `register(registry)` function, and it hooks into the agent loop at startup.\n\n```python\n# ~/.korgex/plugins/notify.py — ping me when a file is edited\ndef register(reg):\n @reg.on(\"post_tool\")\n def on_edit(payload):\n call = payload[\"call\"]\n if call[\"name\"] in (\"Edit\", \"Write\"):\n print(f\" ✎ touched {call['args'].get('file_path')}\")\n```\n\n**Lifecycle hooks:** `on_user_prompt` (each turn starts), `pre_tool` (before a tool runs), `post_tool` (after it returns), `on_stop` (run finishes). Plugins run **in-process** with full access — install only ones you trust — and are **fail-safe**: one that fails to import, lacks `register`, or raises is recorded and skipped without crashing startup.\n\n---\n\n## Streaming TUI\n\nWhen stdout is a TTY, the agent streams output live via [Rich](https://rich.readthedocs.io/): thinking blocks in dimmed italic (Anthropic), text character-by-character, tool calls with a transient spinner (`⠋ Read(file_path=src/foo.py)`), `[y/N]` diff confirmation on critical edits, and graceful `Ctrl+C` interrupt (double to force-kill). Streaming auto-disables when stdout is piped, in CI, or with `--quiet`. OpenAI/OpenRouter streaming pipes through the same renderer; tool-call deltas are accumulated across chunks.\n\n---\n\n## Architecture\n\n### System overview\n\n```mermaid\nflowchart TD\n U[\"You — CLI / REPL / ACP editor
(src/cli.py · repl.py · acp.py)\"] --> AG\n\n subgraph core[\"KorgexAgent loop — src/agent.py (plan, act, verify)\"]\n AG[\"Agent loop: run_task()
system prompt + memory + task list\"]\n GATE[\"Per-call gates
plan-mode · edit-policy · command / egress guard · hooks\"]\n AG --> GATE\n end\n\n AG -->|\"normalize tool-use shape\"| PROV{\"Provider
(model id / KORGEX_PROVIDER)\"}\n PROV -->|\"claude family\"| ANT[\"Anthropic SDK\"]\n PROV -->|\"everything else\"| OAI[\"OpenAI-compatible SDK
OpenAI · OpenRouter · Ollama · Grok · Nous · Venice · Gemini\"]\n ANT --> GATE\n OAI --> GATE\n\n GATE --> TR[\"Tool router
src/tool_abstraction.py\"]\n TR --> BT[\"Built-in handlers
file · Bash · search · git · GitHub · browser\"]\n TR --> CA[\"CodeAct kernel
Python-as-action, fuel/mem-metered (opt-in)\"]\n TR --> MCP[\"MCP servers
src/mcp_client.py\"]\n\n BT --> LED\n CA --> LED\n MCP --> LED\n GATE -. \"every decision + result\" .-> LED\n\n LED[(\"korg-ledger · src/korg_ledger.py
append-only · hash-chained · causal DAG\")]\n LED --> HEAL[\"Test gate + self-heal
src/test_gate.py · self_healing.py\"]\n HEAL -->|\"red, retry\"| AG\n LED --> VERIFY[\"verify · trace · why · audit · receipt
Ed25519 signing\"]\n VERIFY --> U\n```\n\n### Tool routing — stable model-facing names → internal handlers\n\n```\nUser tool call (LLM-visible): Internal handler (src/tools_impl.py):\n───────────────────────────── ─────────────────────────────────────\nRead(file_path=...) → tool_read_file(filepath=..., context=...)\nWrite(file_path=..., ...) → tool_write_file(filepath=..., ...)\nEdit(file_path, old, new) → tool_replace_with_git_merge_diff(merge_diff=\"<<<<<<< SEARCH ...\")\nBash(command=...) → tool_run_in_bash_session(command=...)\n```\n\nThe router (`src/tool_abstraction.py`) looks up the name in `_TOOL_ROUTING`, applies a `param_map` or a custom `adapter`, filters kwargs the handler doesn't accept, auto-injects `context={'repo_root': cwd}`, and catches exceptions into `{\"error\": ...}` so a single tool failure never kills the loop. MCP-sourced tools bypass `_TOOL_ROUTING` and dispatch through `MCPServerManager.call_tool()`.\n\n### The agent loop\n\n```mermaid\nflowchart TD\n S([\"prompt\"]) --> SEND[\"LLM.send(messages, tools)\"]\n SEND --> Q{tool calls?}\n Q -->|no| F([\"final result\"])\n Q -->|yes| RT[\"route_tool_call(name, args)\"]\n RT --> REC[\"record event → korg-ledger\"]\n REC --> APP[\"append tool_result to messages\"]\n APP --> SEND\n```\n\nThe plan-first system prompt directs the agent to plan, verify, diagnose-before-changing, and never modify build artifacts (`SYSTEM_PROMPT` in `src/agent.py`). The ledger lives in native Python (`src/korg_ledger.py`, `src/ledger_spec.py`) — no external runtime required.\n\n---\n\n## Project structure\n\n```\nkorgex/\n├── src/\n│ ├── agent.py # KorgexAgent — main loop, provider branching, streaming\n│ ├── cli.py · repl.py # argparse dispatch · interactive REPL\n│ ├── tool_abstraction.py # USER_TOOLS registry + router + MCP integration\n│ ├── tools_impl.py # ~60 internal handlers (file ops, git, GitHub, web, …)\n│ ├── model_router.py # mode → model mapping (plan/execute/debug/…)\n│ ├── korg_ledger.py · ledger_spec.py · signing.py # verifiable ledger + Ed25519\n│ ├── codeact/ # code-as-action kernel (fuel-metered, isolated, traced)\n│ ├── orchestrate.py # multi-agent DAG orchestration\n│ ├── recall.py · memory.py · memory_drift.py # cross-session memory + drift\n│ ├── command_guard.py · sandbox.py # destructive-cmd floor · bash sandbox\n│ ├── netcapture.py · remote_signer.py · browser.py # opt-in capability modules\n│ ├── structured_output.py · skills.py · local_model.py\n│ ├── mcp_client.py · dashboard.py · interactive.py\n│ └── ...\n├── docs/ # CLI reference, comparison, getting-started, tools-reference, …\n├── spec/korg-ledger-v1/ # the ledger spec (SPEC.md, EVENTS.md)\n├── tests/ # ~1,608 passing tests\n├── .github/workflows/ # Linux CI (3.10–3.13) + PyPI publisher (OIDC)\n├── pyproject.toml\n└── README.md\n```\n\n---\n\n## Development & testing\n\n```bash\ngit clone https://github.com/New1Direction/korgex.git && cd korgex\nuv venv .venv && source .venv/bin/activate # or python -m venv .venv\nuv pip install -e \".[dev]\" # pytest, build, ruff, …\n\nruff check src/ # lint\npytest -q # the full suite\n```\n\n`pyproject.toml` is the package dependency source of truth. `requirements.txt` is\nkept as a compatibility mirror for source checkouts and legacy automation; prefer\neditable installs with extras for development.\n\nThe suite is **1,600+ tests** with no live LLM calls (everything is unit-tested) and runs on Linux CI across **Python 3.10, 3.11, 3.12, 3.13** on every push and PR. Major areas: the agent loop (routing, provider schemas, mode/model resolution, loop guards, the stall classifier, compaction), tools (fuzzy Edit, edit-freshness, background Bash, web), the verifiable ledger (hash-chain + causal DAG, redaction, the Ed25519 signed bus), CodeAct (kernel isolation, fuel, the tool bridge), MCP (namespaced multi-server router, OAuth refresh, full round-trip), prompt caching, skills (trust tiers, self-learning, the curator), and the REPL.\n\n---\n\n## Building & releasing\n\nReleases are automated. Bump `version` in `pyproject.toml`, update `CHANGELOG.md`, merge to `main`, then cut a GitHub Release — the **PyPI publish workflow fires on `release: published` and uploads via OIDC Trusted Publishing** (with digital attestations). No manual token handling.\n\n```bash\ngh release create vX.Y.Z --title \"vX.Y.Z\" --notes \"…\" # → triggers .github/workflows/publish.yml → PyPI\n```\n\nTo build locally for inspection: `python -m build` then `python -m twine check dist/*`.\n\n---\n\n## Troubleshooting\n\n**`korgex: No API key found`** — set one of `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, or `KORGEX_API_KEY` (with `KORGEX_API_URL` for non-OpenAI endpoints), or run `korgex setup`.\n\n**`ModuleNotFoundError: No module named 'anthropic'`** (or `openai`, `rich`) — the deps weren't installed: `pip install -e .` (picks up everything from `pyproject.toml`).\n\n**Agent loops forever on tool calls** — lower the cap: `export KORGEX_MAX_ITERATIONS=10`, and use `--quiet` to see only the final state.\n\n**`--mcp` is slow to start** — the client connects to each server synchronously and waits for the handshake; unreachable entries in `mcp.json` each time out before being skipped. Remove dead servers or use `korgex mcp` to manage them.\n\n**`verify` reports a break** — that's the point: it found and localized an altered/spliced event. The reported `seq_id` is where the chain diverges.\n\n---\n\n## Known limitations\n\nThese exist today; PRs welcome.\n\n- **OpenAI streaming has fewer rendered events than Anthropic.** Anthropic emits thinking blocks and message-delta usage; OpenAI emits only text and tool-call chunks. Both render correctly, but the TUI is richer for Anthropic.\n- **Dashboard authentication is not implemented.** It binds to `127.0.0.1` by default; don't set `KORGEX_DASHBOARD_HOST=0.0.0.0` without an auth-terminating reverse proxy in front.\n- **The VS Code sidecar is a legacy companion** to the dashboard; korgex's primary interface is the terminal REPL.\n\n---\n\n## License\n\nMIT — see [LICENSE](LICENSE).\n\n---\n\n## Related projects\n\n- **[Model Context Protocol](https://modelcontextprotocol.io/)** — the open MCP standard korgex implements (as both client and server).\n- **[korg](https://github.com/New1Direction/korg)** · **[korgchat](https://github.com/New1Direction/korgchat)** — the broader ecosystem around the korg-ledger.\n- **[llmfit](https://github.com/AlexsJones/llmfit)** — the hardware-aware local-model advisor `korgex local` builds on (optional).\n", "bytes": 39404, "sha": "da40361bf9a5a588267acb4feb246f1ea66396f3723f147efed0e85d60723360", "repo_slug": "new1direction/korgex", "fonte": "repo", "truncated": false, "api": "https://agentalog.com/api/listings/mcp_io_github_new1direction_korg_ledger_6fbd8f4a/readme" }