# agent-desk

Electron app -- unified control center for AI coding agents.

## Architecture

- `src/main/` -- Electron main process (TypeScript, compiled to `dist/main/`)
  - `index.ts` -- App entry, window management, tray, IPC handlers, dashboard health checks, config file watcher, auto-update
  - `terminal-manager.ts` -- node-pty terminal lifecycle, buffer capture, history tracking
  - `system-monitor.ts` -- CPU/RAM/disk polling, stats event emission
  - `crash-reporter.ts` -- Crash log writer with rotation (`~/.agent-desk/crash-logs/`)
- `src/preload/` -- Context bridge (TypeScript, compiled to `dist/preload/`)
  - `index.ts` -- Exposes `window.agentDesk` API to renderer
  - `webview-bridge.ts` -- Preload script for dashboard webviews (bidirectional state sync)
- `src/renderer/` -- Frontend (vanilla JS + local vendor libs, served directly, NOT compiled)
  - `index.html` -- Main HTML with local vendor imports (xterm.js, dockview-core)
  - `vendor/` -- Local copies of xterm.js + dockview-core (generated by `scripts/copy-vendor.js`, gitignored)
  - `styles.css` -- MD3 dark theme + dockview overrides + all component styles
  - `app.js` -- Entry point: session restore, global listeners, initialization
  - `state.js` -- Shared state (terminals map, dockview instance, active view) and registry
  - `event-bus.js` -- Pub/sub event system for terminal/agent events
  - `terminals.js` -- Terminal creation, tabs, status tracking, task badges
  - `layout.js` -- Dockview grid management, split, maximize
  - `views.js` -- Sidebar, view switching (terminals/comm/tasks/knowledge/monitor/settings)
  - `commands.js` -- Command palette (Ctrl+Shift+P), quick switcher (Ctrl+P), terminal context menu
  - `keybinding-manager.js` -- Customizable keyboard shortcuts with defaults, capture mode, persistence
  - `keybinds.js` -- Shortcut registration (maps action names to handlers)
  - `settings.js` -- Settings panel (40+ options), profile CRUD, config file sync
  - `agent-monitor.js` -- Agent Monitor view (Ctrl+5): agent cards, task polling, status derivation
  - `agent-parser.js` -- Claude Code output parser: tool calls, file modifications, test results, errors
  - `agent-features.js` -- Terminal chains, chain picker, chain indicators
  - `batch-launcher.js` -- Batch launch modal (Ctrl+Shift+B): count, profile, naming, stagger, initial command
  - `templates.js` -- Agent templates/recipes: CRUD, settings section, command palette integration, 2 defaults
  - `comm-graph.js` -- Agent communication graph: canvas rendering, node layout, edge drawing, interaction
  - `global-search.js` -- Cross-terminal search (Ctrl+Shift+F): async chunked search, regex, keyboard nav
  - `event-stream.js` -- Event timeline panel (Ctrl+E): 200 events, filters, search, expandable details, export
  - `search.js` -- In-terminal search bar (Ctrl+F) using xterm.js search addon
  - `theme-manager.js` -- Theme system: 4 built-in + custom themes, CSS property application
  - `theme-init.js` -- Early theme application before full load
  - `workspaces.js` -- Workspace save/load dialogs, layout capture/restore
  - `system-monitor.js` -- Status bar widgets: CPU/RAM/disk stats, cost/token tracking per agent
  - `shell-integration.js` -- OSC sequence parser (OSC 7, OSC 133, OSC 1337) for cwd, commands, marks
  - `dashboard.js` -- Dashboard bridge module
  - `dashboard-injectors/` -- Per-dashboard toolbar injection (comm, tasks, knowledge)
  - `drag-drop.js` -- Drag-and-drop tab reordering
  - `notifications.js` -- Desktop notification handling, bell behavior
  - `context-menus.js` -- Context menu and confirm dialog primitives
  - `popout.html` -- Pop-out terminal window template

## Commands

- `npm run build` -- Compile TypeScript (main + preload) + copy vendor libs to src/renderer/vendor/
- `npm run dev` -- Build + launch Electron
- `npm run watch` -- Watch TypeScript for changes
- `npm run package` -- Build distributable
- `npm test` -- Unit tests (vitest)
- `npx playwright test` -- E2E tests
- `npx eslint src/` -- Lint
- `npx prettier --write .` -- Format

## Design System

Matches agent-comm and agent-tasks dashboards:
- Accent: #5d8da8
- Background: #1a1d23
- Surface: #21252b
- Font: Inter (UI), JetBrains Mono (terminal)
- Icons: Material Symbols Outlined
- Follow MD3 design language

## IPC API

The preload script exposes `window.agentDesk` with:
- `terminal.create/write/resize/kill/signal/restart/popout/list/subscribe/unsubscribe/onData/onExit`
- `session.save/load/getBuffer/autoSave/replayBuffer/setAgentInfo/saveLayout`
- `window.minimize/maximize/close/flashFrame`
- `notify(title, body)` -- desktop notifications
- `onAction(callback)` -- receives tray menu actions
- `onOpenCwd(callback)` -- receives open-cwd deep links
- `dialog.saveFile/openDirectory` -- native file dialogs
- `file.write/stat/dirname` -- file operations
- `config.read/write/getPath/onChange` -- config file (`~/.agent-desk/config.json`)
- `keybindings.read/write` -- keybinding overrides (`~/.agent-desk/keybindings.json`)
- `history.get/clear/onNew` -- command history
- `dashboard.getStatus/onStatusChanged` -- dashboard health status
- `system.getStats/startMonitoring/stopMonitoring/onStatsUpdate` -- system stats
- `app.checkForUpdates/installUpdate/onUpdateStatus/onCrashDetected/reportError/getCrashLogDir` -- app lifecycle
- `openExternal(url)` -- open URLs in browser
- `openPath(path)` -- open directories in file manager
- `webview.getPreloadPath/broadcastTerminalUpdate/onTerminalUpdate` -- webview bridge
- `setLoginItem(enabled)` -- start-on-login toggle

## Dependencies

- node-pty: PTY process management
- xterm.js: Terminal rendering (local vendor, copied from node_modules)
- dockview-core: Dock/grid layout with tabs, drag-drop, resize (local vendor)
- electron: Desktop app framework
- electron-builder: Packaging
- vitest: Unit testing
- playwright: E2E testing

## Config Files

- `~/.agent-desk/config.json` -- Settings, profiles, workspaces, templates (version 1 schema)
- `~/.agent-desk/keybindings.json` -- User keybinding overrides
- `~/.agent-desk/crash-logs/` -- Crash log files (rotated, max 10)

## Rules

- Renderer uses vanilla JS with locally bundled vendor libraries (no React/Vue framework)
- dockview-core for dock/grid terminal layout (local vendor)
- Google Fonts loaded from CDN (non-critical, graceful fallback)
- Keep dark theme consistent with agent-comm/agent-tasks
- TypeScript for main/preload only
