1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
|
# 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
|
