# Claude Flow

A document-centric coding assistant that enforces a structured workflow: **Research → Plan → Implement**.

Built with Electron, React, TypeScript, better-sqlite3, and the Claude Agent SDK.

## Concept

The primary UI is a **markdown document viewer/editor** with a **chat sidebar**. The workflow is driven by the document, not the chat.

### Workflow Phases

1. **Research** — Claude researches your codebase based on your direction, writing findings to `.claude-flow/research.md`
2. **Plan** — Claude creates a detailed implementation plan in `.claude-flow/plan.md` with code snippets and a TODO checklist
3. **Implement** — Claude executes the plan, marking tasks complete as it goes

At each phase, you can edit the document to add notes (marked with `// REVIEW:` or `// NOTE:`), click **Review** to have Claude address your feedback, then **Submit** to advance to the next phase.

## UI Layout

```
┌──────────────────────────────────────────────────────────────┐
│ [Project ▾]  [Session ▾]              [Research ● ─ Plan ─]  │
├────────────────────────────────────────┬─────────────────────┤
│                                        │                     │
│   # Research Findings                  │   Chat Dialogue     │
│                                        │                     │
│   ## Authentication System             │   Claude: What      │
│                                        │   should I research?│
│   The auth module uses JWT...          │                     │
│                                        │   You: Research the │
│   // REVIEW: check OAuth too           │   auth system       │
│                                        │                     │
├────────────────────────────────────────┼─────────────────────┤
│  42k / 200k tokens ████░░░░            │         [Send]      │
│                     [Review]  [Submit] │                     │
└────────────────────────────────────────┴─────────────────────┘
```

## Requirements

- Node.js ≥ 18
- macOS (Apple Silicon or Intel), Windows, or Linux
- Claude API key or Claude Code subscription

## Install

```bash
git clone <this-repo>
cd claude-flow
npm install
```

## Development

```bash
npm run dev
```

This starts Vite dev server and Electron in watch mode.

## Build

```bash
npm run dist
```

Creates distributable builds via electron-builder.

## Project Structure

```
claude-flow/
├── src/main/           # Electron main process
│   ├── index.ts        # App lifecycle, window management
│   ├── preload.ts      # IPC bridge with typed API
│   ├── db/             # SQLite database (projects, sessions, messages)
│   ├── claude/         # Claude SDK wrapper with phase configs
│   └── ipc/            # IPC handlers
├── renderer/           # React frontend
│   ├── src/
│   │   ├── App.tsx           # Main app with state management
│   │   ├── components/       # Header, DocumentPane, ChatPane, ActionBar
│   │   ├── styles/           # CSS
│   │   └── types.ts          # TypeScript types
│   └── index.html
├── package.json
├── tsconfig.json
└── vite.config.ts
```

## Keyboard Shortcuts

- **Cmd/Ctrl + Enter** — Submit (advance to next phase)
- **Escape** — Interrupt Claude

## References

- [BLOG_POST_TITLE](BLOG_POST_URL) — Blog post that inspired this workflow

## License

MIT