ikamensh/kodo: Autonomous Multi-Agent Coding That Runs Overnight

ikamensh/kodo: Autonomous Multi-Agent Coding That Runs Overnight

Developers with AI coding subscriptions face a frustrating ceiling: tools like Claude Code Max run at human speed, tethered to a terminal and a keyboard. You pay for unlimited access, then sleep through eight hours of potential compute. Meanwhile, single-agent sessions accumulate blind spots—resource leaks, state mutation, architectural drift—that only fresh eyes catch. ikamensh/kodo solves this by orchestrating multiple AI agents through independent work cycles with built-in verification, so your subscription keeps working after you log off.

What is ikamensh/kodo?

ikamensh/kodo is an open-source orchestrator for AI coding workflows, written in Python^{↗ Bright Coding Blog} and released under the MIT License. It directs multiple agent backends—Claude Code, Cursor, OpenAI Codex, Gemini CLI, Kimi, and Kiro—through structured tasks with independent review and testing. The project has 116 GitHub stars and 6 forks as of its last commit on July 16, 2026.

Kodo sits at the intersection of two emerging needs: maximizing subscription value for premium AI coding tools, and solving the verification problem that plagues autonomous code generation. A single Claude Code session might ship subtle bugs—class variable contamination, unclosed process pools, time-slice state mutation—that the same agent cannot see. Kodo's architecture separates roles: an orchestrator delegates tasks, workers implement code, and independent reviewers verify quality before acceptance.

The project's benchmark claim is specific and grounded: on a 100-task SWE-bench Verified head-to-head using the same underlying model (Cursor composer-1.5), Kodo's orchestration layer achieved 57% versus Cursor's standalone 46%—a 24% relative improvement in solving real-world GitHub issues. Same model, same prompt, same conditions; the difference is multi-agent orchestration with verification.

Key Features

Multi-backend agent support. Kodo integrates six AI coding tools: Claude Code for complex implementation and architecture review, Cursor and OpenAI Codex for fast iteration, Gemini CLI for free-tier fast workers, Kimi for deep-thinking tasks, and Kiro for general worker roles. You mix and match based on your existing subscriptions.

Role-separated verification. The orchestrator (typically Gemini Flash via API) assigns distinct roles: architect surveys codebases and catches design flaws, worker_smart handles complex implementation, worker_fast tackles quick iterations, tester runs verification suites, and tester_browser handles UI testing. These agents operate independently—an architect reviewing its own work would inherit the same blind spots.

Context window efficiency. Large tasks that overwhelm a single agent's context window succeed when split across multiple focused agents. Each agent receives only the scope it needs, with summaries bridging context between cycles.

Automatic checkpointing and resumption. Long runs persist progress across cycles. If interrupted, kodo --resume recovers from ~/.kodo/runs/ without losing work.

Three operational modes. kodo (with --goal) runs autonomous implementation toward a specified objective. kodo test exercises software like a real user—installing, feature-walking, edge-case probing, and regression test generation. kodo improve performs code review for simplification, usability, and architecture without running tests.

Cost transparency. Kodo distinguishes real API costs (orchestrator calls, ~$0.13/run for Gemini Flash) from virtual subscription costs (Claude Max workers show estimated API usage but incur no additional charge).

Use Cases

Overnight feature implementation. A developer sets a goal—"build an auto-solving meta-optimizer with four new algorithms"—before leaving for the evening. Kodo cycles through architect survey, parallel worker implementation, and multi-round verification. The documented example from blackopt completed in 3 hours with 2 cycles, 73 tests passing, after the architect caught 9 rounds of progressively subtler bugs.

Regression-free refactoring. Use kodo improve to audit a legacy codebase for unnecessary abstractions, duplicated logic, circular dependencies, and poor API naming. The architect agent filters findings skeptically, auto-fixes safe issues, and flags ambiguous cases for human decision rather than guessing.

Realistic integration testing. kodo test installs your software, exercises every CLI command and flag, probes empty inputs, huge inputs, invalid types, missing files, and concurrent usage. Unlike unit tests, this validates actual user workflows. Blocked workflows (needing Docker^{↗ Bright Coding Blog}, VPS, browser automation) are explicitly reported rather than silently skipped.

Subscription utilization optimization. Claude Code Max users paying for unlimited access can run Kodo continuously, directing their subscription-covered agents through meaningful work rather than idling overnight.

Distributed context workloads. Projects too large for a single agent's context window—multi-module refactors, cross-service API changes—succeed when Kodo partitions work across agents with focused scopes.

Installation & Setup

Kodo requires Python 3.13+ and the uv package manager.

Install uv (skip if present):

# Linux / macOS
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows PowerShell
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

Install Kodo:

uv tool install kodo-agent

This places kodo on your PATH. For the SWE-bench benchmark harness, add [benchmark]:

uv tool install 'kodo-agent[benchmark]'

Install at least one agent backend:

The recommended pairing is Claude Code plus one fast backend (Cursor, Codex, or Gemini CLI).

Configure the orchestrator API key:

# Recommended: Gemini Flash (fast, cheap)
GOOGLE_API_KEY=...     # in .env or environment

# Alternative: Claude API
ANTHROPIC_API_KEY=...

The README explicitly recommends API-based orchestrators over CLI-based ones: CLI coding tools are built to solve problems themselves and tend to micromanage or go off-script, while a plain API model stays in a coordination role closer to human user behavior.

Real Code Examples

Kodo's README documents usage through concrete CLI invocations rather than Python API calls. These are the primary interaction patterns:

Interactive mode (recommended for exploration):

# Run in current directory with guided setup
kodo

# Run in specific project directory
kodo ./my-project

The interactive CLI walks through goal specification (or reuse of existing goal.md), optional Claude-based refinement, team/orchestrator selection, and confirmation before launching. A live progress table displays as agents work.

Non-interactive mode (for scripting, CI, overnight cron):

# Inline goal
kodo --goal 'Build a REST API for user management' ./my-project

# Goal from file
kodo --goal-file requirements.md ./my-project

# Full configuration for extended runs
kodo --goal 'Build X' --team full --exchanges 50 --cycles 10 ./my-project

The --yes flag skips confirmations; --json outputs structured data for pipeline integration.

Testing mode:

# Full realistic user testing
kodo test

# Focus on specific area
kodo test --focus 'auth module'

# Scope to specific paths
kodo test --target src/api/

Improvement mode:

# Full codebase review
kodo improve

# Focus on CLI interface
kodo improve --focus 'CLI flags'

Resuming interrupted runs:

# Resume latest incomplete run in current directory
kodo --resume

# Resume specific run by ID
kodo --resume 20260218_205503

Run IDs are printed at completion and stored in ~/.kodo/runs/.

Custom team configuration (JSON, no code changes required):

{
  "name": "saga-with-designer",
  "agents": {
    "worker_fast": {
      "backend": "claude",
      "model": "sonnet",
      "description": "Fast worker for implementation tasks."
    },
    "designer": {
      "backend": "claude",
      "model": "opus",
      "description": "UX/UI advisor. Reviews component structure, accessibility, interaction patterns.",
      "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.",
      "max_turns": 10,
      "timeout_s": 600,
      "fallback_model": "sonnet"
    }
  }
}

Place at {project}/.kodo/team.json for project-level override or ~/.kodo/teams/{name}.json for user-level reuse.

Advanced Usage & Best Practices

Effort levels control agent behavior and verification strictness. The four levels—low, standard (default), high, max—affect orchestrator iteration pressure, evidence requirements for verification, and Claude worker effort flags. For overnight runs where you cannot intervene, max provides the most thorough verification at the cost of longer runtime. Set via --effort max or .kodo/config.json.

Team composition should match your task topology. The default full team includes all roles; quick and test teams are leaner presets. For security-sensitive code, add a dedicated auditor agent in team.json. For performance-critical paths, add a profiling specialist.

Goal refinement matters. The --auto-refine flag enables AI goal refinement without human input—useful for overnight runs, but risky for ambiguous objectives. For exploratory work where you don't know the solution shape, the README explicitly recommends using Claude Code directly rather than Kodo.

Git hygiene is essential. The README warns that agents run with bypassPermissions mode and can access any file on your system. Commit or backup before launching.

Cost tracking separates real from virtual spend. Monitor the API bucket (actual dollars) separately from virtual estimates (subscription-covered usage shown for visibility).

Comparison with Alternatives

Kodo does not replace these tools—it orchestrates them. The trade-off is setup complexity and orchestrator cost against the gain of autonomous, verified, multi-cycle execution. For tasks needing frequent human steering or exploratory discovery, the README itself recommends using Claude Code directly. For well-scoped, substantial implementation with overnight time available, Kodo's verification architecture provides value that single-agent tools cannot match.

FAQ

Does Kodo work without a Claude Code Max subscription? Yes, but Claude Code is recommended for smart workers. You can use Cursor, Codex, Gemini CLI, Kimi, or Kiro as alternatives or supplements.

What does the orchestrator cost? Gemini Flash API runs approximately $0.13 per run. Claude API orchestrator is an alternative. Worker costs through subscription tools are virtual—shown for tracking, not charged.

Can agents damage my system? Agents run with bypassPermissions and can access any file. The README explicitly warns: commit or backup before launching.

How do I resume after a crash? Use kodo --resume for the latest run, or kodo --resume RUN_ID for a specific one. Runs are stored in ~/.kodo/runs/.

What Python version is required? Python 3.13 or higher, installed via uv.

Is there a web UI for reviewing runs? A local HTML viewer is available: python -m kodo.viewer ~/.kodo/runs/RUN_ID/log.jsonl. Add --serve --port 8080 to expose via HTTP.

Can I use my own orchestrator model? The --orchestrator-model flag supports opus, sonnet, gemini-pro, and gemini-flash. Custom orchestrators require code changes.

Conclusion

ikamensh/kodo fills a specific, well-defined gap: turning idle subscription hours into verified, multi-agent development cycles. It is not a replacement for interactive AI coding tools but an orchestration layer that makes them more effective for well-scoped, substantial tasks. The 57% SWE-bench result versus 46% for the same model without orchestration demonstrates that verification and role separation matter measurably.

This tool suits developers who already pay for premium AI coding subscriptions, have tasks large enough to benefit from overnight execution, and can tolerate setup complexity for autonomous operation. It is less suited to exploratory work, learning, or projects requiring constant human steering.

If you have Claude Code Max and wake up wishing your terminal had kept working, explore ikamensh/kodo on GitHub.