CLAUDE.md

# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Project Overview

Claude Session Manager (CSM) is a CLI tool for managing Claude Code sessions across local and remote machines using tmux and git worktrees. It provides both a command-line interface and an interactive TUI dashboard built with React + Ink.

## Commands

```bash
bun install              # Install dependencies
bun link                 # Link globally as 'csm' command
bun run dev              # Run CLI locally
bun test                 # Run all tests
bun test:unit            # Unit tests only
bun test:integration     # Integration tests only
bun run typecheck        # TypeScript type checking (tsc --noEmit)
```

Run a single test file: `bun test src/path/to/file.test.ts`

## Architecture

**Runtime:** Bun with native TypeScript support (no build step). ES modules throughout.

**Three layers:**

1. **CLI layer** (`src/index.ts`, `src/commands/`) — Argument parsing and command dispatch. Commands: `create`, `attach`, `kill`, `list`/`ls`, `hosts`, `tui`, `help`. No command launches the TUI dashboard.

2. **Core library** (`src/lib/`) — Business logic abstractions:
   - `tmux.ts` — tmux session operations (create, attach, kill, list, state reading)
   - `worktree.ts` — Git worktree lifecycle (create branch `csm/<name>-<timestamp>`, metadata via `.csm-metadata.json`)
   - `config.ts` — Config management at `~/.config/csm/config.json`
   - `ssh.ts` — Abstracts local vs remote command execution over SSH
   - `claude-state.ts` — Reads Claude Code session state from `/tmp/csm-claude-state/`
   - `linear.ts` — Linear issue search, comments (fetch + create)
   - `tool-rules.ts` — Tool approval rule evaluation engine (glob pattern matching, first-match-wins)
   - `event-store.ts` — Persistent JSONL event store for SSE replay (`~/.config/csm/events/`)
   - `claude-usage.ts` — Claude usage tracking via OAuth credentials (file, macOS Keychain)
   - `ws-session-manager.ts` — WebSocket session state management and event broadcasting

3. **TUI layer** (`src/tui/`) — Interactive dashboard using React + Ink:
   - `App.tsx` — Root component with `useReducer` state management
   - Views: `Dashboard`, `CreateSession`, `SessionDetail`
   - Components: `Header`, `Footer`, `SessionList`, `StatusBar`
   - `hooks/useSessions.ts` — Session fetching with 5-second auto-refresh
   - `theme.ts` — Centralized color/styling constants

4. **Web layer** (`src/web/`) — React web dashboard (HeroUI + Vite):
   - `router.tsx` — React Router configuration
   - Views: `Dashboard`, `SessionDetail`, `CreateSession`, `TasksView`, `TaskDetailView`, `ToolRulesView`, `SettingsView`, `ProjectsView`, `HostsView`
   - Components: layout (`Header`, `Footer`, `Sidebar`), session (`SessionCard`, `SessionTable`, `GitChanges`, `FavoriteButton`), messaging (`ClaudeView`, `LogViewer`, `MessageInput`), tools (`ToolApprovalModal`, `ToolApprovalBanner`), common (`Chip`, `StatusBadge`)
   - Hooks: `useSessionStream` (WebSocket streaming), `useToolApprovals`, `useClaudeUsage`, `useLinearTasks`

**State management:** TUI uses `useReducer` with actions (`SET_VIEW`, `SET_SESSIONS`, `SET_LOADING`, `SET_ERROR`, `SET_MESSAGE`). Views: `"dashboard"` | `"create"` | `"detail"`. Web uses TanStack Query for server state and Zustand for client state (favorites).

**Path alias:** `@/*` maps to `src/*` (configured in tsconfig.json).

## Conventions

- Session names are prefixed with `csm-` (e.g., tmux session `csm-my-feature`)
- Worktree branches follow pattern `csm/<session-name>-<timestamp>`
- Worktree metadata stored in `.csm-metadata.json` at worktree root
- `tmux.ts` dynamically generates a `CLAUDE.md` in worktrees via `writeClaudeContext()` with Linear issue context
- Commands return `{ success, stdout, stderr, exitCode }` result objects
- TUI attaches to tmux by exiting the Ink app, running tmux attach, then relaunching TUI on detach (`exitTuiAndAttach()`)