Most tools force a choice: good harness or good workflow.

You end up either wiring raw CLI tools into your own scripts, or accepting opinionated wrappers that bury settings, collapse planning into execution, and lock you to one provider.

	What you have today	What you actually need
	One mode for everything	Distinct modes for distinct intents
	Settings buried in implementation	A first-class configuration surface
	Locked to one provider	Harness choice per project, per session
	Prompts as you typed them	Prompts refined to your intent level

Kōdō Code reduces cognitive overhead by separating exploration, planning, execution, and validation into distinct modes.

Kōdō Code gives you both. Codex and Claude execute. Kōdō orchestrates.

Kōdō (香道) — the Japanese Way of Incense — centers on ritual, attention, and deliberate choice.

Kōdō Code applies that same idea to software development: a structured coding environment where thinking, planning, execution, and review stay separate and intentional.

It wraps Codex CLI and Claude Agent SDK in a clearer workflow, without reinventing what those harnesses already do well.

flowchart LR
    ASK("[?] Ask\nExplore")
    PLAN("[#] Plan\nStrategize")
    CODE("[>] Code\nExecute")
    REVIEW("[v] Review\nValidate")

    ASK --> PLAN --> CODE --> REVIEW

    style ASK    fill:#1e293b,stroke:#475569,color:#94a3b8
    style PLAN   fill:#1e3a5f,stroke:#3b82f6,color:#93c5fd
    style CODE   fill:#14532d,stroke:#22c55e,color:#86efac
    style REVIEW fill:#2e1065,stroke:#a78bfa,color:#c4b5fd

Kōdō Code is built around a simple rule: you should not have to think, plan, execute, and validate in the same mental mode.

Ask Mode  —  question without execution

Probe your codebase and your agents before committing to anything. Ask without triggering execution.

• "Can we add this feature without breaking the mobile layout?"
• "How hard would it be to implement real-time sync?"
• "What changed in the last three PRs?"

No side effects. No surprises. Just answers.

Plan Mode  —  strategize before you build

Designate a dedicated planning model — higher reasoning, slower deliberation — to map out your next move before a single file is touched.

• "Design an approach to fix this long-standing bug."
• "Break down this feature into safe, reviewable increments."

Plans are artifacts. They carry forward into execution.

Code Mode  —  build with precision

Switch to your acting model — optimized for speed and accuracy — and execute with the full weight of your approved plan.

• Rich diffs, terminal output, and execution visibility
• Context carried forward from your plan
• Auto-switches to your designated acting model

Review Mode  —  verify and validate

You built it. Now make sure it actually works — and that you didn't break anything you weren't looking at.

• "Make sure the new backend handles edge cases."
• "Look for regressions for users coming from an older version."
• "Run the test suite and tell me what's left to fix."

Dual Harness Support  —  your choice of execution engine

The same workflow semantics, regardless of which harness runs underneath.

• Codex CLI — OpenAI's native agent harness
• Claude Agent SDK — Anthropic's agent SDK

Switch per-project. Switch per-session. The orchestration layer doesn't care — it stays consistent either way.

Plans as Artifacts  —  plans that persist and carry forward

Plans aren't just conversation turns — they're stored artifacts with state. A plan created in Plan Mode persists, can be referenced later, and tracks whether it's been implemented. Code Mode carries the approved plan forward as structured context, not just chat history.

flowchart TD
    UI["UI\nKōdō Desktop\nAsk · Plan · Code · Review"]
    ORC["Core\nKōdō Orchestrator\nModel switching · Enhance pipeline\nWorkflow state · Settings & policy"]
    CODEX["Codex CLI\nOpenAI"]
    CLAUDE["Claude Agent SDK\nAnthropic"]
    REPO["Repo · Terminal · Files"]

    UI --> ORC
    ORC --> CODEX
    ORC --> CLAUDE
    CODEX --> REPO
    CLAUDE --> REPO

    style UI     fill:#1e293b,stroke:#475569,color:#e2e8f0
    style ORC    fill:#1e3a5f,stroke:#3b82f6,color:#e2e8f0
    style CODEX  fill:#14532d,stroke:#22c55e,color:#e2e8f0
    style CLAUDE fill:#2e1065,stroke:#a78bfa,color:#e2e8f0
    style REPO   fill:#1c1917,stroke:#57534e,color:#a8a29e

Rule: Harnesses execute. Kōdō orchestrates.

Refine your request before you send it into Ask, Plan, Code, or Review.

Kōdō Code can sharpen your prompt at three levels of enhancement, but this is not a mode itself. It is a preparation layer for clearer intent before orchestration hands work to the harness.

The current default preset in settings is balanced.

Illustrative comparison as of April 15, 2026. This category changes quickly.

Kōdō Code sits between the harnesses and you — not competing with any of them directly.

{
  "promptEnhancePreset": "balanced",
  "defaultThreadEnvMode": "local",
  "commitMessageStyle": "summary",
  "textGenerationModelSelection": {
    "provider": "codex",
    "model": "gpt-5.4-mini",
  },
  "promptEnhanceModelSelection": {
    "provider": "codex",
    "model": "gpt-5.4-mini",
  },
  "askModelSelection": {
    "provider": "codex",
    "model": "gpt-5.4",
  },
  "planModelSelection": {
    "provider": "codex",
    "model": "gpt-5.4",
  },
  "codeModelSelection": {
    "provider": "codex",
    "model": "gpt-5.4",
    "options": {
      "reasoningEffort": "medium",
    },
  },
  "reviewModelSelection": {
    "provider": "claudeAgent",
    "model": "claude-sonnet-4-6",
  },
}

This snippet mirrors the current settings schema and built-in model defaults in the codebase:

• Mode overrides are stored as askModelSelection, planModelSelection, codeModelSelection, and reviewModelSelection.
• Default provider models are gpt-5.4 for Codex and claude-sonnet-4-6 for Claude.
• Git text generation and prompt enhancement currently default to gpt-5.4-mini.
• Other built-in models currently exposed include gpt-5.3-codex, gpt-5.3-codex-spark, claude-opus-4-7, claude-opus-4-6, and claude-haiku-4-5.

One concrete product artifact in Kōdō Code is the persisted plan. A request can move through the product like this:

Prompt
  "Break the session reconnect bug into a safe fix plan, then implement it."

Plan artifact
  1. Reproduce reconnect failure after provider restart
  2. Isolate session state lost during websocket rebind
  3. Patch the server resume path
  4. Verify reconnect and partial-stream behavior

Execution
  Code Mode receives the approved plan as structured context, then edits files and runs commands.

Review
  Review Mode checks regressions, edge cases, and anything the execution pass missed.

That separation is the product boundary: Kōdō handles orchestration and workflow state, while Codex CLI or Claude Agent SDK handle file edits and command execution.

Git Worktrees  —  isolated environments per project

Each project can run in its own git worktree, giving agents a clean, isolated environment without interfering with your working tree. Configure the default per-project: local or worktree.

Configurable Keybindings  —  your shortcuts, your way

Every key action is configurable. Bindings are stored in a dedicated config file and documented in KEYBINDINGS.md.

Remote Access  —  run the server anywhere, connect from anywhere

The Kōdō server supports --host, --port, and --auth-token for remote connections. These are Kōdō server options, separate from the underlying Codex or Claude harness configuration. Run it on a homelab or dev box and connect your desktop client over Tailscale or any network. See REMOTE.md for setup examples.

Observability  —  traces and metrics, not just logs

First-class OTLP support for both traces and metrics. Point it at Grafana Tempo, Prometheus, or any compatible collector. Local NDJSON trace files are written by default. See docs/observability.md for the full setup guide.

timeline
    title Kōdō Code Roadmap
    section [1] Phase 1 — Complete
        Desktop release       : 4-mode workflow
                             : Prompt enhancer
                             : Dual harness support
                             : Model switching per mode
                             : Expanded settings
    section [2] Phase 2 — Next
        VS Code extension    : Shared workflow semantics
                             : Editor-native Plan & Code modes
    section [3] Phase 3 — Planned
        Self-hosting         : Docker & homelab support
                             : Remote server deployment

You'll like Kōdō Code if you:

• Love tools like Cline but want a stronger harness underneath
• Want different models for thinking vs. doing vs. reviewing
• Care about token efficiency and cost-per-task
• Believe prompts deserve to be refined, not just submitted as-is
• Want a desktop experience today, editor integration soon, and self-hosting on the horizon

• Not a new harness — Codex and Claude already do that well
• Not a reimplementation of runtime behavior
• Not a generic chat app with coding bolted on
• Not a terminal emulator pretending to be an IDE

Kōdō Code is a fork of t3code and will continue syncing with upstream regularly.

Huge appreciation to Theo Browne and Julius Marminge for creating a strong foundation for an agentic coding harness. Their work made this project possible. ❤️

Kōdō Code builds on that foundation while making its own changes and improvements in service of a clearer, more intentional workflow.