The orchestration layer between you and your AI harnesses —
so Codex CLI and Claude Agent SDK work the way you think, not the other way around.
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.
| Level | What it does |
|---|---|
| Minimal | Fixes grammar, typos, and clarity. Your words, cleaned up. |
| Balanced | Expands your intent into a well-scoped, structured prompt. |
| Vibe | Full rewrite. Every ounce of the vibe, maximally expressed. |
The current default preset in settings is balanced.
Illustrative comparison as of April 15, 2026. This category changes quickly.
| Kōdō Code | Cline | Roo Code | Claude Code | Codex CLI | |
|---|---|---|---|---|---|
| Harness | Codex + Claude Agent SDK | API-based | API-based | Native Claude | Native OpenAI |
| Workflow Modes | ✓ 4 | ✗ | ✓ | ✗ | ✗ |
| Prompt Enhancer | ✓ 3 levels | ✓ | ✓ | ✗ | ✗ |
| Auto model switch | ✓ per mode | ✗ | ✓ per-task | ✗ | ✗ |
| Dual harness | ✓ | ✗ | ✗ | -- | -- |
| Desktop UI | ✓ | ✓ VS Code | ✓ VS Code | ✗ | ✗ |
| VS Code extension | ◐ Phase 2 | ✓ | ✓ | ✗ | ✗ |
| Self-hostable | ◐ Phase 3 | ✗ | ✗ | ✗ | ✗ |
| Commit model policy | ✓ separate | ✓ basic | ✗ | ✗ | ✓ basic |
| Settings surface | ✓ first-class | ✓ | ✓ | Flags | Flags |
| Philosophy | Orchestrator | Editor-first | Feature-rich | Raw harness | Raw harness |
Kōdō Code sits between the harnesses and you — not competing with any of them directly.
This snippet mirrors the current settings schema and built-in model defaults in the codebase:
- Mode overrides are stored as
askModelSelection,planModelSelection,codeModelSelection, andreviewModelSelection. - Default provider models are
gpt-5.4for Codex andclaude-sonnet-4-6for 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, andclaude-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.
Keep the best harnesses. Keep the best workflow base. Build only the missing layer.
Kōdō Code exists so you can code the way kōdō practitioners approach incense:
Report a Bug · Request a Feature
{ "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", }, }