[日本語版](../architecture.md)

# CommandMate Architecture

> Architecture design document for a development companion tool that opens Claude Code / tmux sessions per git worktree and allows chat operations from a smartphone browser.

This document defines the technical architecture of **CommandMate**.

- What processes/components make up the system
- How Claude CLI / tmux / Web UI cooperate
- Which responsibilities belong to which layer

It serves as a guide during implementation.

---

## 0. Scope & Notation

- Scope: The entire `CommandMate` application
  - Next.js (App Router) based Web UI
  - Node.js API / WebSocket server
  - tmux + Claude CLI session management
  - SQLite / local FS persistence
- Out of scope:
  - Claude model behavior
  - Specific integration implementations with other tools (mySwiftAgent / myAgentDesk, etc.)

Naming / Terminology:

- **worktree**: A branch directory managed as a git worktree
- **worktreeId**: A URL-safe identifier (e.g., `feature-foo`)
- **tmux session**: A tmux session named `cw_{worktreeId}`
- **Stop hook**: A completion hook set via Claude CLI's `CLAUDE_HOOKS_STOP`

---

## 1. System Goals

### 1.1 Goals

- Manage **independent Claude CLI sessions** per git worktree
- Provide a **per-branch chat UI** accessible from smartphone or PC browsers
- Use Stop hooks for **event-driven updates** without polling for the latest responses
- Safely store conversation history / detailed logs locally

### 1.2 Non-goals

- Operating as a multi-user SaaS (this is for local developers)
- Public exposure across security boundaries / multi-tenant operation

### 1.3 Implemented Features

- **CLI Tool Support** (Implemented in Issue #4, extended in Issue #368/#379/#545)
  - Supports 7 tools: Claude Code, Codex CLI, Gemini CLI, Vibe-Local (Ollama), OpenCode, GitHub Copilot, Antigravity (the authority is `CLI_TOOL_IDS` in `src/lib/cli-tools/types.ts`)
  - Extensible design via Strategy pattern
  - Select 2-4 agents per worktree (`selected_agents` column)
  - Vibe-Local supports Ollama model selection (`vibe_local_model` column)

---

## 2. Context & Assumptions

### 2.1 Prerequisites

- Runs on the developer's local machine
  - macOS / Linux assumed (tmux / Claude CLI must be available)
- Claude CLI is installed and:
  - Can be launched with the `claude` command
  - Supports setting `CLAUDE_HOOKS_STOP`
- Multiple branch directories are managed via git worktree

### 2.2 Execution Modes

- **Local mode (default)**
  - `MCBD_BIND = 127.0.0.1`
  - Connections from the same machine only
- **LAN access mode (optional)**
  - `CM_BIND = 0.0.0.0`
  - Reverse proxy authentication recommended (details: `docs/security-guide.md`)
  - Accessible from smartphones on the same network

---

## 3. High-level Architecture

### 3.1 Component Diagram

```mermaid
graph TD
    subgraph Browser["Smartphone/PC Browser"]
        UI_A[Screen A: Worktree List]
        UI_B[Screen B: Chat Screen]
        UI_C[Screen C: Log Viewer]
        UI_WS[WebSocket Client]
    end

    subgraph Next["Next.js / Node.js Application"]
        App["Next.js UI (App Router)"]
        API_Send[/POST /api/worktrees/:id/send/]
        API_WT[/GET /api/worktrees/ .../]
        API_Hook[/POST /api/hooks/claude-done/]
        API_Logs[/GET /api/worktrees/:id/logs/ .../]
        WS_Server[WebSocket Server]
        DB[(SQLite db.sqlite)]
    end

    subgraph TmuxClaude["tmux / Claude CLI"]
        T[(tmux server)]
        S1[tmux session: cw_main]
        S2[tmux session: cw_feature-foo]
        CL1[Claude CLI Process]
    end

    subgraph FS["Local Filesystem"]
        Logs[".claude_logs/ (Markdown logs)"]
    end

    UI_A --> App
    UI_B --> App
    UI_C --> App
    UI_WS <---> WS_Server

    App --> API_WT
    App --> API_Send
    App --> API_Logs

    API_Send --> T
    API_Hook --> T

    API_WT --> DB
    API_Logs --> Logs
    API_Hook --> DB
    API_Hook --> Logs
    API_Hook --> WS_Server

    CL1 -->|"Stop hook"| API_Hook
```

### 3.2 Processes & Ports

- **Next.js / Node.js process**
  - Port: MCBD_PORT (e.g., 3000)
  - Bind: MCBD_BIND (127.0.0.1 or 0.0.0.0)
  - Features:
    - HTTP server (UI, API Routes)
    - WebSocket server
    - SQLite connection
- **tmux server**
  - Uses the existing tmux server on the system
  - Launches CLI tools in sessions named `cw_{worktreeId}`
- **CLI tool process (Claude Code / Codex CLI)**
  - The selected CLI tool runs within each tmux session
  - Sends completion notifications via the command set in `CLAUDE_HOOKS_STOP` (for Claude Code)

---

## 4. Data Model

### 4.1 Worktree

```typescript
interface Worktree {
  id: string;              // URL-safe ID ("main", "feature-foo", etc.)
  name: string;            // Display name ("main", "feature/foo", etc.)
  path: string;            // Absolute path "/path/to/root/feature/foo"
  lastMessageSummary?: string; // Summary of the last message
  updatedAt?: Date;        // Timestamp of last message
}
```

- **id**: Identifier normalized to a URL-parameter-safe format
  - Example: `feature/foo` → `feature-foo`
- **path**: Absolute path based on `MCBD_ROOT_DIR`
- **updatedAt**: Used for sorting the worktree list by last update time

### 4.2 ChatMessage

```typescript
type ChatRole = "user" | "claude";

interface ChatMessage {
  id: string;           // UUID
  worktreeId: string;   // Worktree.id
  role: ChatRole;
  content: string;      // Full text for UI display
  summary?: string;     // Optional short summary
  timestamp: Date;
  logFileName?: string; // Corresponding Markdown log file name
  requestId?: string;   // Future extension: 1 send = 1 UUID
}
```

- **content**: Text displayed directly in the chat UI (prompt/response).
- **summary**: Summary for `Worktree.lastMessageSummary` (optional).
- **logFileName**: Link to the detailed log file in `.claude_logs/`.

### 4.3 WorktreeSessionState

```typescript
interface WorktreeSessionState {
  worktreeId: string;
  lastCapturedLine: number; // Last line count obtained via tmux capture-pane
}
```

- On Stop hook, the entire scrollback is captured via `tmux capture-pane`.
- Lines after `lastCapturedLine` are treated as "new output" for differential extraction.

---

## 5. Core Flows

### 5.1 Startup & Worktree Scan

1. On app startup, scan git worktrees based on `MCBD_ROOT_DIR`.
2. Store/update Worktree records in the DB based on the scanned worktree information.
3. If existing `cw_{worktreeId}` tmux sessions exist, reconcile them with Worktrees (optional).

### 5.2 Message Send Flow (UI → Claude)

**Overview**

```mermaid
sequenceDiagram
    participant UI as UI (Screen B)
    participant API as API_Send
    participant T as tmux
    participant CL as Claude CLI

    UI->>API: POST /api/worktrees/:id/send { message }
    API->>T: Check session existence (cw_{worktreeId})
    alt No session
        API->>T: tmux new-session (cw_{worktreeId})
        API->>T: export CLAUDE_HOOKS_STOP=...
        API->>T: Start claude
    end
    API->>T: tmux send-keys "message"
    API-->>UI: 202 Accepted (send complete)
    Note over UI: Display "Sending..." bubble
```

**Detailed Steps**

1. UI (Screen B) sends `POST /api/worktrees/:id/send` with `{ message }`.
2. API:
   - Retrieves the Worktree from worktreeId and references the path.
   - Checks session existence with `tmux has-session -t cw_{worktreeId}`.
   - If not found, executes UC-2 (lazy startup flow, described below).
3. Sends the message to Claude CLI with `tmux send-keys -t cw_{worktreeId} "<message>" C-m`.
4. API responds immediately with 202 (Accepted). The UI displays the user's message plus a "Sending..." bubble.

### 5.3 Stop Hook Processing Flow (Claude → API → Logs/DB)

```mermaid
sequenceDiagram
    participant CL as Claude CLI
    participant Hook as CLAUDE_HOOKS_STOP
    participant API as API_Hook
    participant T as tmux
    participant DB as SQLite
    participant FS as .claude_logs
    participant WS as WebSocket

    CL-->>Hook: Completion hook invocation
    Hook->>API: POST /api/hooks/claude-done { worktreeId }
    API->>T: tmux capture-pane (capture full scrollback)
    API->>API: Differential extraction (lines after lastCapturedLine)
    API->>FS: Save as Markdown log
    API->>DB: Update ChatMessage and Worktree.updatedAt
    API->>WS: Publish new ChatMessage
```

**Detailed Steps**

1. When Claude CLI completes processing, it executes the command set in `CLAUDE_HOOKS_STOP`.
   - Example:
   ```
   HOOK_COMMAND="curl -X POST http://localhost:3000/api/hooks/claude-done \
     -H 'Content-Type: application/json' \
     -d '{\"worktreeId\":\"{worktreeId}\"}'"
   export CLAUDE_HOOKS_STOP="${HOOK_COMMAND}"
   ```
2. `API_Hook` receives `POST /api/hooks/claude-done`:
   - Reads `WorktreeSessionState.lastCapturedLine` (default 0).
   - Captures scrollback with `tmux capture-pane -p -S -10000 -t cw_{worktreeId}`.
3. Counts lines in the captured text:
   - Extracts only lines after `lastCapturedLine` as "new output".
   - Future extension: If markers (`### REQUEST {id} START/END`) are introduced, only that range can be extracted.
4. Saves the extracted diff as Markdown under `.claude_logs/`.
5. Creates a `ChatMessage` record (`role = "claude"`) with the linked `logFileName`.
6. Updates `Worktree.lastMessageSummary` and `updatedAt`.
7. Publishes the new `ChatMessage` via WebSocket to all clients viewing the relevant worktree.

### 5.4 WebSocket Flow

- Clients subscribe by specifying a `worktreeId` upon connection.
- The server manages rooms/channels per `worktreeId`.
- When a new `ChatMessage` is saved, it broadcasts to all clients subscribed to that `worktreeId`.

Message format example:
```json
{
  "type": "chat_message_created",
  "worktreeId": "feature-foo",
  "message": {
    "id": "uuid",
    "role": "claude",
    "content": "Claude's response...",
    "timestamp": "2025-11-16T03:00:00.000Z",
    "logFileName": "20251116-030000-feature-foo-bd2f8c3d.md"
  }
}
```

### 5.5 Error / Recovery Flow

**When Stop hook doesn't arrive**

- UI side:
  - If "Sending..." isn't replaced after a set period (e.g., 120 seconds), display a warning bubble.
- Server side:
  - Log a timeout in the Hook API (implementation-dependent).
  - Manual checking of `.claude_logs/` or tmux state is expected.

**When tmux session / Claude process crashes**

- During `API_Send`, check tmux session / process state with `tmux has-session`.
- If no session / Claude not found, restart via UC-2.
- Re-set `CLAUDE_HOOKS_STOP` when restarting Claude CLI.

---

## 6. tmux & CLI Tool Integration

### 6.1 Session Naming Convention

- Session name: `mcbd-{ns}-{cliToolId}-{worktreeId}[-{suffix}]` (Issue #2866)
  - `{ns}` is a per-server namespace (8 hex digits, stored in the DB), so two servers with the same worktree ID never share a session name
  - A legacy `mcbd-{cliToolId}-{worktreeId}[-{suffix}]` session is adopted by the server and keeps its legacy name
  - Names are built and split in one place: `src/lib/cli-tools/session-name.ts` (`resolveSessionName` / `parseSessionName`)
  - The ns lives in the server's DB, so the CLI cannot compute it. The server publishes `tmuxSessionNamespace` at the top level of `GET /api/worktrees` and the name actually in use as `agentInstances[].sessionName` on `GET /api/worktrees/[id]` (Issue #2867)
- Example:
  - Claude: `mcbd-0a1b2c3d-claude-feature-foo` (legacy: `mcbd-claude-feature-foo`)
- One session per worktree is maintained.
- Note: Migration from old naming convention `cw_{worktreeId}`: Implemented in Issue #4

### 6.1.5 CLI Tool Abstraction Layer (Implemented in Issue #4)

**Design Pattern:**
- CLI tool abstraction via Strategy pattern
- `BaseCLITool` abstract class defines the common interface:
  ```typescript
  abstract class BaseCLITool {
    abstract id: CLIToolType;
    abstract name: string;
    abstract command: string;

    abstract isInstalled(): Promise<boolean>;
    abstract isRunning(worktreeId: string): Promise<boolean>;
    abstract startSession(worktreeId: string, worktreePath: string): Promise<void>;
    abstract sendMessage(worktreeId: string, message: string): Promise<void>;
    abstract killSession(worktreeId: string): Promise<boolean>;
    getSessionName(worktreeId: string): string;
  }
  ```

**Implementation Classes:**
- `ClaudeTool` - Claude Code CLI
- `CodexTool` - Codex CLI
- `GeminiTool` - Gemini CLI (Issue #368)
- `VibeLocalTool` - Vibe-Local / Ollama (Issue #368)
- `OpenCodeTool` - OpenCode (Issue #379)
- `CopilotTool` - GitHub Copilot CLI (Issue #545)

**Management:**
- `CLIToolManager` singleton class manages each tool instance
- Retrieves the appropriate tool based on the worktree's `cliToolId`

**Benefits:**
- Easy to add new CLI tools (just extend `BaseCLITool`)
- API layer depends only on abstract interfaces, not specific implementations
- Encapsulates tool-specific logic

### 6.2 UC-2: Lazy Session Startup Flow

```bash
# {sessionName}   = cw_{worktreeId}
# {worktreePath}  = /path/to/root/feature/foo
tmux new-session -d -s "{sessionName}" -c "{worktreePath}"

HOOK_COMMAND="curl -X POST http://localhost:3000/api/hooks/claude-done \
  -H 'Content-Type: application/json' \
  -d '{\"worktreeId\":\"{worktreeId}\"}'"

tmux send-keys -t "{sessionName}" "export CLAUDE_HOOKS_STOP='${HOOK_COMMAND}'" C-m
tmux send-keys -t "{sessionName}" "claude" C-m
```

- The wrapper for executing tmux commands directly from the API is organized in `src/lib/tmux.ts`.

### 6.3 Health Monitoring (Variable Intensity)

- Simple implementation: Only check "session existence".
- For more robustness:
  - `tmux list-panes -F "#{pane_pid}"` → Use `ps` to verify the PID is `claude`.
  - If in prompt state (claude has exited), re-set `CLAUDE_HOOKS_STOP` + restart claude.

---

## 7. Persistence

### 7.1 SQLite (db.sqlite)

- Storage location example: `~/.mycodebranchdesk/db.sqlite`
- Tables (conceptual):
  - **worktrees**:
    - id, name, path, last_message_summary, updated_at
    - **cli_tool_id** (added: Issue #4, extended in #379/#545/#988) - CLI tool to use ('claude' | 'codex' | 'gemini' | 'vibe-local' | 'opencode' | 'copilot' | 'antigravity')
    - **selected_agents** (added: Issue #368) - Selected 2-4 agents (JSON array, e.g., '["claude","vibe-local"]')
    - **vibe_local_model** (added: Issue #368) - Ollama model name for Vibe-Local (nullable)
    - repository_path, repository_name, description
    - last_user_message, last_user_message_at
    - favorite, status, link
  - **chat_messages**:
    - id, worktree_id, role, content, summary, timestamp, log_file_name, request_id
    - message_type, prompt_data
  - **session_states**:
    - worktree_id, last_captured_line

### 7.2 Markdown Logs (.claude_logs/)

- A `.claude_logs/` directory is created directly under each worktree directory.
- File naming convention:

  `{YYYYMMDD}-{HHmmss}-{worktreeId}-{uuid}.md`

- Content example:
```markdown
# CommandMate Log

## Worktree
feature/foo

## Timestamp
2025-11-16T03:00:00Z

## User

<User's prompt>

## Claude

<Claude's full response>
```

- Deletion policy:
  - v1 does not perform automatic deletion; future cleanup via CLI is under consideration.

---

## 8. Configuration

### 8.1 Environment Variables (Planned)

- `MCBD_ROOT_DIR` (required)
  - Root directory for git worktree management
- `MCBD_PORT` (optional, default: 3000)
- `MCBD_BIND` (optional, default: 127.0.0.1)
- Potentially added in the future:
  - `MCBD_DB_PATH` (storage location for db.sqlite)
  - `MCBD_LOG_LEVEL` (log output level)

A `.env.example` file is expected to be included in the repository.

---

## 9. Security Model

### 9.1 Local Mode

- Default is `MCBD_BIND=127.0.0.1`
- Access is limited to the same machine.
- Security risk is essentially dependent on the OS user.

### 9.2 LAN Access Mode

- When `CM_BIND=0.0.0.0`, access from any device on the same LAN is possible
- Reverse proxy authentication (Nginx / Caddy, etc.) is recommended (details: `docs/security-guide.md`)
- HTTPS / TLS termination is delegated to the reverse proxy

---

## 10. Extensibility & Future Work

### 10.1 Stop Hook Extension

- Future design allows including `requestId` in the Stop hook payload:

```json
{ "worktreeId": "{worktreeId}", "requestId": "{requestId}" }
```

- By embedding it in `ChatMessage.requestId` and log names, you can more precisely trace "which request this response belongs to."

### 10.2 Multi-LLM / Multi-Session ✅ Implemented (Issue #4, extended in #368/#379/#545)

**Implementation:**
- Supports 7 tools: Claude Code / Codex / Gemini / Vibe-Local / OpenCode / GitHub Copilot / Antigravity
- Each worktree manages its CLI tool via the `cliToolId` field
- Abstraction via Strategy pattern:
  - `BaseCLITool` abstract class
  - `ClaudeTool` / `CodexTool` / `GeminiTool` / `VibeLocalTool` / `OpenCodeTool` / `CopilotTool` / `AntigravityTool` implementation classes
  - `CLIToolManager` singleton for managing tool instances
- Database schema: `worktrees.cli_tool_id` column (default: 'claude')
- Supported APIs:
  - `POST /api/worktrees/:id/send` - Send message
  - `POST /api/worktrees/:id/respond` - Respond to prompt
  - `POST /api/worktrees/:id/kill-session` - Kill session
  - `GET /api/worktrees` - List worktrees (including session state)

**Future Extensions:**
- To add other CLIs, implement by extending `BaseCLITool`
- If Stop hook specifications differ, handle within each tool class

### 10.3 Real-Time Status Detection ✅ Implemented (Issue #31)

**Implementation:**
- Real-time detection of CLI tool state by directly parsing terminal output
- Visual status indicators displayed in the sidebar
- Polling updates every 2 seconds

**Status Types:**

| Status | Display | Detection Condition |
|--------|---------|---------------------|
| `idle` | Gray ● | Session not started |
| `ready` | Green ● | Input prompt `❯` displayed |
| `running` | Blue spinner | Thinking indicator detected |
| `waiting` | Yellow ● | Interactive prompt detected |

**Detection Logic:**
1. Capture terminal output via `captureSessionOutput()`
2. Strip ANSI escape codes
3. Filter empty lines and extract the last 15 lines
4. Pattern match in priority order:
   - Interactive prompt → `waiting`
   - Thinking indicator (`✻ Thinking…`) → `running`
   - Input prompt (`❯`) → `ready`
   - Otherwise → `running` (assumed processing)

**Related Files:**
- `src/config/status-colors.ts` - Centralized status color management
- `src/lib/cli-patterns.ts` - CLI tool-specific pattern definitions
- `src/lib/prompt-detector.ts` - Prompt detection
- `src/types/sidebar.ts` - Status determination logic

For details, see [Status Indicator](./features/sidebar-status-indicator.md).

### 10.4 Repository Deletion ✅ Implemented (Issue #69)

**Implementation:**
- API endpoint and UI for deleting registered repositories
- Batch cleanup of related worktrees, sessions, and pollers
- Centralized session stop processing via Facade pattern

**API:**
- `DELETE /api/repositories` - Delete repository (specify `repositoryPath` in request body)

**Request/Response:**
```json
// Request
{ "repositoryPath": "/path/to/repository" }

// Response (200 OK)
{
  "success": true,
  "deletedWorktreeCount": 3,
  "warnings": []
}
```

**Error Responses:**

| Status | Condition |
|--------|-----------|
| 400 | `repositoryPath` not specified |
| 404 | Repository does not exist |

**Deletion Flow:**
1. Get all worktree IDs belonging to the repository
2. Kill tmux sessions for each worktree (if kill fails, record in warnings and continue)
3. Stop response-pollers
4. Clean up WebSocket subscription state
5. CASCADE delete worktree records from DB
6. Broadcast `repository_deleted` event

**Gradual Error Handling:**
- DB deletion continues even when session kill fails
- Failure information is returned in the `warnings` array

**UI Implementation:**
- Delete button (×) appears on hover over repository filter chips
- Confirmation dialog requires typing "delete"
- Warning icon (⚠️) displayed for repositories set via `WORKTREE_REPOS` environment variable

**Related Files:**
- `src/lib/session-cleanup.ts` - Session/poller stop Facade
- `src/app/api/repositories/route.ts` - DELETE endpoint
- `src/lib/db.ts` - `getWorktreeIdsByRepository()`, `deleteRepositoryWorktrees()`
- `src/lib/ws-server.ts` - `cleanupRooms()`

### 10.5 Observability

- For the future:
  - Response time (latency) measurement
  - Error rates
  - Per-session history metrics
  - Extension fields in ChatMessage and Worktree for metadata to enable visualization.

---

## 11. UI Layout Architecture (PC, Issue #727 / #730 / #747)

> **Note**: The legacy desktop left-pane model (history / files / memo, MobileTabBar) introduced in #600 has been replaced by the activity model described in this chapter (since Issue #3591: the header tools + ActivityPane). Reorganizing the older descriptions is out of scope here.

This chapter covers the **responsibility boundaries, state ownership, and data flow** of the top-level PC UI layout (why the structure exists and who owns which state). Visual layout, interactions (keyboard / Tooltip), and the component catalog are owned by [./UI_UX_GUIDE.md](./UI_UX_GUIDE.md) as the single source of truth and are not duplicated here.

### 11.1 Component Responsibilities and State Ownership

> **Note (Issue #3589 / #3591)**: The 48px full-height ActivityBar is gone from PC. Activities are opened from the tools right after the header's identity group (repository › branch › session) (`HeaderToolBar`, Issue #4218) and the Verification chip on the second row, and the ActivityPane opens from the right by default (it can sit on the left, Issue #4219), laid over the body (pinning it puts it beside the body). The items below describe that layout.

- **HeaderToolBar** (`src/components/worktree/HeaderToolBar.tsx`, Issue #3591): A controlled component that **does not own** the activity-selection state. It receives `active` / `onToggle` as props and draws `HEADER_TOOLS` from `@/config/activity-bar-config` (`ACTIVITIES` without `verification`) as icons right after the identity group of the PC header (`DesktopHeader`, Issue #4218). On a narrow header the trailing tools fold into a "…" list (`useDesktopHeaderFit` decides how many).
- **VerificationStatusChip** (`VerificationStatusChip.tsx`, Issue #1816 / #2064 / #3590): The PC entry point of the `verification` activity (`CHIP_ACTIVITY_ID`). It sits in the second-row action bar and opens/closes the Verification pane when pressed. It is always drawn, reporting "unverified" on a branch with no execution contract (#2064).
- **ActivityBar** (`src/components/worktree/ActivityBar.tsx`): The former 48px vertical Activity Bar. Since Issue #3591 it is not mounted on any screen (the sidebar open/close button moved to `SidebarPanelToggle` in #3512).
- **ActivityPane** (`ActivityPane.tsx`): A stateless, table-driven dispatcher. It picks exactly one node — `activities[active]` — from the parent-built `ActivityContentMap` (`Partial<Record<ActivityId, ReactNode>>`) and renders it through an `ErrorBoundary`. Because a single `active` key resolves to a single node, **rendering multiple activities simultaneously is structurally impossible**.
- **TerminalContainer** (`TerminalContainer.tsx`, Issue #730): Wraps a `terminal` slot (always rendered) and an optional `history` slot. Since Issue #744, the top-level History column is no longer rendered on PC; History was moved inside each terminal split (see §12). The `history` prop and the `useHistoryPaneState` wiring are kept for backward compatibility with the #730 single-column layout.
- **WorktreeDesktopLayout** (`WorktreeDesktopLayout.tsx`, Issue #730 / #3589 / #3591): Lays out the Right pane (the body) and the ActivityPane. The ActivityPane is on the **right** by default (#3591); the `usePaneSide` setting can move it to the left (#4219, shared across worktrees) with "Move to left" / "Move to right" in the pane title. Unpinned — the default — it is drawn over the Right pane, which keeps its width (#3589). Only when pinned (`activityPanePinned`) does it take a column beside the body, with a PaneResizer on the boundary. The pane's frame (title, pin, ×, Esc / outside-press dismissal) is `PaneOverlayFrame` in the same file. When `activityPane === null`, neither the pane nor the PaneResizer is drawn.
- **PaneResizer** (`PaneResizer.tsx`): A generic resizer that owns only transient drag state. It **only reports a pixel delta via `onResize(delta)`**; the parent decides the final pane width. It is reused for both the Right↔Activity boundary in WorktreeDesktopLayout (when pinned) and the History↔Terminal boundary in TerminalContainer.

### 11.2 State Owners (Custom Hooks)

- **useActivityBarState** (`src/hooks/useActivityBarState.ts`): The single source of truth for the `active` state. It persists **per worktree** under `commandmate.worktree.activeActivity-<worktreeId>` (`getActivityBarStorageKey`, Issue #858). **The closed state (null) is persisted too**, as `__closed__` (`ACTIVITY_CLOSED_SENTINEL`), so a pane closed on one worktree stays closed after a visit to another and back. An unvisited worktree or an invalid value gives `INITIAL_ACTIVITY` (`null` = closed since Issue #3589; it was `'files'` before). The initial render is deterministically `INITIAL_ACTIVITY` and the localStorage read happens in a `useEffect` after mount and on every `worktreeId` change (to avoid hydration mismatch).
- **usePanePinnedState** (`src/hooks/useActivityPaneOverlay.ts`, Issue #3589): Whether the ActivityPane is pinned. Stored once under `commandmate.worktree.activityPanePinned` (`ACTIVITY_PANE_PINNED_STORAGE_KEY`) and shared across worktrees. `usePaneOverlayDismiss` in the same file closes an overlaid pane on Esc / an outside press.
- **SidebarContext** (`src/contexts/SidebarContext.tsx`): Owns the sidebar `isOpen` via `useReducer`. The sidebar's own open/close button (`SidebarPanelToggle`, at the top of the `SidebarRail` icon rail while the sidebar is closed) reads this context, forming a separate data-flow path from the props-based activity selection.

The controller (`src/hooks/useWorktreeDetailController.ts`) calls `useActivityBarState`, and the PC orchestrator (`WorktreeDetailDesktop.tsx`) builds the `ActivityContentMap` and wires HeaderToolBar (through `DesktopHeader`) / VerificationStatusChip / ActivityPane / WorktreeDesktopLayout together.

### 11.3 Data-Flow Diagram

```mermaid
graph TD
    Ctrl["useWorktreeDetailController<br/>(calls useActivityBarState)"]
    Parent["WorktreeDetailDesktop<br/>(PC orchestrator)"]
    ActState["useActivityBarState<br/>(owns active / per-worktree localStorage)"]
    PinState["usePanePinnedState<br/>(owns the pin / localStorage)"]
    SideCtx["SidebarContext<br/>(owns isOpen)"]
    SideToggle["SidebarPanelToggle<br/>(sidebar / SidebarRail)"]
    Tools["HeaderToolBar<br/>(header right, stateless)"]
    Chip["VerificationStatusChip<br/>(second row)"]
    Pane["ActivityPane<br/>(table-driven dispatch)"]
    Layout["WorktreeDesktopLayout<br/>(overlay / beside the body when pinned)"]
    Term["TerminalContainer<br/>(terminal + optional history)"]

    ActState -->|active| Ctrl
    Ctrl -->|"active / onToggle"| Parent
    Parent -->|onToggle| ActState
    Parent -->|active / onToggle| Tools
    Parent -->|"open/close verification"| Chip
    PinState -->|activityPanePinned| Parent
    SideToggle --> SideCtx
    Parent -->|"activityPane (nullable)"| Layout
    Parent -->|"ActivityContentMap"| Pane
    Pane --> Layout
    Layout -->|rightPane| Term
```

> **Forward reference**: The per-agent (per-CLI) session status indicator is already implemented in Issue #743 / #749 / #751 (per-split header status and the DesktopHeader agent status row). It is out of scope for this chapter and may be documented later (optional).

---

## 12. TerminalSplits Strategy (PC, Issue #728 / #736 / #744)

This chapter covers the PC terminal's 1–3 splits and the per-(worktreeId, cliToolId) fan-out polling strategy that runs independently per split.

### 12.1 Split State Management (useTerminalSplits)

- The state owner is `src/hooks/useTerminalSplits.ts` (Issue #728). It is **intentionally kept out of** the VS Code-style layout reducer (activityBar / historyPane, etc.) to avoid action bloat.
- Constants (`src/config/terminal-split-config.ts`): `MIN_SPLITS = 1`, `MAX_SPLITS = 3`, `DEFAULT_SPLIT_CONFIG = { splits: [{ cliToolId: 'claude' }], widths: [1] }`.
- Persistence is **per worktree** (splits + widths are stored in localStorage under `getTerminalSplitsStorageKey(worktreeId)`). On a worktreeId change the state is reloaded and `focusedSplitIndex` is reset to 0.
- On load, the config is validated by `isValidSplitConfig` (`splits.length ∈ [1, 3]`, `widths.length === splits.length`, each width finite and positive); on failure it falls back to `DEFAULT_SPLIT_CONFIG` (defense against external edits / stale data).
- **Same-CLI duplicate-selection guard**: `setSplitCliTool` rejects the change if another split already uses that CLI, and `availableCliTools(idx)` returns a list excluding in-use CLIs (the UI `<select>` disables those options). Because the number of CLI types (6) exceeds `MAX_SPLITS` (3), `addSplit`'s unused-CLI assignment never runs out.

### 12.2 per-(worktreeId, cliToolId) Fan-out Polling (useTerminalPanePolling)

- Each `TerminalSplitPaneContent` owns one instance of `src/hooks/useTerminalPanePolling.ts` and calls `GET /api/worktrees/{worktreeId}/current-output?cliTool={cliToolId}` **independently** (split 0 = Claude and split 1 = Codex poll on their own).
- Owned state: `output` / `isRunning` / `isThinking` / `isSelectionListActive` / `attaching` (true until the first successful fetch) / `autoScroll` (per pane) / prompt. Auto-Yes state and History messages are global at activeCliTab scope, so they are **intentionally not owned** here.
- **Stale-response discard (2 axes)**: a `requestId` incremented on every fetch, and an `inFlightCliToolRef` that records the current CLI on every render, are compared at response time; any response that does not match (out-of-order or CLI-switch crossing) is discarded. A response whose server-provided `cliToolId` differs from the requested CLI is also discarded.
- The polling cadence switches on `isRunning` (`ACTIVE_POLLING_INTERVAL_MS = 2000` / `IDLE_POLLING_INTERVAL_MS = 5000`). Ticks where `document.visibilityState === 'hidden'` are skipped, and a single re-fetch runs when visibility is restored (polling stops in the background).
- On a change of `compositeKey = {worktreeId}::{cliToolId}`, `requestId` is bumped, output / prompt are cleared, and the pane returns to the `attaching` state (treated as a fresh attach).

### 12.3 per-split Message History and Namespace Separation

- **useSplitMessages** (`src/hooks/useSplitMessages.ts`, Issue #744): Each split independently fetches `GET /api/worktrees/{worktreeId}/messages?cliTool={cliToolId}` (`SPLIT_MESSAGES_POLL_INTERVAL_MS = 5000`). The parent's `state.messages` is already filtered to activeCliTab, so it cannot be reused to show split A=Claude and split B=Codex at the same time. The stale-guard is identical in form to useTerminalPanePolling.
- **makeHistoryNamespace** (`src/lib/terminal-highlight.ts`, Issue #744): `CSS.highlights` is a global Map keyed by name, so multiple HistoryPanes using the same namespace (`HISTORY_SEARCH_NAMESPACE`) would clobber each other's search highlights. `makeHistoryNamespace(splitIndex)` returns a namespace suffixed by the split index (`history-search-{idx}`, etc.) so each split keeps its highlights under a distinct registry key, avoiding collisions. `applyHistoryHighlights` and friends default to the shared namespace when the `namespace` argument is omitted, so Mobile / single-pane calls are unchanged (backward compatible).

### 12.4 Difference from the Mobile Path

- On Mobile, `MobileTerminalTab` owns a **single instance** of `useTerminalPanePolling` and mounts it only while the terminal tab is shown (polling only the one CLI corresponding to activeCliTab).
- Issue #736 removed the terminal reducer slice, so both PC and Mobile obtain output from `useTerminalPanePolling`. The difference is that PC starts up to `MAX_SPLITS` (3) instances **in parallel**, one per split.

### 12.5 Data-Flow Diagram

```mermaid
graph TD
    Splits["useTerminalSplits<br/>(owns splits / widths / focusedSplitIndex)"]
    Container["TerminalSplitContainer<br/>(delegates each split via renderPane)"]
    P0["TerminalSplitPaneContent[0]<br/>cliTool=claude"]
    P1["TerminalSplitPaneContent[1]<br/>cliTool=codex"]
    Poll0["useTerminalPanePolling"]
    Msg0["useSplitMessages"]
    Poll1["useTerminalPanePolling"]
    API0["/current-output?cliTool=claude"]
    API0b["/messages?cliTool=claude"]
    API1["/current-output?cliTool=codex"]

    Splits --> Container
    Container --> P0
    Container --> P1
    P0 --> Poll0 --> API0
    P0 --> Msg0 --> API0b
    P1 --> Poll1 --> API1
```

> **Note**: The History pane's visibility / width is shared across all splits via `useHistoryPaneState` in the MVP (per-split independent toggle / width is a future extension).
