# Claude Flow — Codebase Overview

## What This Is

An Electron desktop app that enforces a **Research → Plan → Implement** workflow for AI-assisted coding, using `@anthropic-ai/claude-agent-sdk`.

## Tech Stack

- **Electron 38** + **Vite** + **React 19** + **TypeScript**
- **better-sqlite3** — local persistence (projects, sessions, messages)
- **@anthropic-ai/claude-agent-sdk** — Claude integration
- **CodeMirror 6** — markdown editor in DocumentPane
- **react-markdown + remark-gfm** — markdown renderer

## Project Structure

```
src/main/          # Electron main process
  claude/          # SDK integration + phase configs
  db/              # SQLite layer (schema, projects, sessions)
  ipc/             # IPC channel registrations
  index.ts         # App entry, BrowserWindow
  preload.ts       # contextBridge API surface
renderer/src/      # React UI
  App.tsx          # Root — all state management
  components/      # Header, DocumentPane, ChatPane, ActionBar
  types.ts         # Shared TypeScript types
  styles/          # CSS variables (dark/light themes)
```

## Key Patterns

### Phase System
Phases: `research | plan | implement`. Each defined in `src/main/claude/phases.ts` with its own `systemPrompt`, `tools[]`, `permissionMode`, and `initialMessage`. Phase progression is one-way; triggered by user clicking "Submit".

### Artifact Storage
Session artifacts (`research.md`, `plan.md`) stored inside the target project at `.claude-flow/sessions/{sessionId}/`. This keeps them within the SDK's allowed write boundary (project `cwd`). Add `.claude-flow/` to `.gitignore` to exclude from version control.

### Session Continuity
Claude SDK session IDs are captured from the `system:init` message and stored in SQLite. Subsequent turns resume the same SDK session (`options: { resume: claude_session_id }`).

### IPC Pattern
All renderer→main communication goes through named IPC channels registered in `src/main/ipc/handlers.ts`. Streaming events flow back via `mainWindow.webContents.send("claude:message", sessionId, msg)` and are received via `ipcRenderer.on()`.

### Database
SQLite at `app.getPath("userData")/claude-flow.db`. Tables: `projects`, `sessions`, `messages`. Foreign keys ON, WAL mode enabled.

Schema migrations: `db/index.ts::getDb()` calls `initSchema()` which uses `CREATE TABLE IF NOT EXISTS`. **New columns require explicit `ALTER TABLE` migration** run after `initSchema()`.

### SDK Permission Modes
`PermissionMode` values: `'default' | 'acceptEdits' | 'bypassPermissions' | 'plan' | 'dontAsk'`

**Known bug**: `permissionMode: 'bypassPermissions'` requires a companion flag `allowDangerouslySkipPermissions: true` in the `query()` options. This flag is currently missing from `claude/index.ts`.

`allowedTools: string[]` in the SDK maps to Claude Code's `--allowedTools` CLI flag and supports patterns like `'Bash(git *)'` to auto-allow only specific Bash command forms.

## Important Notes

- `ANTHROPIC_API_KEY` env var must be set before launching
- Artifacts are stored in `.claude-flow/sessions/` inside the target project
- `bypassPermissions` mode is a user-controlled toggle in implement phase only
- Token usage (from `SDKResultMessage.usage`) is displayed in the ActionBar
- No git library in dependencies — use Node.js `child_process` (built-in) for git operations