Korg Ledger

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
• Quickstart
• The REPL — live in it
• How it works
• Verifiable cognition
• Tools
• Capabilities
• Safety & sandboxing
• CLI reference
• Environment variables
• Multi-model routing
• MCP integration
• Plugins
• Streaming TUI
• Architecture
• Project structure
• Development & testing
• Building & releasing
• Troubleshooting
• Known limitations
• 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

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 loop plan → act → verify"] AG -->|model id| PB{Provider} PB -->|"claude / anthropic/*"| ANT["Anthropic SDK"] PB -->|everything else| OAI["OpenAI-compatible SDK OpenAI · OpenRouter · Ollama · Grok · DeepSeek"] ANT --> TR["Tool router (src/tool_abstraction.py)"] OAI --> TR TR --> BT["Built-in tools Read · Edit · Bash · Grep · …"] TR --> MCP["MCP servers (any in mcp.json)"] TR --> CA["CodeAct kernel code = the action (opt-in)"] BT --> LED[("korg-ledger hash-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["prompt a1f3"] --> E1["Read 7c0e"] --> E2["Edit b42d"] --> E3["Bash: pytest 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

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