{"id":48515847,"url":"https://github.com/ikamensh/kodo","last_synced_at":"2026-04-07T19:02:35.674Z","repository":{"id":339467631,"uuid":"1160719064","full_name":"ikamensh/kodo","owner":"ikamensh","description":"Orchestrator for AI coding (claude code, cursor, codex, gemini)","archived":false,"fork":false,"pushed_at":"2026-03-21T22:05:42.000Z","size":4583,"stargazers_count":39,"open_issues_count":0,"forks_count":2,"subscribers_count":2,"default_branch":"dev","last_synced_at":"2026-03-21T22:34:14.828Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","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/ikamensh.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"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-02-18T09:40:03.000Z","updated_at":"2026-03-21T22:05:46.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/ikamensh/kodo","commit_stats":null,"previous_names":["ikamensh/kodo"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/ikamensh/kodo","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ikamensh%2Fkodo","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ikamensh%2Fkodo/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ikamensh%2Fkodo/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ikamensh%2Fkodo/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ikamensh","download_url":"https://codeload.github.com/ikamensh/kodo/tar.gz/refs/heads/dev","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ikamensh%2Fkodo/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31524531,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-07T16:28:08.000Z","status":"ssl_error","status_checked_at":"2026-04-07T16:28:06.951Z","response_time":105,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"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":[],"created_at":"2026-04-07T19:02:30.477Z","updated_at":"2026-04-07T19:02:35.665Z","avatar_url":"https://github.com/ikamensh.png","language":"Python","funding_links":[],"categories":["Multi-Agent Swarms","Harnesses \u0026 orchestration"],"sub_categories":["Orchestrators \u0026 autonomous loops"],"readme":"\u003cp align=\"center\"\u003e\n  \u003cimg src=\"docs/logo.png\" width=\"300\"\u003e\n  \u003cbr\u003e\u003cbr\u003e\n  \u003cstrong\u003eBuilding while you sleep.\u003c/strong\u003e\n  \u003cbr\u003e\u003cbr\u003e\n  \u003ca href=\"https://www.python.org/\"\u003e\u003cimg src=\"https://img.shields.io/badge/python-3.13+-blue?logo=python\u0026logoColor=white\" alt=\"Python 3.13+\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/ikamensh/kodo/blob/main/LICENSE\"\u003e\u003cimg src=\"https://img.shields.io/badge/license-MIT-green\" alt=\"MIT License\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://docs.anthropic.com/en/docs/claude-code\"\u003e\u003cimg src=\"https://img.shields.io/badge/Claude_Code-Max-blueviolet?logo=anthropic\u0026logoColor=white\" alt=\"Claude Code\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://cursor.com\"\u003e\u003cimg src=\"https://img.shields.io/badge/Cursor-supported-orange?logo=cursor\u0026logoColor=white\" alt=\"Cursor\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/openai/codex\"\u003e\u003cimg src=\"https://img.shields.io/badge/Codex-supported-green?logo=openai\u0026logoColor=white\" alt=\"OpenAI Codex\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/google-gemini/gemini-cli\"\u003e\u003cimg src=\"https://img.shields.io/badge/Gemini_CLI-supported-blue?logo=google\u0026logoColor=white\" alt=\"Gemini CLI\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/nicepkg/kimi-cli\"\u003e\u003cimg src=\"https://img.shields.io/badge/%F0%9F%8C%99_Kimi-supported-red\" alt=\"Kimi\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://kiro.dev/cli/\"\u003e\u003cimg src=\"https://img.shields.io/badge/👻_Kiro-supported-yellow?logo=amazonaws\u0026logoColor=white\" alt=\"Kiro\"\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n---\n\n# 🦉 kodo\n\nAutonomous multi-agent coding that runs overnight on your Claude Code Max subscription. An orchestrator directs Claude Code agents through work cycles with independent verification — so you wake up to tested, reviewed code instead of a stale terminal.\n\n### [SWE-bench Verified: Kodo 57% vs Cursor 46%](https://kodo-bench-h2h-430011644943.europe-west1.run.app/)\n\nOn a 100-task head-to-head using the same underlying model (Cursor `composer-1.5`), adding Kodo's orchestration layer solves 24% more real-world GitHub issues. Same model, same prompt, same conditions — the difference is orchestration. [Full methodology and interactive results →](https://kodo-bench-h2h-430011644943.europe-west1.run.app/)\n\n## Overview\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"docs/diagrams/overview.svg\" width=\"800\" alt=\"Kodo modes overview — Goal, Improve, and Test\"\u003e\n\u003c/p\u003e\n\nSee [detailed mode diagrams](docs/modes_diagram.md) for the full pipeline of each mode.\n\n## 🎬 How it works in practice\n\nReal run from [blackopt](https://github.com/ikamen/blackopt) — building an auto-solving meta-optimizer with 4 new algorithms, adaptive scheduling, and 73 tests. **3 hours unattended, 2 cycles, succeeded.**\n\n```\n🔍 [00:00] orchestrator → architect\n           \"Survey the codebase — Solver interface, existing algorithms,\n            where to add new ones.\"\n📋 [03:04] architect reports back\n           Full architecture survey, found 3 bugs in existing code\n\n🔧 [03:14] orchestrator → worker_smart\n           \"Fix structural bugs identified by architect\"\n✅ [11:29] worker_smart: 82 turns of editing. All bugs fixed, tests pass.\n\n⚡ [12:36] orchestrator → architect: \"Analyze how to implement DE and PSO\"\n   [15:22] orchestrator → worker_fast: \"Implement TabuSearch and EDA\"\n   [16:01] orchestrator → worker_smart: \"Build autosolve() — concurrent\n                          portfolio, adaptive scheduling\"\n\n🏁 [35:20] orchestrator → done(\"autosolve complete, 4 new algorithms\")\n           → tester:          runs tests ✅\n           → tester_browser:  runs tests ✅\n           → architect:       \"ProcessPool is never closed — resource leak\" ❌\n           REJECTED\n\n🔧 [45:37] orchestrator → worker_smart: \"Fix the resource leak\"\n           → done() → architect: \"class-variable contamination\" ❌\n           REJECTED\n\n           ... 7 more verification rounds ...\n           architect catches: time-slice state mutation, exponential\n           offspring, crossover edge case — each progressively more subtle\n\n🎉 [2:59:50] → done() → tester ✅ → tester_browser ✅ → architect ✅\n             ACCEPTED — \"4 new algorithms, autosolve() API, 73 tests pass\"\n```\n\nThe architect verifier caught **9 rounds of bugs** that the worker agent was blind to — resource leaks, class variable contamination, state mutation — each subtler than the last. A single Claude Code session would likely have shipped with several of these.\n\n## 🦉 When to use kodo\n\nYou have a Claude Code Max subscription. You can't use it while you sleep.\n\nkodo lets you set a goal, go to bed, and wake up to working code that's been independently tested and reviewed. The orchestrator (Gemini Flash) directs your subscription-covered Claude Code agents through multiple work cycles with built-in QA.\n\n\u003ctable\u003e\n\u003ctr\u003e\u003ctd nowrap\u003e🌙 \u003cstrong\u003eOvernight runs\u003c/strong\u003e\u003c/td\u003e\u003ctd\u003eSet a goal, leave it running for hours. Cycles checkpoint progress automatically.\u003c/td\u003e\u003c/tr\u003e\n\u003ctr\u003e\u003ctd nowrap\u003e🔍 \u003cstrong\u003eBuilt-in verification\u003c/strong\u003e\u003c/td\u003e\u003ctd\u003eIndependent architect + tester agents review work before accepting. Catches bugs the implementing agent is blind to.\u003c/td\u003e\u003c/tr\u003e\n\u003ctr\u003e\u003ctd nowrap\u003e🎭 \u003cstrong\u003eRole separation\u003c/strong\u003e\u003c/td\u003e\u003ctd\u003eOrchestrator making judgment calls, workers building code, independent reviewers catching issues.\u003c/td\u003e\u003c/tr\u003e\n\u003ctr\u003e\u003ctd nowrap\u003e🧠 \u003cstrong\u003eContext efficiency\u003c/strong\u003e\u003c/td\u003e\u003ctd\u003eWork is spread across multiple agent context windows, so tasks that might overwhelm a single agent's context can succeed when agents take turns with focused scopes.\u003c/td\u003e\u003c/tr\u003e\n\u003c/table\u003e\n\n## 🧑‍💻 When to just use Claude Code directly\n\n\u003ctable\u003e\n\u003ctr\u003e\u003ctd nowrap\u003e📖 \u003cstrong\u003eLearning\u003c/strong\u003e\u003c/td\u003e\u003ctd\u003eYou want to stay in the loop and build intuition by watching decisions unfold.\u003c/td\u003e\u003c/tr\u003e\n\u003ctr\u003e\u003ctd nowrap\u003e🧭 \u003cstrong\u003eExploration\u003c/strong\u003e\u003c/td\u003e\u003ctd\u003eYou don't know what you want yet and are discovering the shape of the solution as you go.\u003c/td\u003e\u003c/tr\u003e\n\u003ctr\u003e\u003ctd nowrap\u003e🎮 \u003cstrong\u003eSteering\u003c/strong\u003e\u003c/td\u003e\u003ctd\u003eThe task needs frequent course corrections that only a human at the keyboard can provide.\u003c/td\u003e\u003c/tr\u003e\n\u003c/table\u003e\n\n## 📦 Install\n\n1. You need uv to install kodo.\n   \n**Linux / macOS:**\n```bash\ncurl -LsSf https://astral.sh/uv/install.sh | sh   # install uv (skip if you have it)\n```\n\n**Windows (PowerShell):**\n```powershell\npowershell -ExecutionPolicy ByPass -c \"irm https://astral.sh/uv/install.ps1 | iex\"   # install uv (skip if you have it)\n```\n\n2. Install kodo using uv\n```bash\nuv tool install git+https://github.com/ikamensh/kodo\n```\n\nThat's it. `kodo` is now on your PATH.\n\nTo also install the **SWE-bench benchmark harness** (`kodo-bench`):\n```bash\nuv tool install --with 'kodo[benchmark]' git+https://github.com/ikamensh/kodo\n```\n\n### Prerequisites\n\nYou need **at least one** agent backend installed:\n\n| Backend | Role | Setup |\n|---------|------|-------|\n| 🤖 [Claude Code](https://code.claude.com/docs/en/setup) | Smart workers + architect | [instructions](docs/providers.md#claude-code-smart-workers--architect) |\n| ⚡ [Cursor](https://cursor.com/docs/cli/installation) | Fast workers + testers | [instructions](docs/providers.md#cursor-fast-workers--testers) |\n| 🌀 [OpenAI Codex](https://github.com/openai/codex/blob/main/docs/install.md) | Fast workers | [instructions](docs/providers.md#openai-codex-fast-workers) |\n| 💎 [Gemini CLI](https://geminicli.com/docs/get-started/installation/) | Fast workers (free tier) | [instructions](docs/providers.md#gemini-cli-fast-workers) |\n| 🌙 [Kimi](https://www.kimi.com/code/docs/en/kimi-cli/guides/getting-started.html) | Smart workers | [instructions](docs/providers.md#kimi-smart-workers) |\n| 👻 [Kiro](https://kiro.dev/docs/cli/installation/) | Workers | [instructions](docs/providers.md#kiro-workers) |\n\nClaude Code + one fast backend (Cursor, Codex, or Gemini CLI) is recommended. See [docs/providers.md](docs/providers.md) for detailed setup instructions, authentication, and troubleshooting.\n\nFor the **API orchestrator** (recommended), set a key in `.env` or your environment:\n```bash\nGOOGLE_API_KEY=...     # Gemini orchestrator (recommended — fast and cheap)\nANTHROPIC_API_KEY=...  # Claude API orchestrator (alternative)\n```\n\n\u003e **Why API over CLI orchestrators?** CLI coding tools (Claude Code, Cursor, Codex) are built to solve problems themselves — they'll try to write code, micromanage agents, or go off-script instead of purely delegating. A plain API model stays in its lane as a coordinator: it thinks high level and delegates, closer to human user behavior.\n\n## 🚀 Usage\n\n```bash\n# Interactive mode (recommended) — walks you through goal, config, launch\nkodo                     # run in current directory\nkodo ./my-project        # run in specific directory\n\n# Non-interactive (for scripting, CI, overnight cron jobs)\nkodo --goal 'Build a REST API for user management' ./my-project\nkodo --goal-file requirements.md ./my-project\nkodo --goal 'Build X' --team full --exchanges 50 --cycles 10 ./my-project\n\n# Test — find bugs through realistic interaction (not unit tests)\nkodo test                            # test current project\nkodo test --focus 'auth module'      # focus on specific area\nkodo test --target src/api/          # scope to specific files/dirs\n\n# Improve — code review for simplification, usability, architecture\nkodo improve                         # review current project\nkodo improve --focus 'CLI flags'     # focus on specific area\n\n# Fix findings from a previous test or improve run\nkodo --fix-from \u003cRUN_ID\u003e             # printed at end of test/improve runs\n\n# Resume an interrupted run (looks in ~/.kodo/runs/)\nkodo --resume                       # resume latest incomplete run in current dir\nkodo --resume 20260218_205503       # resume specific run by ID\n```\n\n### Interactive mode\n\nThe interactive CLI will:\n1. Ask for your goal (or reuse an existing `goal.md`)\n2. Optionally refine it via a Claude interview\n3. Let you pick team, orchestrator, and limits\n4. Show a summary and ask for confirmation before starting\n5. Print a live progress table as agents work\n\n### Non-interactive mode\n\nPassing `--goal` or `--goal-file` enables non-interactive mode — no prompts, no confirmations. The AI still breaks down your goal into stages (unless `--skip-intake` is set), but without asking clarifying questions.\n\n### All flags\n\n```\nkodo [project_dir] [options]\n\nGoal (mutually exclusive):\n  --goal TEXT               Goal text (inline)\n  --goal-file PATH          Path to file containing goal\n  --improve                 Code review: simplification, usability, architecture\n  --test                    Find bugs through realistic interaction and workflows\n  --fix-from RUN_ID         Fix findings from a previous test or improve run\n\nTest/Improve options:\n  --focus TEXT              Steer toward a specific area (e.g. 'error handling')\n  --target PATH             Scope --test to specific files/dirs (repeatable)\n\nConfiguration:\n  --team TEAM               full (default) | quick | test\n  --exchanges N             Max exchanges per cycle\n  --cycles N                Max cycles\n  --orchestrator BACKEND    api (default) | claude-code | gemini-cli | codex | cursor\n  --orchestrator-model M    opus | sonnet | gemini-pro | gemini-flash\n\nBehavior:\n  --effort LEVEL            low | standard (default) | high | max\n  --skip-intake             Skip AI goal refinement\n  --auto-refine             Auto-refine goal (no human input, for overnight runs)\n  --yes, -y                 Skip confirmation prompts\n  --no-auto-commit          Disable auto-commit after stages\n\nOutput:\n  --json                    Structured JSON to stdout (implies --yes)\n  --resume [RUN_ID]         Resume an interrupted run\n  --version                 Show version\n```\n\n\n\u003e **⚠️ Heads up:** agents run with full permissions (`bypassPermissions` mode). They primarily work in your project directory but **can access any file on your system** (installing dependencies, editing configs, etc.). Make sure you have a git commit or backup before launching.\n\n### `kodo test` — test like a real user\n\nTests your software the way a real user would — install it, exercise every feature, then probe edge cases.\n\n1. **Setup \u0026 Discovery**: installs the software, builds testing tools (CLI wrappers, fixtures, sample data), maps all user-facing features and workflows\n2. **Feature Walkthroughs**: exercises every feature end-to-end — follows documented workflows, tries every CLI command and flag, tests happy paths and common error cases\n3. **Edge Cases \u0026 Error Paths**: probes boundaries — empty inputs, huge inputs, invalid types, missing files, concurrent usage, interruption mid-operation\n4. **Triage \u0026 Regression Tests**: for confirmed bugs, writes a test that fails, fixes the code, verifies the test passes\n\nIf agents need tools they can't build (Docker, VPS, browser automation), they say so in the **Blocked Workflows** section of the report. On repeated runs, previously-tested features are skipped based on coverage tracking in `.kodo/test-coverage.md`.\n\n```bash\nkodo test                                # full test run\nkodo test --focus 'authentication'       # focus on area\nkodo test --target src/api/ --target src/auth/  # scope to files\n```\n\n### `kodo --improve` — code review for significant improvements\n\nReviews your codebase like a senior developer joining the project. Focuses on simplification, usability, and architecture — not on running tests (use `kodo test` for that).\n\n1. **Simplification**: unnecessary abstractions, duplicated logic, dead code, things that reimplement stdlib\n2. **Usability**: redundant CLI flags, confusing API naming, poor error messages, missing defaults, docs that contradict code\n3. **Architecture**: module boundaries, dependency directions, circular deps, scattered responsibilities\n4. **Triage**: skeptically filters findings — most don't survive scrutiny\n5. **Fix \u0026 Report**: auto-fixes safe issues, flags ambiguous ones as \"needs decision\"\n\n```bash\nkodo --improve                           # full review\nkodo --improve --focus 'CLI interface'   # focus on area\n```\n\n### Subcommands\n\n```bash\nkodo test                     # find bugs through realistic testing\nkodo runs                     # list all past runs\nkodo runs ./my-project        # list runs for a specific project\nkodo issue [RUN_ID]           # report a bug (opens GitHub with run context pre-filled)\nkodo backends                 # show available backends, models, API key status\nkodo teams                    # list available teams\nkodo teams add my-team        # interactively create a custom team\nkodo teams edit my-team       # edit an existing team\nkodo teams delete             # pick user team files to remove (same listing style as `kodo teams`)\n```\n\n```\n🦉 Orchestrator (Gemini Flash)\n │\n ├── 🔍 architect        Survey codebase, review code, find bugs\n ├── 🧠 worker_smart     Complex implementation (Claude Code)\n ├── ⚡ worker_fast       Quick tasks, iterations (Cursor, Codex, or Gemini CLI)\n ├── 🧪 tester           Run tests, verify behavior\n └── 🌐 tester_browser   Browser-based UI testing\n```\n\n### Effort levels\n\nControl how hard agents work and how strict verification is:\n\n| Level | Orchestrator behavior | Verification | Claude workers |\n|-------|----------------------|-------------|----------------|\n| `low` | Do exactly what's asked, don't over-engineer | Basic — tests passing is sufficient | `--effort low` |\n| `standard` | Default behavior | Default | SDK default |\n| `high` | Push agents to iterate, reject mediocre results | Thorough — verify each criterion with evidence | `--effort high` |\n| `max` | Tackle hardest parts first, iterate aggressively | Skeptical — reject technically correct but mediocre work | `--effort max` |\n\nSet via CLI (`--effort max`) or project config (`.kodo/config.json`):\n```json\n{ \"effort\": \"max\" }\n```\n\n**Key concepts:**\n\n- **Session** — a stateful conversation with a backend (Claude, Cursor, Codex, Gemini CLI, Kimi, or Kiro). Tracks token usage, supports reset.\n- **Agent** — a prompt + session + turn budget. Call `agent.run(task, project_dir)` to get work done.\n- **Orchestrator** — an LLM that delegates to a team of agents via tool calls:\n  - `ClaudeCodeOrchestrator` — runs on Claude Code with agents as MCP tools. Free on Max subscription.\n  - `ApiOrchestrator` — runs on Anthropic/Gemini API. Pay-per-token orchestrator, but workers still use your subscription.\n- **Cycle** — one unit of orchestrated work. Think of it as one dev session.\n- **Run** — multiple cycles until done, with summaries bridging context between cycles.\n- **Stage** — an independently verifiable piece of a plan. Stages run sequentially, or in parallel in git worktrees when grouped.\n\n## 🎨 Custom teams\n\nYou can customize which agents run by dropping a `team.json` file — no code changes needed.\n\n**Lookup order:**\n1. `{project}/.kodo/team.json` — project-level override\n2. `~/.kodo/teams/{name}.json` — user-level named team\n\n**Example:** adding a UX/UI designer agent to review user-facing code:\n\n```json\n{\n  \"name\": \"saga-with-designer\",\n  \"agents\": {\n    \"worker_fast\": {\n      \"backend\": \"claude\", \"model\": \"sonnet\",\n      \"description\": \"Fast worker for implementation tasks.\"\n    },\n    \"worker_smart\": {\n      \"backend\": \"claude\", \"model\": \"opus\",\n      \"description\": \"Deep-thinking worker for complex tasks.\"\n    },\n    \"tester\": {\n      \"backend\": \"claude\", \"model\": \"sonnet\",\n      \"description\": \"Runs tests and reports results.\",\n      \"max_turns\": 10\n    },\n    \"architect\": {\n      \"backend\": \"claude\", \"model\": \"opus\",\n      \"description\": \"Reviews architecture, validates direction.\",\n      \"max_turns\": 10, \"timeout_s\": 600\n    },\n    \"designer\": {\n      \"backend\": \"claude\", \"model\": \"opus\",\n      \"description\": \"UX/UI advisor. Reviews component structure, accessibility, interaction patterns. Provides file/line references.\",\n      \"system_prompt\": \"You are a UX/UI design advisor. Review code for UI structure, accessibility, responsive design, and consistency. Reference specific files and lines. Fix minor issues yourself. Say 'ALL CHECKS PASS' if clean.\",\n      \"max_turns\": 10, \"timeout_s\": 600,\n      \"fallback_model\": \"sonnet\"\n    }\n  }\n}\n```\n\nThe orchestrator sees all agents in the team and delegates to them as needed. You can add any specialized reviewer (security auditor, performance analyst, etc.) the same way.\n\n**Agent fields:** `backend` and `model` are required. Optional: `description`, `system_prompt`, `max_turns` (default 15), `timeout_s`, `chrome` (for browser agents), `fallback_model`.\n\n## 💰 Cost tracking\n\nKodo tracks costs in two buckets:\n\n| Bucket | What | Example |\n|--------|------|---------|\n| **🔑 API** | Real money — pay-per-token orchestrator calls | Gemini Flash orchestrator: ~$0.13/run |\n| **✨ Virtual** | **Not charged.** Claude Code SDK reports what API usage *would* cost — but on a Max/Pro subscription you pay nothing extra. | Claude Max workers: shows ~$1.69, actual spend $0 |\n\nThe progress table labels subscription-covered costs as **Virtual** to make this clear. Only the **API** bucket represents real spend.\n\n## 🔎 Analyzing past runs\n\n```bash\n# Open the interactive HTML viewer\npython -m kodo.viewer ~/.kodo/runs/20260218_205503/log.jsonl\n# Or serve on port 8080: python -m kodo.viewer --serve --port 8080 \u003clogfile.jsonl\u003e\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fikamensh%2Fkodo","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fikamensh%2Fkodo","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fikamensh%2Fkodo/lists"}