koan

Koan runs opinionated multi-turn workflows for LLM-assisted engineering. A local Python process hosts a web dashboard and an MCP endpoint; subagents are invocations of the vendor CLIs (claude, codex, or gemini) that connect back over HTTP MCP and advance through a fixed sequence of phases under user direction. Decisions are written to markdown artifacts during the run, and a per-project memory is carried across runs.

Koan invokes the vendor CLIs as subprocesses and uses whatever authentication they already have on your machine. It does not call provider APIs directly, does not touch OAuth credentials, and does not proxy traffic, so it runs under your existing CLI subscription and within each CLI's terms of service.

Koan is alpha. Interfaces, phase names, state files, and the memory schema will change without migration.

The Problem

Long-lived LLM-assisted projects accumulate what I call knowledge debt. The developer no longer knows what is in the code, and the LLM never knew to begin with. Utilities get reimplemented, conventions diverge, and architecture drifts.

LLMs are good at retrieval, synthesis, and presentation. They are bad at reasoning under uncertainty and at noticing drift. Larger context windows do not help -- attention is finite and uneven regardless of window size. What helps is giving the model a narrower slice of the right information at each step, and writing the decisions down so the next run does not re-derive them.