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

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<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"]