docs: add CLAUDE.md for AI coding agents

Adds a context file at the repo root to help AI coding agents understand the Electron app (apps/x) structure, build commands, and common development tasks. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
2026-04-25 00:16:29 +02:00 · 2026-01-29 19:48:31 +05:30 · 2026-01-29 19:48:31 +05:30 · 9828ea8301
commit 9828ea8301
parent f5cc803340
1 changed files with 147 additions and 0 deletions
--- a/CLAUDE.md
+++ b/CLAUDE.md
@ -0,0 +1,147 @@
+# CLAUDE.md - AI Coding Agent Context
+
+This file provides context for AI coding agents working on the Rowboat monorepo.
+
+## Quick Reference Commands
+
+```bash
+# Electron App (apps/x)
+cd apps/x && pnpm install          # Install dependencies
+cd apps/x && npm run deps          # Build workspace packages (shared → core → preload)
+cd apps/x && npm run dev           # Development mode (builds deps, runs app)
+cd apps/x && npm run lint          # Lint check
+cd apps/x/apps/main && npm run package   # Production build (.app)
+cd apps/x/apps/main && npm run make      # Create DMG distributable
+```
+
+## Monorepo Structure
+
+```
+rowboat/
+├── apps/
+│   ├── x/                 # Electron desktop app (focus of this doc)
+│   ├── rowboat/           # Next.js web dashboard
+│   ├── rowboatx/          # Next.js frontend
+│   ├── cli/               # CLI tool
+│   ├── python-sdk/        # Python SDK
+│   └── docs/              # Documentation site
+├── CLAUDE.md              # This file
+└── README.md              # User-facing readme
+```
+
+## Electron App Architecture (`apps/x`)
+
+The Electron app is a **nested pnpm workspace** with its own package management.
+
+```
+apps/x/
+├── package.json           # Workspace root, dev scripts
+├── pnpm-workspace.yaml    # Defines workspace packages
+├── pnpm-lock.yaml         # Lockfile
+├── apps/
+│   ├── main/              # Electron main process
+│   │   ├── src/           # Main process source
+│   │   ├── forge.config.cjs   # Electron Forge config
+│   │   └── bundle.mjs     # esbuild bundler
+│   ├── renderer/          # React UI (Vite)
+│   │   ├── src/           # React components
+│   │   └── vite.config.ts
+│   └── preload/           # Electron preload scripts
+│       └── src/
+└── packages/
+    ├── shared/            # @x/shared - Types, utilities, validators
+    └── core/              # @x/core - Business logic, AI, OAuth, MCP
+```
+
+### Build Order (Dependencies)
+
+```
+shared (no deps)
+   ↓
+core (depends on shared)
+   ↓
+preload (depends on shared)
+   ↓
+renderer (depends on shared)
+main (depends on shared, core)
+```
+
+**The `npm run deps` command builds:** shared → core → preload
+
+### Key Entry Points
+
+| Component | Entry | Output |
+|-----------|-------|--------|
+| main | `apps/main/src/main.ts` | `.package/dist/main.cjs` |
+| renderer | `apps/renderer/src/main.tsx` | `apps/renderer/dist/` |
+| preload | `apps/preload/src/preload.ts` | `apps/preload/dist/preload.js` |
+
+## Build System
+
+- **Package manager:** pnpm (required for `workspace:*` protocol)
+- **Main bundler:** esbuild (bundles to single CommonJS file)
+- **Renderer bundler:** Vite
+- **Packaging:** Electron Forge
+- **TypeScript:** ES2022 target
+
+### Why esbuild bundling?
+
+pnpm uses symlinks for workspace packages. Electron Forge's dependency walker can't follow these symlinks. esbuild bundles everything into a single file, eliminating the need for node_modules in the packaged app.
+
+## Key Files Reference
+
+| Purpose | File |
+|---------|------|
+| Electron main entry | `apps/x/apps/main/src/main.ts` |
+| React app entry | `apps/x/apps/renderer/src/main.tsx` |
+| Forge config (packaging) | `apps/x/apps/main/forge.config.cjs` |
+| Main process bundler | `apps/x/apps/main/bundle.mjs` |
+| Vite config | `apps/x/apps/renderer/vite.config.ts` |
+| Shared types | `apps/x/packages/shared/src/` |
+| Core business logic | `apps/x/packages/core/src/` |
+| Workspace config | `apps/x/pnpm-workspace.yaml` |
+| Root scripts | `apps/x/package.json` |
+
+## Common Tasks
+
+### Add a new shared type
+1. Edit `apps/x/packages/shared/src/`
+2. Run `cd apps/x && npm run deps` to rebuild
+
+### Modify main process
+1. Edit `apps/x/apps/main/src/`
+2. Restart dev server (main doesn't hot-reload)
+
+### Modify renderer (React UI)
+1. Edit `apps/x/apps/renderer/src/`
+2. Changes hot-reload automatically in dev mode
+
+### Add a new dependency to main
+1. `cd apps/x/apps/main && pnpm add <package>`
+2. Import in source - esbuild will bundle it
+
+### Verify compilation
+```bash
+cd apps/x && npm run deps && npm run lint
+```
+
+## Tech Stack
+
+| Layer | Technology |
+|-------|------------|
+| Desktop | Electron 39.x |
+| UI | React 19, Vite 7 |
+| Styling | TailwindCSS, Radix UI |
+| State | React hooks |
+| AI | Vercel AI SDK, Anthropic/OpenAI/Google providers |
+| IPC | Electron contextBridge |
+| Build | TypeScript 5.9, esbuild, Electron Forge |
+
+## Environment Variables (for packaging)
+
+For production builds with code signing:
+- `APPLE_ID` - Apple Developer ID
+- `APPLE_PASSWORD` - App-specific password
+- `APPLE_TEAM_ID` - Team ID
+
+Not required for local development.