# Doan

**Code shouldn't be your first draft.**

Doan is a planning canvas for Claude Code and Codex. You think out loud in the browser; the coding session you already have open turns it into screens, flows, data and the questions you skipped. When nothing is left undecided, the plan goes back to that same session as a spec, and it starts building.

[한국어](README.ko.md)

![A plan on the Doan canvas: two flows of wireframed screens, a notification and a background job, the open questions on the right, and Claude's critiques in the chat](docs/canvas.png)

- **Your session, your subscription.** Doan runs on your machine and attaches to Claude Code as a [channel](https://code.claude.com/docs/en/channels), or to Codex as an MCP server. No API keys, no account with us, and no one else's login in between.
- **It asks before it guesses.** Every hole in the idea becomes a question on the canvas: *structural* ones (who approves? can one date go to several people?) block the handoff until you answer, defer or drop them.
- **Colors mean something.** Graphite is what you decided. Blue pencil is Claude's: new or proposed. Red is still open.
- **The plan stays in your repo**, in `.doan/`, next to the code it becomes.

## Requirements

- One coding agent:
  - [Claude Code](https://code.claude.com) 2.1.80 or later, signed in with a claude.ai account (Channels, research preview). Doan starts it with a development-channel flag, because custom channels aren't on the preview allowlist.
  - or [Codex CLI](https://github.com/openai/codex), signed in.
- [Bun](https://bun.sh) 1.3 or later, and git.
- macOS or Linux. On Windows, use WSL.

## Install

```bash
curl -fsSL https://getdoan.com/install.sh | bash
```

It clones Doan into `~/.doan`, links `doan` into `~/.local/bin`, and tells you which agents it found ([read it first](install.sh)). By hand:

```bash
git clone https://github.com/Streamize-llc/doan ~/.doan
cd ~/.doan && bun install
ln -s ~/.doan/bin/doan ~/.local/bin/doan    # any folder on your PATH
```

Run the installer again to update.

## Use

In the project you're planning:

```bash
cd ~/code/my-app
doan                        # with Claude Code; other claude flags pass through: doan --model opus
doan codex                  # with Codex; codex flags pass through: doan codex -m gpt-5
```

Nothing is added to your Claude Code or Codex settings: `doan` passes the MCP server for this session only.

1. Claude Code warns about the development channel. Choose **I am using this for local development**. (The startup line `server:doan · no MCP server configured with that name` is cosmetic; events arrive.)
2. The canvas opens at `http://localhost:7420`. A tab left open from last time reconnects on its own.
3. Write on the left, the way you'd explain it to a friend. When you pause, it's sent (untick **Send when I pause** to send by hand).
4. Claude answers in two steps: first the **structure** (screens, elements, actions), then **critiques and questions**.
5. Answer the open questions on the right (option chips answer in one click), and accept or dismiss proposals (dashed blue) and critiques.
6. When nothing structural is open, **Send to Claude Code**: the spec is written to `.doan/specs/<id>.md`, and the same session reports an implementation plan in the terminal and waits for your go.

**With Codex**, the same canvas and the same steps, with one difference: an MCP server can't push into a Codex session, so Codex *waits on the canvas* with a `doan_wait` tool and goes back to waiting after each change. While it waits, you plan in the browser, not in the terminal. If you interrupt it, the canvas says Codex isn't listening; tell it to continue. Doan's tools are approved up front for that session, so drawing doesn't ask for permission each time. After the handoff Codex stops waiting and shows its implementation plan in the terminal, like Claude.

Planning turns want speed more than depth, so `doan` starts Claude Code with `--effort medium` (about 18 s to the first structure, 33 s to questions and critiques; `xhigh` takes 80 s or more). Raise it with `/effort high` before building from the spec, or start with `doan --effort high`.

### What Claude can draw

- **Screens**: full screens, modals, sheets and toasts (with the screen they sit on), named states ("Empty", "Pending approval"), screens only some roles see.
- **Elements**: header, text, button, input, list, card, image, grid, tabs, toggle, sheet, nav, divider, chat, picker, media, chart, map, progress, avatar, and one level of `section` / `row` grouping. Elements can be bound to data (`T1.date`).
- **Systems**: what happens off-screen: AI, background jobs, notifications, payments, third-party services.
- **Data**: fields, relations, retention, and whether it's sensitive (the **Data** tab).
- **Actions**: moves between screens and systems, conditional branches, role limits.
- **Flows** group screens once there are many; **scope** marks what ships first and what waits.

Canvas: drag to move, scroll to pan, `⌘`/`Ctrl` + scroll (or pinch) to zoom, `F` to fit, double-click a screen name to rename it.

### Where plans live

```
<project>/.doan/plans/<id>.json   # the canvas
<project>/.doan/specs/<id>.md     # the spec written at handoff
```

### Try it without Claude

```bash
bun run demo    # draws a sample plan (shift swaps for nurses) with a scripted stand-in
```

### Settings

| Variable | Default | |
|---|---|---|
| `DOAN_PORT` | 7420 | Canvas port (the next free one if taken) |
| `DOAN_OPEN` | 1 | `0` doesn't open a browser |
| `DOAN_BROWSER` | system default | App to open the canvas in, e.g. `DOAN_BROWSER="Google Chrome"` |
| `DOAN_LANG` | your shell locale | `en` or `ko` for the canvas and the spec. Claude always writes in the language you write in. |
| `DOAN_EFFORT` | medium | Claude Code effort (an explicit `--effort` wins) |
| `DOAN_DEBUG` | 0 | `1` logs every change the agent sends to `.doan/debug.log` |
| `DOAN_WAIT_SEC` | 1500 | Codex: how long one `doan_wait` waits before returning empty |

## Doan Team

Planning alone is free and stays free. **Doan Team** ([getdoan.com](https://getdoan.com/teams)) is our hosted service for teams who want to see each other's plans: every plan from a linked project syncs to your team, teammates open it in the browser (read only), and their comments land in the planner's chat as they're written and reach Claude on the next turn. Free for up to 3 members; larger teams subscribe.

![A teammate's comment on a screen in the Doan Team viewer](docs/team-viewer.png)

```bash
doan team join <team-url> <token>   # the whole command is on the invite page; run it in the project folder
```

Teammates who don't plan can still bring the team's plans into their own agent: Doan Team is a remote MCP server at `https://getdoan.com/mcp` (sign in once in the browser), for Claude Code, Codex, Cursor or claude.ai.

The team service never calls Claude and never sees anyone's Claude login: every member plans with Claude Code on their own subscription, and only the plan (without the chat) is shared. This repository contains the client side (`packages/team`); the team server itself isn't open source and isn't offered for self-hosting.

## License

[MIT](LICENSE). See [CONTRIBUTING.md](CONTRIBUTING.md) to help.

Doan is not affiliated with or endorsed by Anthropic. Claude and Claude Code are trademarks of Anthropic.