@hienlh/ppm 0.1.0

package/plans/reports/fullstack-developer-260314-2307-phase-06-git-integration.md

@@ -0,0 +1,33 @@
+# Phase 6: Git Integration — Implementation Report
+
+**Status:** Completed
+**Date:** 2026-03-14
+
+## Files Created
+- `src/services/git.service.ts` — GitService class (status, diff, stage/unstage, commit, push/pull, branches, graph, cherry-pick, revert, tag, PR URL)
+- `src/server/routes/git.ts` — 17 Hono routes (GET + POST) for all git operations
+- `src/web/components/git/git-status-panel.tsx` — Full status panel with stage/unstage/commit/push/pull
+- `src/web/components/git/git-graph.tsx` — Commit graph with lane coloring, branch/tag labels, context menus
+
+## Files Modified
+- `src/server/index.ts` — Added git routes import + mount at `/api/git`
+- `src/web/components/editor/diff-viewer.tsx` — Replaced placeholder with real @codemirror/merge unified diff viewer
+- `src/web/components/layout/tab-content.tsx` — Wired real GitGraph + GitStatusPanel instead of placeholders
+
+## Backend Summary
+- **GitService**: Uses simple-git for all operations. `graphData()` uses `.log({ '--all': null, maxCount })` + raw `--format=%H %P` for parent hashes (per v1 lesson). PR URL parsing supports GitHub + GitLab SSH/HTTPS remotes.
+- **Routes**: 5 GET + 12 POST endpoints. All use `ok()`/`err()` envelope. Project resolved by name via `resolveProjectPath()`.
+
+## Frontend Summary
+- **GitStatusPanel**: Two sections (Staged/Changes), per-file +/- stage/unstage, commit textarea with Cmd+Enter, push/pull buttons. Auto-refresh after actions.
+- **GitGraph**: Scrollable commit list with lane-colored dots, abbreviated hash, subject, author, relative date. Branch labels as colored badges, tag labels in amber. Nested ContextMenus on both commits (checkout, create branch, cherry pick, revert, tag, copy hash, view diff) and branch labels (checkout, merge, push, create PR, delete).
+- **DiffViewer**: Fetches diff from API, parses unified diff into original/modified, renders with `@codemirror/merge` `unifiedMergeView`. Syntax highlighting by file extension.
+
+## Tests Status
+- Type check: PASS (0 errors)
+- Build: PASS (368ms)
+
+## Design Decisions
+- Git graph uses simple list layout (colored dots per lane) instead of SVG — KISS for v1, performant, works well on mobile
+- Diff viewer uses inline unified merge view rather than side-by-side — better mobile experience
+- Branch/tag labels parsed from both `git branch -a` and commit refs field

package/plans/reports/research-260314-1911-ppm-tech-stack.md

@@ -0,0 +1,318 @@
+# Research Report: PPM Tech Stack Selection
+
+**Date:** 2026-03-14
+**Sources consulted:** 15+
+**Key search terms:** mobile-first code editor, web terminal, git graph visualization, Claude Code CLI integration, Go CLI web gateway
+
+---
+
+## Executive Summary
+
+PPM (Personal Project Manager) cần: CLI backend chạy background serving web UI, mobile-first tab system giống VSCode, terminal/editor/git/AI chat trong browser. Sau khi research, recommend stack:
+
+- **Backend:** Go + Cobra CLI + embedded SPA + WebSocket
+- **Frontend:** React (Vite) + Tailwind CSS + shadcn/ui mobile
+- **Editor:** CodeMirror 6 (mobile-first, 300KB vs Monaco 5-10MB)
+- **Terminal:** xterm.js + WebSocket → PTY
+- **Git:** go-git + custom SVG git graph + diff2html
+- **AI Chat:** Claude Agent SDK / Anthropic API streaming via SSE
+- **Tab System:** Custom React tab manager (inspired by VSCode workbench)
+
+---
+
+## Key Findings
+
+### 1. CLI Backend: Go
+
+| Criteria | Go | Node.js | Rust |
+|---|---|---|---|
+| Single binary deploy | Yes | No (runtime needed) | Yes |
+| Build speed | Fast (~2s) | N/A | Slow (~30s+) |
+| Concurrency | Goroutines (lightweight) | Event loop + workers | Async/Tokio |
+| WebSocket support | gorilla/websocket, nhooyr | ws, socket.io | tokio-tungstenite |
+| PTY support | creack/pty | node-pty | portable-pty |
+| Embed static files | embed.FS (built-in) | pkg/nexe (hacky) | rust-embed |
+| Learning curve | Low-medium | Low | High |
+| Dev productivity (solo) | High | High | Medium |
+
+**Recommendation: Go**
+- Single binary = dễ deploy lên VPS, chỉ cần copy binary + config
+- `embed.FS` cho phép nhúng toàn bộ frontend build vào binary
+- Cobra CLI framework cho CLI commands (init, start, config)
+- gorilla/websocket cho terminal + chat streaming
+- creack/pty cho PTY spawning
+
+**Key libraries:**
+- `spf13/cobra` - CLI framework
+- `gorilla/websocket` - WebSocket server
+- `creack/pty` - PTY management
+- `go-git/go-git` - Pure Go git implementation (no git binary needed)
+- `embed` (stdlib) - Embed frontend assets
+
+### 2. Frontend: React + Vite + Tailwind
+
+**Tại sao React thay vì Svelte?**
+
+Gemini recommend Svelte nhưng tôi counter-argue:
+- Ecosystem cho tab system, code editor wrappers, terminal components **lớn hơn nhiều** ở React
+- `@anthropic-ai/claude-agent-sdk-demos` dùng React - dễ reference
+- CodeMirror 6 có `@uiw/react-codemirror` wrapper tốt
+- xterm.js có nhiều React wrappers
+- shadcn/ui + Radix UI cho mobile-first components
+- Solo dev đã quen React → productivity cao hơn
+
+**Bundle size concern:** Vite tree-shaking + code splitting giải quyết. Lazy load tabs (terminal, editor, git graph) = initial load nhỏ.
+
+**Key libraries:**
+- `vite` - Build tool
+- `tailwindcss` + `shadcn/ui` - Mobile-first UI
+- `@tanstack/react-router` - File-based routing (nếu cần)
+- `zustand` - State management (nhẹ, simple)
+- `react-resizable-panels` - Split panes cho tab layout
+
+### 3. Code Editor: CodeMirror 6
+
+| Criteria | CodeMirror 6 | Monaco |
+|---|---|---|
+| Bundle size | ~300KB (core) | 5-10MB |
+| Mobile/touch support | Native, built-in | Not officially supported |
+| Modular | Yes, tree-shakable | Monolithic |
+| Syntax highlighting | 100+ languages via @codemirror/lang-* | Built-in, extensive |
+| Diff view | @codemirror/merge | Built-in, excellent |
+
+**Winner: CodeMirror 6** - mobile-first requirement makes this a no-brainer.
+- Replit switched to CM6, mobile retention tăng 70%
+- Sourcegraph migrated Monaco → CM6 vì performance
+
+**Key packages:**
+- `@uiw/react-codemirror` - React wrapper
+- `@codemirror/lang-*` - Language support
+- `@codemirror/merge` - Diff/merge view
+- `@codemirror/theme-one-dark` - Dark theme
+
+### 4. Web Terminal: xterm.js
+
+Industry standard, powers VSCode terminal. Architecture:
+
+```
+Browser (xterm.js) ←WebSocket→ Go server ←PTY→ bash/zsh
+```
+
+**Key packages:**
+- `@xterm/xterm` - Core terminal emulator
+- `@xterm/addon-fit` - Auto-resize
+- `@xterm/addon-web-links` - Clickable links
+- `@xterm/addon-attach` - WebSocket attachment
+
+Go side: `creack/pty` spawns PTY, `gorilla/websocket` bridges to frontend.
+
+### 5. Git Integration
+
+**Git operations:** `go-git/go-git` (pure Go, no git binary dependency)
+- Clone, log, diff, status, branch - all natively
+- Fallback to `os/exec` + `git` binary for complex ops
+
+**Git graph visualization:**
+- `gitgraph.js` archived → NOT recommended
+- **Custom SVG rendering** using commit data from go-git
+  - Parse commit graph → layout algorithm → SVG/Canvas render
+  - Reference: VSCode Git Graph extension approach
+  - Libraries: `react-flow` hoặc custom SVG with D3 basics
+
+**Git diff viewer:**
+- `diff2html` (2.5k stars) - Parse unified diff → HTML
+- Alternative: `@codemirror/merge` for inline editing + diff
+
+### 6. AI Chat Integration
+
+**Approach 1 (Recommended): Wrap Claude Code CLI**
+```
+Frontend Chat UI ←WebSocket→ Go server ←stdin/stdout→ claude CLI process
+```
+- Spawn `claude` process with PTY (giống terminal nhưng parse output)
+- Giống hệt VSCode extension approach
+- Hỗ trợ tool approvals, streaming, MCP
+- Session = 1 claude process, CRUD = start/stop processes
+
+**Approach 2: Direct API**
+- Anthropic API streaming via SSE
+- Mất hết claude code features (tools, MCP, permissions)
+
+**Approach 3: Claude Agent SDK**
+- TypeScript SDK cho building agents
+- Phức tạp hơn nhưng flexible hơn
+
+**Reference projects:**
+- `siteboon/claudecodeui` - Self-hosted web UI for Claude Code sessions
+- `Jinn` - Gateway daemon extending Claude CLI with web UI
+- Claude Agent SDK demos - React + Express chat app
+
+### 7. Tab System Architecture
+
+```
+┌─────────────────────────────────────────┐
+│ Tab Bar (scrollable on mobile)          │
+│ [Terminal 1] [Chat: main] [editor.ts] X │
+├─────────────────────────────────────────┤
+│                                         │
+│          Active Tab Content              │
+│   (lazy-loaded React component)         │
+│                                         │
+└─────────────────────────────────────────┘
+```
+
+- Each tab = `{ id, type, title, component, metadata }`
+- Types: `terminal`, `chat`, `editor`, `git-graph`, `git-diff`, `settings`
+- State: zustand store with tab CRUD
+- Mobile: swipe gestures, bottom tab bar option
+- Desktop: draggable tabs, split panes
+
+### 8. Deployment & Config
+
+**Config file (`ppm.yaml`):**
+```yaml
+port: 8080
+host: 0.0.0.0
+projects:
+  - path: /home/user/project-a
+    name: Project A
+  - path: /home/user/project-b
+    name: Project B
+auth:
+  enabled: true
+  token: "xxx"  # simple token auth for VPS
+```
+
+**Local onboarding:**
+```bash
+ppm init          # Interactive setup, scan for .git folders
+ppm start         # Start server
+ppm start -d      # Daemon mode (background)
+```
+
+**VPS deployment:**
+```bash
+# Copy binary + config
+scp ppm user@vps:/usr/local/bin/
+scp ppm.yaml user@vps:/etc/ppm/
+ssh user@vps "ppm start -c /etc/ppm/ppm.yaml -d"
+```
+
+**Tailscale:** Just run `ppm start` on local machine, access via Tailscale IP.
+
+---
+
+## Architecture Overview
+
+```
+┌──────────────────────────────────────────────────┐
+│                   PPM Binary (Go)                 │
+│                                                    │
+│  ┌──────────┐  ┌──────────┐  ┌────────────────┐  │
+│  │ Cobra CLI│  │ HTTP/WS  │  │ Embedded SPA   │  │
+│  │ Commands │  │ Server   │  │ (React build)  │  │
+│  └──────────┘  └────┬─────┘  └────────────────┘  │
+│                     │                              │
+│  ┌──────────┐  ┌────┴─────┐  ┌────────────────┐  │
+│  │ PTY Mgr  │  │ WS Hub   │  │ Session Mgr    │  │
+│  │(terminal)│  │(routing) │  │ (AI processes) │  │
+│  └──────────┘  └──────────┘  └────────────────┘  │
+│                                                    │
+│  ┌──────────┐  ┌──────────┐  ┌────────────────┐  │
+│  │ go-git   │  │ Config   │  │ File System    │  │
+│  │ (git ops)│  │ Manager  │  │ Watcher        │  │
+│  └──────────┘  └──────────┘  └────────────────┘  │
+└──────────────────────────────────────────────────┘
+         ↕ WebSocket / HTTP
+┌──────────────────────────────────────────────────┐
+│              React SPA (Browser)                   │
+│                                                    │
+│  ┌──────────┐  ┌──────────┐  ┌────────────────┐  │
+│  │ Tab Mgr  │  │ xterm.js │  │ CodeMirror 6   │  │
+│  │ (zustand)│  │(terminal)│  │ (editor)       │  │
+│  └──────────┘  └──────────┘  └────────────────┘  │
+│                                                    │
+│  ┌──────────┐  ┌──────────┐  ┌────────────────┐  │
+│  │ Chat UI  │  │ Git Graph│  │ File Explorer  │  │
+│  │(streaming│  │ (SVG)    │  │ (tree view)    │  │
+│  └──────────┘  └──────────┘  └────────────────┘  │
+└──────────────────────────────────────────────────┘
+```
+
+---
+
+## Final Tech Stack Summary
+
+| Component | Technology | Why |
+|---|---|---|
+| CLI + Backend | Go + Cobra | Single binary, embed frontend, fast, easy deploy |
+| HTTP Server | Go stdlib `net/http` | No framework needed |
+| WebSocket | gorilla/websocket | Battle-tested, Go standard |
+| PTY | creack/pty | Terminal spawning |
+| Git | go-git | Pure Go, no git binary dep |
+| Frontend | React 19 + Vite | Ecosystem, AI SDK demos, component libs |
+| Styling | Tailwind CSS + shadcn/ui | Mobile-first, accessible |
+| State | zustand | Simple, lightweight |
+| Editor | CodeMirror 6 | Mobile-first, 300KB, modular |
+| Terminal | xterm.js v5 | Industry standard (VSCode uses it) |
+| Git Graph | Custom SVG + D3 basics | No good maintained lib exists |
+| Git Diff | diff2html or CM6 merge | Proven solutions |
+| AI Chat | Claude CLI process via PTY | Full feature parity with VSCode ext |
+| Config | YAML (viper) | Go standard for config |
+| Auth | Simple token (VPS) | KISS for personal tool |
+
+---
+
+## Implementation Recommendations
+
+### Quick Start Order
+1. Go CLI skeleton (Cobra) + config loading
+2. HTTP server + embed empty React app
+3. React tab system + routing
+4. Terminal tab (xterm.js ↔ WebSocket ↔ PTY)
+5. File explorer + CodeMirror editor tab
+6. Git operations (status, log, diff)
+7. Git graph visualization
+8. AI chat integration (claude CLI wrapper)
+9. Onboarding flow (`ppm init`)
+10. VPS deployment mode
+
+### Common Pitfalls
+- Monaco Editor on mobile = broken. Use CodeMirror 6
+- Don't use gitgraph.js (archived since 2023)
+- PTY resize events must sync between xterm.js and server
+- Claude CLI process management: handle crashes, timeouts, cleanup
+- WebSocket reconnection logic essential for mobile (network drops)
+- `go-git` doesn't support all git features — fallback to `git` binary
+
+---
+
+## References
+
+- [CodeMirror 6 vs Monaco comparison](https://agenthicks.com/research/codemirror-vs-monaco-editor-comparison)
+- [Sourcegraph Monaco → CM6 migration](https://sourcegraph.com/blog/migrating-monaco-codemirror)
+- [Replit code editor comparison](https://blog.replit.com/code-editors)
+- [xterm.js](https://xtermjs.org/)
+- [go-git](https://github.com/go-git/go-git)
+- [Cobra CLI](https://github.com/spf13/cobra)
+- [creack/pty](https://github.com/creack/pty)
+- [gorilla/websocket](https://github.com/gorilla/websocket)
+- [diff2html](https://github.com/rtfpessoa/diff2html)
+- [Claude Agent SDK demos](https://github.com/anthropics/claude-agent-sdk-demos)
+- [claudecodeui](https://github.com/siteboon/claudecodeui)
+- [shadcn/ui](https://ui.shadcn.com/)
+
+---
+
+## User Decisions (2026-03-14)
+
+1. **Claude Code integration:** Reference projects: [vibe-kanban](https://github.com/BloopAI/vibe-kanban), [claude-code-chat](https://github.com/andrepimenta/claude-code-chat), [Claude Agent SDK](https://platform.claude.com/docs/en/agent-sdk/overview)
+2. **Git scope:** Basic only (status, log, diff, graph). No advanced features (rebase, submodules)
+3. **Auth:** Simple token OK. Design for extensibility (pluggable auth later)
+4. **Editor:** CodeMirror 6 confirmed — works well on mobile
+5. **PWA:** Yes, will implement PWA (offline caching, add to homescreen)
+
+## Remaining Questions
+
+1. **Claude CLI output parsing:** Exact JSON output format? Need to study vibe-kanban and claude-code-chat implementations
+2. **Agent SDK vs CLI wrapping:** Which approach fits better? SDK = more control, CLI = full feature parity

package/plans/reports/research-260314-1930-claude-code-integration.md

@@ -0,0 +1,293 @@
+# Research Report: Claude Code CLI Integration Patterns
+
+**Date:** 2026-03-14
+**Sources:** 3 primary (vibe-kanban, claude-code-chat, Agent SDK docs) + 2 supplementary (sessions, user-input docs)
+
+---
+
+## Executive Summary
+
+3 approaches exist for integrating Claude Code into a custom UI. After analyzing all sources, **Claude Agent SDK (TypeScript)** is the clear winner for PPM — it provides programmatic session management, streaming, tool approvals, and is the officially supported path. claude-code-chat validates the CLI subprocess approach works but Agent SDK is superior in every way.
+
+---
+
+## Source Analysis
+
+### 1. BloopAI/vibe-kanban
+
+**Architecture:** Rust backend + React frontend. Full IDE-like tool for managing coding agents.
+- Supports Claude Code, Codex, Gemini CLI, GitHub Copilot, Amp, etc.
+- Runs agents in isolated workspaces (git worktrees) with terminal + dev server per workspace
+- Backend: Rust (49.4%), Frontend: TypeScript/React (46.7%)
+- Requires PostgreSQL
+
+**Integration approach:** Agent-agnostic — treats all AI tools as terminal processes in workspaces. Does NOT deeply integrate with Claude Code internals, just provides terminal environments.
+
+**Key takeaway for PPM:** Overkill for our needs. Uses Rust + PostgreSQL which adds complexity. But the "workspace = branch + terminal + dev server" concept is interesting.
+
+### 2. andrepimenta/claude-code-chat
+
+**Architecture:** VSCode extension wrapping Claude Code CLI as subprocess.
+
+**Integration method: CLI Subprocess via stdin/stdout**
+- Spawns `claude` CLI process
+- Captures streaming stdout for real-time response display
+- Sends user messages via stdin
+- WSL path support for CLI binary (`/usr/local/bin/claude`)
+
+**Session management:**
+- Automatic conversation saving/restoration (file-based)
+- Resume conversations where left off
+- Workspace-scoped sessions
+
+**Tool approvals — sophisticated permission system:**
+- Interactive dialog showing tool info + command previews
+- Smart pattern matching (npm, git, docker auto-approved)
+- "Always Allow" functionality
+- "YOLO Mode" — skip all permission checks
+- Workspace-level granular permissions
+
+**Streaming:** Real-time streaming responses with typing indicators, parsing CLI stdout.
+
+**Key takeaway for PPM:** Validates CLI wrapping works well for chat UI. But this is VSCode-specific. For a web app, Agent SDK is better since it gives programmatic control without parsing CLI output.
+
+### 3. Claude Agent SDK (Official) — **RECOMMENDED**
+
+**Architecture:** Library that gives same capabilities as Claude Code CLI, programmable in TypeScript and Python.
+
+**Package:** `@anthropic-ai/claude-agent-sdk` (TypeScript) / `claude-agent-sdk` (Python)
+
+**Core API — `query()` function:**
+```typescript
+import { query } from "@anthropic-ai/claude-agent-sdk";
+
+for await (const message of query({
+  prompt: "Find and fix the bug in auth.py",
+  options: { allowedTools: ["Read", "Edit", "Bash"] }
+})) {
+  console.log(message);
+}
+```
+
+**Built-in tools (same as Claude Code CLI):**
+| Tool | What it does |
+|------|-------------|
+| Read | Read files |
+| Write | Create files |
+| Edit | Precise edits |
+| Bash | Terminal commands |
+| Glob | Find files by pattern |
+| Grep | Search file contents |
+| WebSearch | Search web |
+| WebFetch | Fetch web pages |
+| AskUserQuestion | Ask user clarifying questions |
+| Agent | Spawn subagents |
+
+**Session Management — EXCELLENT:**
+```typescript
+// Create session — capture ID from init message
+let sessionId: string;
+for await (const message of query({
+  prompt: "Analyze auth module",
+  options: { allowedTools: ["Read", "Glob"] }
+})) {
+  if (message.type === "system" && message.subtype === "init") {
+    sessionId = message.session_id;
+  }
+}
+
+// Resume session with full context
+for await (const message of query({
+  prompt: "Now find all places that call it",
+  options: { resume: sessionId }
+})) {
+  // Has full context from first query
+}
+
+// Fork session to explore alternative
+for await (const message of query({
+  prompt: "Try OAuth2 instead",
+  options: { resume: sessionId, forkSession: true }
+})) {
+  // New session branched from original
+}
+
+// Continue most recent session (no ID needed)
+for await (const message of query({
+  prompt: "Continue with previous task",
+  options: { continue: true }
+})) {}
+
+// List all sessions
+import { listSessions, getSessionMessages } from "@anthropic-ai/claude-agent-sdk";
+const sessions = await listSessions();
+const messages = await getSessionMessages(sessionId);
+```
+
+**Session storage:** `~/.claude/projects/<encoded-cwd>/<session-id>.jsonl`
+
+**Tool Approvals — Full Control:**
+```typescript
+for await (const message of query({
+  prompt: "Refactor this code",
+  options: {
+    canUseTool: async (toolName, input) => {
+      if (toolName === "AskUserQuestion") {
+        // Handle clarifying questions from Claude
+        return handleQuestions(input);
+      }
+      // Show approval UI to user
+      const approved = await showApprovalDialog(toolName, input);
+      if (approved) {
+        return { behavior: "allow", updatedInput: input };
+      }
+      return { behavior: "deny", message: "User declined" };
+    }
+  }
+})) {}
+```
+
+**Permission modes:** `allowedTools` pre-approves safe tools, `canUseTool` callback for interactive approval.
+
+**Streaming:** Native async iterator — each `message` yields as it arrives. Message types:
+- `system` (init with session_id)
+- `assistant` (text blocks, tool calls)
+- `tool` (tool results)
+- `result` (final result with cost info)
+
+**Hooks:** PreToolUse, PostToolUse, Stop, SessionStart, SessionEnd — same as Claude Code CLI.
+
+**MCP Support:** Connect external MCP servers:
+```typescript
+options: {
+  mcpServers: {
+    playwright: { command: "npx", args: ["@playwright/mcp@latest"] }
+  }
+}
+```
+
+**Subagents:** Spawn specialized agents from main agent.
+
+**Claude Code features supported:** Skills, slash commands, CLAUDE.md memory, plugins.
+
+---
+
+## Comparative Analysis
+
+| Feature | CLI Subprocess | Agent SDK |
+|---|---|---|
+| Setup complexity | Low (just spawn process) | Low (npm install) |
+| Streaming | Parse stdout (fragile) | Native async iterator (robust) |
+| Session CRUD | Parse filesystem | `listSessions()`, `getSessionMessages()`, `resume`, `fork` |
+| Tool approvals | Parse CLI prompts (very fragile) | `canUseTool` callback (clean API) |
+| Multi-session | Multiple processes (heavy) | Multiple `query()` calls (lightweight) |
+| Error handling | Process exit codes | Structured error messages |
+| MCP support | Via CLI config | Programmatic |
+| Hooks | Via CLI config files | Programmatic callbacks |
+| Authentication | CLI handles it | API key in env var |
+| Maintenance | Breaks on CLI output format changes | Stable SDK contract |
+
+**Winner: Agent SDK** — vastly superior for building a web app.
+
+---
+
+## Implementation Architecture for PPM
+
+```
+┌─────────────────────────────────────────────┐
+│            React Frontend (Browser)          │
+│                                              │
+│  Chat Tab ←→ WebSocket ←→ Go Backend        │
+│  - Message list (streaming)                  │
+│  - Tool approval dialogs                     │
+│  - AskUserQuestion UI                        │
+│  - Session picker (list/resume/fork)         │
+└─────────────────────────────────────────────┘
+         ↕ WebSocket (bidirectional)
+┌─────────────────────────────────────────────┐
+│              Go Backend Server               │
+│                                              │
+│  Session Manager                             │
+│  ├─ Map<sessionId, AgentSDKProcess>          │
+│  ├─ Create: spawn node process with SDK      │
+│  ├─ Resume: pass sessionId to SDK            │
+│  ├─ Fork: pass sessionId + forkSession       │
+│  ├─ List: call listSessions()                │
+│  └─ Delete: remove session file              │
+│                                              │
+│  Agent SDK Bridge (Node.js sidecar)          │
+│  ├─ Runs @anthropic-ai/claude-agent-sdk      │
+│  ├─ Communicates with Go via stdio/WebSocket │
+│  ├─ Handles query() streaming                │
+│  └─ Forwards canUseTool to frontend          │
+└─────────────────────────────────────────────┘
+```
+
+**Key architectural decision:** Since Agent SDK is TypeScript/Python, the Go backend needs a Node.js sidecar process to run the SDK. Communication: Go ↔ Node.js via stdio (JSON lines) or local WebSocket.
+
+**Alternative:** Write backend in Node.js instead of Go to avoid sidecar. Trade-off: lose single binary deployment but gain simpler architecture.
+
+---
+
+## Recommended Approach
+
+### Option A: Go + Node.js Sidecar (Recommended if keeping Go)
+- Go handles HTTP/WS server, file ops, git ops, terminal PTY
+- Node.js sidecar runs Agent SDK, communicates via JSON-over-stdio
+- Go spawns/manages sidecar processes (one per active session)
+
+### Option B: Full Node.js Backend (Simpler)
+- Single runtime for everything
+- Agent SDK runs directly in backend
+- Use `pkg` or `bun compile` for single binary
+- Lose Go's PTY management elegance, but `node-pty` works fine
+
+### Option C: Hybrid — Go binary embeds Node.js runtime
+- Complex but achievable with embedded V8 or Bun
+- Not recommended for solo dev
+
+**Recommendation:** Start with **Option A** (Go + sidecar). The Go binary handles everything except AI chat. The sidecar is only spawned when user opens a chat tab. If sidecar management becomes painful, migrate to Option B later.
+
+---
+
+## Key Code Patterns for PPM
+
+### 1. Session List API
+```typescript
+// Node.js sidecar endpoint
+import { listSessions } from "@anthropic-ai/claude-agent-sdk";
+const sessions = await listSessions(); // Returns session metadata
+```
+
+### 2. Streaming Chat via WebSocket
+```typescript
+// Sidecar: stream messages to Go backend
+for await (const message of query({ prompt, options: { resume: sessionId } })) {
+  process.stdout.write(JSON.stringify(message) + '\n'); // JSON lines to Go
+}
+```
+
+### 3. Tool Approval Flow
+```
+User sends prompt → Go → Sidecar starts query()
+Claude wants to use Bash → canUseTool fires
+Sidecar → Go → WebSocket → Frontend shows approval dialog
+User clicks Allow → Frontend → WebSocket → Go → Sidecar returns allow
+Claude executes tool → continues
+```
+
+### 4. Multi-tab Chat
+- Each chat tab = one session ID
+- Frontend tracks `Map<tabId, sessionId>`
+- Opening new chat tab = new `query()` call, captures new sessionId
+- Switching tabs = just UI state, sessions persist on disk
+- Resuming tab = `query({ options: { resume: savedSessionId } })`
+
+---
+
+## Remaining Questions
+
+1. **Agent SDK + Go sidecar performance:** Spawning Node.js per session = memory overhead. Need to benchmark. Could pool sidecar processes.
+2. **Agent SDK auth on VPS:** API key needed. How to securely store/inject on VPS deployment?
+3. **V2 TypeScript SDK:** Preview available with `createSession()` pattern — more natural for multi-session. Worth tracking but unstable.
+4. **Offline/PWA:** Agent SDK requires network. PWA caching useful for UI shell only, chat always needs connectivity.