{"id":50363895,"url":"https://github.com/new1direction/korgex","last_synced_at":"2026-05-30T03:01:00.479Z","repository":{"id":360049991,"uuid":"1247938567","full_name":"New1Direction/korgex","owner":"New1Direction","description":"Autonomous AI Software Engineer — 41 tools, cloud sandbox, multimodal vision, GitHub API integration, plan-first workflow. Enterprise-grade open source.","archived":false,"fork":false,"pushed_at":"2026-05-24T19:45:13.000Z","size":301,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-24T20:23:13.965Z","etag":null,"topics":["ai-agent","autonomous-coding","cloud-sandbox","code-review","coding-agent","developer-tools","open-source","python","software-engineering"],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/New1Direction.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":"ROADMAP.md","authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-05-24T01:26:36.000Z","updated_at":"2026-05-24T19:45:16.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/New1Direction/korgex","commit_stats":null,"previous_names":["new1direction/korgex"],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/New1Direction/korgex","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/New1Direction%2Fkorgex","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/New1Direction%2Fkorgex/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/New1Direction%2Fkorgex/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/New1Direction%2Fkorgex/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/New1Direction","download_url":"https://codeload.github.com/New1Direction/korgex/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/New1Direction%2Fkorgex/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33678271,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-05-30T02:00:06.278Z","response_time":92,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-agent","autonomous-coding","cloud-sandbox","code-review","coding-agent","developer-tools","open-source","python","software-engineering"],"created_at":"2026-05-30T03:00:59.654Z","updated_at":"2026-05-30T03:01:00.471Z","avatar_url":"https://github.com/New1Direction.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# korgex\n\n**Autonomous coding agent. Provider-agnostic. MCP-native. Plan-first.**\n\nA terminal-native AI engineer that reads your codebase, edits files, runs commands, and ships work. Speaks both Anthropic and OpenAI tool-use protocols. Connects to any MCP server. Streams output live to your terminal. Open source, MIT-licensed, no vendor lock-in.\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\n---\n\n## Table of Contents\n\n- [Install](#install)\n- [Quickstart](#quickstart)\n- [How it works](#how-it-works)\n- [Verifiable cognition](#verifiable-cognition)\n- [CLI reference](#cli-reference)\n- [Tools](#tools)\n- [Environment variables](#environment-variables)\n- [Multi-model routing](#multi-model-routing)\n- [MCP integration](#mcp-integration)\n- [Streaming TUI](#streaming-tui)\n- [VS Code sidecar](#vs-code-sidecar)\n- [Dashboard API](#dashboard-api)\n- [Architecture](#architecture)\n- [Project structure](#project-structure)\n- [Development](#development)\n- [Testing](#testing)\n- [Building \u0026 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 korgex\n```\n\nRequires Python ≥ 3.10.\n\n### From GitHub Release\n\n```bash\npip install https://github.com/New1Direction/korgex/releases/download/v0.7.0/korgex-0.7.0-py3-none-any.whl\n```\n\n### From source\n\n```bash\ngit clone https://github.com/New1Direction/korgex.git\ncd korgex\npip install -e .\n```\n\n### From `git+https` (latest `main`)\n\n```bash\npip install git+https://github.com/New1Direction/korgex.git\n```\n\n### From PyPI\n\nPlanned. Until then use one of the above.\n\n---\n\n## Quickstart\n\n```bash\n# 1. Set an API key — either provider works\nexport ANTHROPIC_API_KEY=\"sk-ant-...\"\n# or\nexport OPENAI_API_KEY=\"sk-proj-...\"\n# or via OpenRouter (OpenAI-compatible, many models)\nexport KORGEX_API_KEY=\"sk-or-v1-...\"\nexport KORGEX_API_URL=\"https://openrouter.ai/api/v1\"\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 specific 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/\"\n```\n\n---\n\n## How it works\n\n```\n┌──────────────────────────────────────────────────────────────────┐\n│                     KORGEX AGENT LOOP                             │\n│                                                                  │\n│  user prompt                                                     │\n│     │                                                            │\n│     ▼                                                            │\n│  ┌─────────────────────────┐                                     │\n│  │  KorgexAgent.run_task() │                                     │\n│  └─────────────────────────┘                                     │\n│     │                                                            │\n│     ▼                                                            │\n│  ┌──────────────────────────────────────────────────────────┐    │\n│  │  for i in range(max_iter):                                │    │\n│  │    response = LLM.send(messages, tools)                   │    │\n│  │    if no tool_calls → return final text                   │    │\n│  │    for call in tool_calls:                                │    │\n│  │      result = route_tool_call(name, args)                 │    │\n│  │      messages.append(tool_result)                         │    │\n│  └──────────────────────────────────────────────────────────┘    │\n│     │                                                            │\n│     ▼                                                            │\n│  ┌─────────────────────────────────────────┐                     │\n│  │  Provider branching                      │                     │\n│  │  - \"claude\" in model → Anthropic SDK     │                     │\n│  │  - else → OpenAI SDK (works for          │                     │\n│  │    OpenAI, OpenRouter, Ollama, etc.)     │                     │\n│  └─────────────────────────────────────────┘                     │\n│     │                                                            │\n│     ▼                                                            │\n│  ┌─────────────────────────────────────────┐                     │\n│  │  Tool routing (src/tool_abstraction.py) │                     │\n│  │  - 12 Claude-Code-style user tools      │                     │\n│  │  - Adapter layer → Jules-style handlers │                     │\n│  │  - MCP-sourced tools → MCP manager       │                     │\n│  └─────────────────────────────────────────┘                     │\n└──────────────────────────────────────────────────────────────────┘\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.\n\n---\n\n## Verifiable cognition\n\nWhat sets korgex apart: 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, so a whole session can be cryptographically proven intact — any edit, deletion, reorder, or splice is detected and localized to the offending event.\n\n```bash\n# Prove a recorded run was not altered after the fact\nkorgex verify .korg/journal.jsonl\n#   ✓ ledger intact — 7 events, hash-chain verified      (exit 0; exit 1 + the bad seq_id if tampered)\n\n# Set KORG_LEDGER_HMAC_KEY to make the chain tamper-PROOF, not just tamper-evident\nexport KORG_LEDGER_HMAC_KEY=…\n```\n\nOn top of the chain, korgex tracks **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\n# Scan persistent memories for drift against their recorded source baselines\nkorgex drift\n#   ✗ memory DRIFT — 1 drifted … reconcile is recorded to the ledger    (exit 0 if none, 1 if drift)\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\n# Zero-config: audit your latest Claude Code session → a shareable, self-verifying report\nkorgex audit --html audit.html\n#   audited \u003csession\u003e → 2,319 ledger events\n#   chain:  ✓ INTACT — tamper-evident, cryptographically verifiable\n#   report: audit.html  ← open in any browser; it re-verifies itself\n```\n\nSee [Self-Coding Bench](docs/self-coding-bench.md) for live reliability data across five models.\n\n---\n\n## CLI reference\n\n```\n$ korgex --help\n\nusage: korgex [-h] SUBCOMMAND ...\n\nkorgex — autonomous coding agent. Pass a naked prompt to run the agent,\nor use a subcommand.\n\npositional arguments:\n  SUBCOMMAND\n    serve            Start dashboard + open VS Code with the sidecar.\n    dashboard        Start the web dashboard only.\n    init             Install Python deps + compile the VS Code extension.\n    status           Check if the backend is running.\n    stop             Stop the running backend.\n    install-extension\n                     Install the .vsix into VS Code.\n    verify           Prove the cognition ledger is intact (hash-chain proof).\n    drift            Scan memories for drift vs their source baselines.\n```\n\n### Naked-prompt invocation (the default)\n\nAny non-subcommand argument is treated as a prompt:\n\n```bash\nkorgex \"create a hello.txt with the text 'hi'\"\nkorgex --mode plan \"redesign the data model\"\nkorgex --model gpt-4o \"write the test for this fix\"\nkorgex --quiet \"list all functions called from main()\"\n```\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 text prints. Use this in pipes, scripts, CI. |\n| `--resume` | Not yet implemented — exits with code 2 so scripts don't silently lose state. |\n\n### Subcommands\n\n| Subcommand | Behavior |\n|---|---|\n| `korgex serve` | Starts the FastAPI dashboard on `localhost:8090` and opens VS Code with the sidecar. |\n| `korgex dashboard` | Starts the dashboard only (no editor). |\n| `korgex init` | One-shot setup: pip-installs deps, npm-installs + compiles the VS Code extension. |\n| `korgex status` | Reports whether the background backend is running. |\n| `korgex stop` | Terminates the background backend (SIGTERM, then SIGKILL if needed). |\n| `korgex install-extension` | Installs the compiled `.vsix` into your local VS Code. |\n| `korgex verify [journal]` | Verify the ledger's hash-chain is intact — proves the recorded run wasn't edited, deleted, reordered, or spliced (exit 0/1, CI-friendly). |\n| `korgex drift` | Scan persistent memories for drift against their recorded source baselines (exit 0/1). |\n\n---\n\n## Tools\n\nThe agent sees ~12 high-level tools (Claude-Code style), each with a deep description that includes usage guidance, edge cases, and anti-patterns:\n\n| Tool | Purpose |\n|---|---|\n| **Read** | Read a file from disk, optionally with line offset/limit. |\n| **Write** | Create a new file or overwrite an existing one with full content. |\n| **Edit** | Surgical string replacement in an existing file. Auto-converted to SEARCH/REPLACE block internally. |\n| **Bash** | Execute a shell command with timeout. |\n| **Grep** | Search file contents by regex (uses ripgrep where available). |\n| **Glob** | List files matching a pattern. |\n| **Agent** | Delegate a sub-task to a specialized sub-agent. |\n| **AskUserQuestion** | Ask the user a clarifying question with optional multiple-choice. |\n| **TaskCreate** | Track multi-step work via a task list. |\n| **Skill** | Invoke an installed skill by name. |\n| **ToolSearch** | Discover tools at runtime by keyword. |\n\nUnder the hood these route to 49+ internal handlers (file ops, git, GitHub API, sandbox execution, web fetch, dependency analysis, profiler, etc.) — see `src/tools_impl.py`.\n\n---\n\n## Environment variables\n\n| Variable | Purpose | Default |\n|---|---|---|\n| `ANTHROPIC_API_KEY` | Used when the model name contains \"claude\" or starts with \"anthropic/\". | — |\n| `OPENAI_API_KEY` | Used for any non-Anthropic model. | — |\n| `KORGEX_API_KEY` | Generic fallback if a provider-specific key isn't set. Useful for OpenRouter. | — |\n| `KORGEX_API_URL` | Base URL for OpenAI-compatible endpoints (set for OpenRouter, Ollama, etc.). | `https://api.openai.com/v1` |\n| `KORGEX_MODEL` | Default model when neither `--model` nor `--mode` is given. | `claude-sonnet-4-6` |\n| `KORGEX_MAX_ITERATIONS` | Maximum agent loop iterations before giving up. | `30` |\n| `KORGEX_MCP` | Set to `1` to auto-load MCP servers from `mcp.json` (equivalent to `--mcp`). | unset |\n| `KORGEX_SANDBOX` | `modal` \\| `docker` \\| `direct` \\| `auto`. Controls bash sandbox isolation. | `auto` |\n| `KORGEX_PROVIDER` | Force the transport (`openai` \\| `anthropic`), overriding model-id autodetect — e.g. drive `anthropic/*` or `google/*` models through OpenRouter. | autodetect |\n| `KORG_JOURNAL_PATH` | Path to the durable JSONL ledger journal; content-addressed blobs are written beside it. | `.korg/journal.jsonl` |\n| `KORG_LEDGER_HMAC_KEY` | If set, the ledger hash-chain is HMAC-keyed — tamper-*proof*, not just tamper-evident. | unset |\n\nProvider-detection rule: if the model id contains `\"claude\"` or starts with `\"anthropic/\"`, the agent uses the Anthropic SDK. Otherwise it uses the OpenAI SDK (which works against OpenAI, OpenRouter, Ollama, DeepSeek, vLLM, and anything else that speaks OpenAI's chat-completions protocol). Set `KORGEX_PROVIDER=openai` to force the OpenAI-compatible transport even for a `claude`/`anthropic/` model id — e.g. to drive Claude through 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\nkorgex includes a native MCP (Model Context Protocol) client. Any MCP server in your `mcp.json` becomes part of the agent's tool surface.\n\n### As an MCP server (verify / audit / import from any host)\n\nkorgex also *is* an MCP server — `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\nWire it into your host's MCP config:\n\n```json\n{ \"mcpServers\": { \"korg-ledger\": { \"command\": \"korgex\", \"args\": [\"mcp-server\"] } } }\n```\n\nListed in the [MCP Registry](https://registry.modelcontextprotocol.io/) —\n`mcp-name: io.github.New1Direction/korg-ledger`\n\n### Configure\n\nPlace an `mcp.json` in your repo root (matches the VS Code convention):\n\n```json\n{\n  \"mcpServers\": {\n    \"github\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@modelcontextprotocol/server-github\"],\n      \"env\": {\n        \"GITHUB_TOKEN\": \"ghp_...\"\n      }\n    },\n    \"filesystem\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@modelcontextprotocol/server-filesystem\", \"/tmp\"]\n    }\n  }\n}\n```\n\n### Use\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## Streaming TUI\n\nWhen stdout is a TTY, the agent streams output live via [Rich](https://rich.readthedocs.io/):\n\n- **Thinking blocks** render in dimmed italic gray (Anthropic only)\n- **Text** streams character-by-character\n- **Tool calls** show a transient spinner: `⠋ Read(file_path=src/foo.py)`\n- **Diffs** for Edit/Write on critical files prompt `[y/N]` confirmation\n- **Ctrl+C** sends a graceful interrupt; double Ctrl+C force-kills\n\nStreaming auto-disables when stdout is piped (e.g. `korgex \"...\" | tee log`), in CI, or with `--quiet`.\n\nOpenAI/OpenRouter streaming works just like Anthropic: text deltas pipe through the same renderer, tool-call deltas are accumulated across chunks into a complete tool call.\n\n---\n\n## VS Code sidecar\n\n`korgex-vscode/` contains a TypeScript extension that adds four commands (Cmd+Shift+P → \"korgex\"):\n\n| Command | Action |\n|---|---|\n| `korgex: Refactor Current File` | POSTs to `/api/swarm/refactor` |\n| `korgex: Run TDD Healer on Current File` | POSTs to `/api/swarm/heal` |\n| `korgex: Profile Test Suite` | POSTs to `/api/swarm/profile` |\n| `korgex: Open the Swarm Dashboard` | Opens `http://localhost:8090/dashboard` |\n\nTo install:\n\n```bash\nkorgex init                # compiles the .vsix\nkorgex install-extension   # installs it into your local VS Code\n```\n\nThe extension connects to `http://localhost:8090` by default, which matches the dashboard port. Adjust via the VS Code setting `korgex.backendUrl` if you change the port.\n\n---\n\n## Dashboard API\n\n`korgex serve` (or `korgex dashboard`) starts a FastAPI server on `:8090` with these endpoints:\n\n| Route | Method | Purpose |\n|---|---|---|\n| `/` | GET | HTML dashboard |\n| `/health` | GET | `{status: \"ok\"}` for liveness checks |\n| `/api/state` | GET | Current dashboard state (current task, plan, logs) |\n| `/api/new-task` | POST `{description}` | Start a new agent task in a background thread |\n| `/api/approve-plan` | POST | Approve a pending plan |\n| `/api/send-feedback` | POST `{feedback}` | Send mid-task feedback to the agent |\n| `/api/swarm/refactor` | POST `{filepath}` | Spin a one-shot agent that refactors the given file |\n| `/api/swarm/heal` | POST `{filepath, command}` | Spin a one-shot agent that fixes failing tests |\n| `/api/swarm/profile` | POST `{command}` | Run `cProfile` via `PerformanceProfiler` and return top-N slowest functions |\n| `/ws/logs` | WebSocket | Live log stream |\n\nAll swarm endpoints are synchronous (FastAPI thread-pools them) and return JSON: `{success, output, ...}` or `{success: false, error}` if a key is missing or the agent crashes.\n\n---\n\n## Architecture\n\n### Tool routing — Claude-Code-style → Jules-style\n\n```\nUser tool call (LLM-visible):     Internal handler (in 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(\n                                    filepath=...,\n                                    merge_diff=\"\u003c\u003c\u003c\u003c\u003c\u003c\u003c SEARCH\\n...\")\nBash(command=...)           →     tool_run_in_bash_session(command=...)\n```\n\nThe router (`src/tool_abstraction.py`):\n\n- Looks up the user-facing tool name in `_TOOL_ROUTING`\n- Applies a `param_map` (rename kwargs like `file_path → filepath`)\n- Or applies a custom `adapter` for structural transforms (Edit → SEARCH/REPLACE)\n- Filters out kwargs the handler doesn't accept (so schema fields like `Read.offset` don't crash handlers that haven't grown them yet)\n- Auto-injects `context={'repo_root': cwd}`\n- Catches exceptions and returns `{\"error\": ...}` so a single tool failure never kills the agent loop\n\nMCP-sourced tools bypass `_TOOL_ROUTING` and dispatch through `MCPServerManager.call_tool()` instead.\n\n### Provider branching\n\n```\nKorgexAgent(model=\"claude-sonnet-4-6\")  →  provider=\"anthropic\"\nKorgexAgent(model=\"anthropic/claude-...\")→  provider=\"anthropic\"  (OpenRouter)\nKorgexAgent(model=\"gpt-4o\")             →  provider=\"openai\"\nKorgexAgent(model=\"openai/gpt-4o-mini\") →  provider=\"openai\"      (OpenRouter)\nKorgexAgent(model=\"llama3:8b\")          →  provider=\"openai\"      (Ollama)\n```\n\nEach provider gets:\n- Its own tool-schema shape\n- Its own request method (`messages.create` vs `chat.completions.create`)\n- Its own streaming chunk parser\n- Its own assistant/tool-result message format\n\n### Plan-first system prompt\n\nThe default system prompt directs the agent to plan, verify, diagnose-before-changing, and never modify build artifacts. See `SYSTEM_PROMPT` in `src/agent.py`.\n\n---\n\n## Project structure\n\n```\nkorgex/\n├── src/\n│   ├── agent.py              # KorgexAgent class — main loop, provider branching, streaming\n│   ├── cli.py                # argparse dispatch (naked-prompt + subcommands)\n│   ├── tool_abstraction.py   # USER_TOOLS registry + router + MCP integration\n│   ├── tools_impl.py         # ~49 internal handlers (tool_read_file, tool_bash, ...)\n│   ├── tool_base.py          # Legacy Jules-style tool registry (still in use)\n│   ├── interactive.py        # Streaming TUI: Rich-based renderer, spinner, interrupt handler\n│   ├── model_router.py       # Mode → model mapping (plan/execute/debug/...)\n│   ├── mcp_client.py         # Native MCP client (stdio JSON-RPC 2.0)\n│   ├── dashboard.py          # FastAPI dashboard + /api/swarm/* endpoints\n│   ├── sandbox.py            # Docker / Modal / direct subprocess sandbox\n│   ├── swarm.py              # Multi-agent swarm orchestration\n│   ├── self_healing.py       # TDD self-healing loop\n│   ├── profiler.py           # cProfile-based perf profiler\n│   ├── dependency_graph.py   # AST-based import/symbol graph\n│   ├── context_compression.py# AST minimization for large files\n│   ├── diff_engine.py        # SEARCH/REPLACE diff parser\n│   ├── github_api.py         # GitHub PR / issue helpers\n│   ├── memory.py             # Cross-session memory (planned)\n│   ├── vision.py             # Image attachment handling\n│   └── ...\n├── korgex-vscode/            # VS Code sidecar extension (TypeScript)\n│   ├── src/extension.ts      # 4 registered commands\n│   ├── korgex-sidecar.vsix   # Compiled artifact (after `korgex init`)\n│   └── package.json\n├── tests/\n│   └── test_bridge.py        # 27 tests covering router, providers, MCP, streaming, dashboard\n├── docs/                     # CLI reference, comparison, getting-started\n├── scripts/                  # Build helpers (package-vsix.sh, MCP conformance test)\n├── packages/\n│   └── mcp-native-client/    # Standalone reusable MCP client package\n├── dist/                     # Built wheels and sdists\n├── mcp.json                  # Default MCP server config\n├── pyproject.toml            # Package metadata\n└── requirements.txt          # Pinned runtime deps\n```\n\n---\n\n## Development\n\n### Setup\n\n```bash\ngit clone https://github.com/New1Direction/korgex.git\ncd korgex\n\n# Create venv (uv recommended; falls back to python -m venv if you don't have uv)\nuv venv .venv\nsource .venv/bin/activate\n\n# Install with dev extras (pytest, twine, build, ruff)\nuv pip install -e \".[dev]\"\n\n# Or with plain pip\npip install -e \".[dev]\"\n```\n\n### Run the agent in editable mode\n\nAfter `pip install -e .`, `korgex` is on your PATH and reflects live source edits:\n\n```bash\nexport ANTHROPIC_API_KEY=sk-ant-...\nkorgex \"explain what src/agent.py does\"\n```\n\n### Code style\n\nThe project uses [ruff](https://docs.astral.sh/ruff/):\n\n```bash\nruff check src/\nruff format src/\n```\n\n---\n\n## Testing\n\n```bash\n# Run the full test suite\npytest tests/ -v\n\n# Run a specific test\npytest tests/test_bridge.py::test_write_routes_to_disk -v\n\n# With coverage\npytest tests/ --cov=src --cov-report=term-missing\n```\n\n### What the tests cover (27 cases)\n\n- **Router** (5): Read/Write/Edit route to handlers and produce filesystem effects; unknown tools return errors gracefully; the Edit adapter constructs valid SEARCH/REPLACE blocks; unsupported kwargs (Read.offset/limit) are filtered, not crashed.\n- **Provider schemas** (4): Anthropic and OpenAI tool-schema shapes are correct; OpenRouter `anthropic/...` IDs are detected; missing API keys raise `RuntimeError` cleanly.\n- **Mode routing** (5): `--mode plan` picks Opus, `--mode execute` picks Sonnet, `--mode debug` picks Haiku, explicit `--model` overrides, default falls back to Sonnet.\n- **MCP** (3): MCP tools register into `USER_TOOLS` correctly; the router dispatches them to the MCP manager; full connect→discover→call→disconnect round-trip against a real stub subprocess.\n- **Streaming** (5): Interactive mode auto-detects TTY; sessions are lazily constructed; OpenAI streaming accumulates text + multi-chunk tool calls into the right shape; text-only responses pass through.\n- **Dashboard** (5): `/health` returns ok; swarm endpoints reject missing args with 400; swarm endpoints return clean JSON errors when no API key is set.\n\nNo live LLM calls in the test suite — everything is unit-tested.\n\n---\n\n## Building \u0026 releasing\n\n### Build the wheel and sdist\n\n```bash\nrm -rf dist build\npython -m build\n# → dist/korgex-X.Y.Z-py3-none-any.whl\n# → dist/korgex-X.Y.Z.tar.gz\n\n# Validate PyPI metadata\npython -m twine check dist/*\n```\n\n### Cut a GitHub Release\n\n```bash\ngh release create vX.Y.Z \\\n  dist/korgex-X.Y.Z-py3-none-any.whl \\\n  dist/korgex-X.Y.Z.tar.gz \\\n  --title \"korgex X.Y.Z\" \\\n  --notes \"Release notes here\"\n```\n\n### Publish to PyPI\n\n```bash\npython -m twine upload dist/*\n# username: __token__\n# password: pypi-... (token from https://pypi.org/manage/account/token/)\n```\n\nFor the first upload of a new package, use an \"Entire account\" scoped token. After the package exists on PyPI, project-scoped tokens work.\n\n---\n\n## Troubleshooting\n\n### `korgex: No API key found`\n\nSet one of `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, or `KORGEX_API_KEY` (with `KORGEX_API_URL` for non-OpenAI endpoints).\n\n### `ModuleNotFoundError: No module named 'anthropic'` (or `openai`, or `rich`)\n\nThe dependency wasn't installed. Either:\n\n```bash\npip install -e .          # picks up everything from pyproject.toml\n# or\npip install anthropic openai rich\n```\n\n### Agent loops forever on tool calls\n\nThe default `KORGEX_MAX_ITERATIONS` is 30. If the agent genuinely can't finish:\n\n```bash\nexport KORGEX_MAX_ITERATIONS=10   # cap it harder\nkorgex --quiet \"...\"              # see only the final state\n```\n\n### `--mcp` takes a long time to start\n\nThe MCP client connects to each server synchronously at startup and waits up to 60s per server for the handshake. If your `mcp.json` references unreachable servers (missing `GITHUB_TOKEN`, `npx` not installed, network blocked), each one times out before being skipped. Remove unreachable entries from `mcp.json`, or reduce the per-server `timeout` value.\n\n### Streaming TUI swallows my prompt's output\n\n`korgex \"...\"` streams to stdout. If you need machine-readable output (e.g. piping to `jq`), use `--quiet`:\n\n```bash\nkorgex --quiet \"...\" | tee transcript.txt\n```\n\n### `403 Forbidden` from `twine upload`\n\nFor a brand-new package on PyPI, you need an **\"Entire account\"** scoped token, not a project-scoped one. Project-scoped tokens can't create a package they don't yet own. Re-create the token at https://pypi.org/manage/account/token/ with the wider scope, upload, then narrow the token for future releases.\n\n### VS Code extension commands do nothing\n\nThe extension POSTs to `http://localhost:8090/api/swarm/*` by default (matches the dashboard). Make sure:\n1. The backend is running: `korgex serve` or `korgex dashboard`\n2. The `korgex.backendUrl` setting in VS Code matches the port korgex is listening on (default `8090` on both sides)\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, content-block-start/stop, and message-delta usage events; OpenAI emits only text and tool-call chunks. The TUI renders both correctly but is richer for Anthropic.\n- **`--resume` is not yet implemented.** Exits with code 2 rather than silently starting fresh, so scripts and CI that rely on it fail loudly.\n- **Memory module is a stub.** `src/memory.py` exists but isn't wired into the agent loop.\n- **Swarm endpoints share the agent's single-context loop.** They don't actually run sub-agents in parallel sandboxes (the `swarm.py` module supports it, but the `/api/swarm/*` endpoints don't use it yet).\n- **TDD self-healing requires explicit invocation.** It's not yet triggered automatically on test failure.\n- **Dashboard authentication is not implemented.** Don't expose port 8090 publicly without putting a reverse proxy with auth in front of it.\n- **Dependency-graph and AST-compression tools (`src/dependency_graph.py`, `src/context_compression.py`) are not yet bridged into `USER_TOOLS`.** They're callable directly but not exposed to the agent.\n\n---\n\n## License\n\nMIT — see [LICENSE](LICENSE).\n\n---\n\n## Related projects\n\n- **[korg](https://github.com/New1Direction/korg)** — deterministic cognitive runtime for AI agents (Rust). korgex v0.3.0+ records every tool call into a korg ledger via the `korg_bridge` PyO3 extension; the ledger is what korg-tui rewinds and korgchat builds on.\n- **[korgchat](https://github.com/New1Direction/korgchat)** — chat product built on the same ledger; runs in the same `.korg/journal.json` as a korgex agent run, so you can interleave chat and autonomous edits.\n- **[thumper](https://github.com/New1Direction/thumper)** — local execution + recovery substrate that runs under korgex; pre-warmed sandbox pools, persistent LSP, sub-second compile-error healing.\n- **[Model Context Protocol](https://modelcontextprotocol.io/)** — the open MCP standard korgex implements.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnew1direction%2Fkorgex","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnew1direction%2Fkorgex","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnew1direction%2Fkorgex/lists"}