From 9a636af9090b122db2e55737fca3e78550aab9df Mon Sep 17 00:00:00 2001
From: bndw <ben@bdw.to>
Date: Sat, 28 Feb 2026 19:14:01 -0800
Subject: fix: scope artifacts to sessions

---
 CLAUDE.md | 53 +++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 53 insertions(+)
 create mode 100644 CLAUDE.md

(limited to 'CLAUDE.md')

diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..e54032e
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,53 @@
+# 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.
+
+## 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
-- 
cgit v1.2.3