Korgex

English · 简体中文 · 繁體中文

korgex

An AI coding teammate for your terminal — that keeps the receipts.

Tell 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.

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.

For 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.

$ 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

---

Table of Contents

• [Install](#install)
• [Quickstart](#quickstart)
• [The REPL — live in it](#the-repl--live-in-it)
• [How it works](#how-it-works)
• [Verifiable cognition](#verifiable-cognition)
• [Tools](#tools)
• [Capabilities](#capabilities)
• [Safety & sandboxing](#safety--sandboxing)
• [CLI reference](#cli-reference)
• [Environment variables](#environment-variables)
• [Multi-model routing](#multi-model-routing)
• [MCP integration](#mcp-integration)
• [Plugins](#plugins)
• [Streaming TUI](#streaming-tui)
• [Architecture](#architecture)
• [Project structure](#project-structure)
• [Development & testing](#development--testing)
• [Building & releasing](#building--releasing)
• [Troubleshooting](#troubleshooting)
• [Known limitations](#known-limitations)
• [License](#license)

---

Install

From PyPI (recommended)

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

Requires Python ≥ 3.10 (tested on 3.10, 3.11, 3.12, 3.13).

From source / latest 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

---

Quickstart

# 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

Run bare korgex with no prompt to drop into the interactive REPL.

---

The REPL — live in it

Run bare korgex for a streaming, multi-turn session. It connects your MCP servers, reads your project rules, and keeps a per-session rewind log.

Slash commands

| Command | What it does | |---|---| | /loop | Grind a task list unattended — auto-continues turn after turn until done, with a hard cap (Ctrl-C stops). | | /diff [n] | Colored diffs of what changed in the last turn (or turn n). | | /rewind [n] | List undo points, or restore files to BEFORE prompt n. | | /skills · /skills curate | List skills korgex learned (✦); curate merges near-duplicates. | | /tasks · /jobs | The live task checklist; background shell jobs. | | /plan [on\|off] | Plan mode — read-only until you approve the agent's plan. | | /model [id] | Show a priced model menu, or switch the live model mid-session. | | /verify · /cost | Verify the session ledger; show estimated $ spend from recorded tokens. | | /resume [id] | Reload a prior session's transcript into context and continue where you left off. | | / [args] | Run a custom command — a markdown prompt from .korgex/commands/ (or a built-in like /code-review, /build-fix, /checkpoint). | | /clear · /help · /exit | Reset the conversation · help · quit. |

Inline shortcuts

• @path/to/file — mention a file and its contents are pulled into the turn: refactor @src/auth.py to use @src/db.py.
• !command — run a shell command right there: !git status, !pytest -q.

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.

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.

---

How it works

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

The 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.

---

Verifiable cognition

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.

Under 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.

flowchart LR
    subgraph chain["korg-ledger — each event hash-linked to the last"]
      direction LR
      E0["prompta1f3"] --> E1["Read7c0e"] --> E2["Editb42d"] --> E3["Bash: pytest9d11"]
    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

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.

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

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.

korgex audit --html audit.html
#   audited  → 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

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.

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)

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:

- 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

See [Self-Coding Bench](docs/self-coding-bench.md) for live reliability data across models.

---

Tools

The 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).

| Tool | Purpose | |---|---| | Read · Write · Edit | Read a file; create/overwrite; surgical string-replace (converted to SEARCH/REPLACE internally). | | Bash · BashOutput | Run a shell command with timeout; poll a long-running background job. | | Grep · Glob | Regex content search (ripgrep where available); list files by pattern. | | Agent · Orchestrate | Delegate a sub-task to a sub-agent; run a parallel DAG of sub-agents (see [Capabilities](#capabilities)). | | TaskCreate · TaskUpdate | Track and update multi-step work as a task list. | | AskUserQuestion | Ask a clarifying question with optional multiple-choice. | | Skill · ToolSearch | Invoke an installed skill; discover tools at runtime by keyword. | | WebFetch · WebSearch | Fetch a URL as clean text; search the web. | | Recall | Pull relevant facts from cross-session memory (drift-checked). | | Retrieve | Pull the exact bytes of a large tool result that was sealed to a content-ref. | | BusSend · BusInbox | Send/receive on the verifiable agent message bus (tamper-evident coordination). | | python (opt-in) | CodeAct — run Python as the action, with tools available as functions. | | NetCapture (opt-in) | Auditable HTTP(S) capture of an app you wrote — debug API calls without cURL. | | RemoteSignTip (opt-in) | Sign a ledger tip via a remote signer you control (key off-host). |

---

Capabilities

Beyond 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.

• 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).
• 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.
• 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.
• Verifiable browser (KORGEX_BROWSER_STEALTH, KORGEX_BROWSER_EVAL). CDP-driven snapshot→act browser automation, ledger-recorded; opt-in stealth.
• 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.
• 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.
• Recall + memory — cross-session memory that is drift-checked against source baselines ([Verifiable cognition](#verifiable-cognition)).
• Local models (korgex local). Hardware-aware advisor (CPU/RAM/GPU/VRAM → ranked, fit-scored picks via llmfit, optional) that can wire a local Ollama model as your default. On Apple Silicon, korgex local --omlx targets a running 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.

---

Safety & sandboxing

• 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.
• 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 neve

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: New1Direction
• Source: New1Direction/korgex
• License: MIT
• Homepage: https://korgex-docs.pages.dev

Install and usage instructions live in the source repository linked above.