agent-desk

Agent Desk

Unified control center for AI coding agents. Terminals, dashboards, and orchestration in one Electron app. Manage multiple Claude Code sessions, monitor agent status, and coordinate multi-agent workflows from a single window.

For a complete guide, see the User Manual.

Why

Running multiple AI agents means juggling terminals, losing track of which agent is doing what, and manually switching between dashboards. Agent Desk puts everything in one place:

	Without Agent Desk	With Agent Desk
Terminals	Separate windows, no organization	Tabbed grid layout with splits
Agent status	No visibility	Live monitor with status, cost, tasks
Coordination	Manual, error-prone	Batch launcher, templates, comm graph
Dashboards	Open 3 browser tabs	Embedded with health monitoring
Search	Per-terminal only	Cross-terminal search across all buffers
Session restore	Lost on close	Auto-save + restore with buffer replay

Features

Terminal Management

• Multi-terminal with tabs, split views (horizontal/vertical), drag-and-drop reordering
• Dockview grid layout -- resize, maximize, and rearrange terminal panes freely
• Pop-out windows -- detach any terminal into its own native window
• Shell profiles -- Default Shell and Claude Code built-in; create custom profiles with command, args, env, cwd, and icon
• Shell integration -- OSC sequence parsing for current directory tracking and command boundary detection
• Inline rename -- double-click tab labels to rename terminals

Agent Intelligence

• Agent Detection -- auto-detects Claude Code sessions by parsing tool calls, file modifications, test results, and errors from terminal output
• Live tab indicators -- tab titles show agent name, current activity, and attention state (waiting on user, running, idle, errored)
• Lifecycle Controls -- interrupt (SIGINT), stop (SIGTERM), kill (SIGKILL), and restart agents from the context menu or tab buttons
• Cost Tracking -- per-agent token/cost estimation in the status bar with $2/$5 warning thresholds
• Terminal Chains -- trigger commands in one terminal when another exits or changes status

Multi-Agent Orchestration

• Batch Launcher (Ctrl+Shift+B) -- launch N agents at once with profile selection, naming patterns (agent-{n}), stagger delays, working directory, and initial commands
• Templates / Recipes -- save and load reusable multi-agent configurations; 2 built-in defaults (Quick Review: 3 agents, Parallel Tasks: 5 agents)
• Communication Graph -- canvas visualization of agent interactions fetched from the agent-comm API, with animated nodes and edge thickness by message count

Search

• Terminal Search (Ctrl+F) -- search within the active terminal buffer using xterm.js search addon
• Cross-Terminal Search (Ctrl+Shift+F) -- async chunked search across all terminal buffers with case-sensitive and regex options, keyboard navigation, and jump-to-line

Dashboard Integration

• Agent Comm (Ctrl+2) -- embedded agent-comm dashboard, mounted as a first-party plugin into a shadow DOM
• Agent Tasks (Ctrl+3) -- embedded agent-tasks pipeline kanban
• Agent Knowledge (Ctrl+4) -- embedded agent-knowledge dashboard with search and graph
• Agent Discover (Ctrl+5) -- embedded agent-discover MCP registry / marketplace
• Event Stream (Ctrl+6), Settings (Ctrl+7) -- native views
• Plugin system -- each agent-* package ships an agent-desk-plugin.json manifest. Agent Desk discovers them at startup and mounts them via a plugin:// protocol with theme + CSS variable sync into a per-view shadow root
• Dashboard Health -- 30-second health checks with auto-reconnect; sidebar status dots show service availability

Event System

• Event Stream (Ctrl+E) -- filterable timeline panel showing up to 200 events with expandable details, severity color coding, and JSON export
• Event Bus -- internal pub/sub system emitting terminal lifecycle, agent tool calls, file modifications, test results, errors, and chain triggers

Project-Centric Workspaces

• Workspaces (Ctrl+Shift+W / Ctrl+Alt+W) -- bundle a root folder, per-workspace env vars, color, agent selection, and pin state; opening spawns terminals for every configured agent
• Workspace switcher -- titlebar dropdown with pinned + recent workspaces; one-click open
• 24-color palette -- visual identity for tabs, sidebar accents, and switcher rows
• Session Persistence -- auto-save every 60 seconds; restore prompt on startup with 10-second countdown; buffer replay for terminal history
• Layout auto-save -- dockview grid state persisted automatically
• Migration -- pre-1.6 layout-only workspaces lift automatically to the new v2 shape on first read

Git Integration

• Read-only git sidebar -- branch, ahead/behind, per-file status (M/A/D/?/R/U), last commit; powered by simple-git with fs.watch on .git/HEAD + .git/index
• Diff viewer -- Shiki-highlighted dockview overlay with unified and side-by-side modes, j/k hunk navigation, Esc to close, o to open in external editor
• External editor handoff -- detects VS Code, Cursor, Windsurf, VSCodium on PATH; opens files via vscode://file/<path>:<line>:<col> URL scheme with --goto CLI fallback; context menu items on terminal tabs, agent cards, git file rows, and inside the diff viewer

Warp-inspired primitives (v1.7)

• Blocks (Ctrl+B) -- terminal output partitioned by OSC 133 into structured command blocks; collapsible cards with exit-code chip, elapsed time, and one-click rerun
• Diff-first edit review (Ctrl+Shift+R) -- Claude Code tool-call edits captured against git HEAD and presented in a review panel with approve / reject (reverts to HEAD) / comment
• Unified input bar (Ctrl+L) -- titlebar input with intent auto-detect: $ <cmd> pipes to focused terminal, /<name> opens command palette, plain text routes to focused Claude Code agent or configured provider (anthropic / openai / ollama / custom)
• Skills & Rules panel (Ctrl+8) -- browse and edit .claude/skills, .claude/hooks, .mcp.json, CLAUDE.md for the active workspace with path-contained saves
• Tab modality states -- colored dot per tab tracking idle / running / awaiting-input / edits-pending / errored; click to act (open review, focus terminal)

Appearance

• 4 built-in themes -- Default Dark, Default Light, Dracula, Nord; custom themes via the theme manager
• Custom themes -- full color customization including terminal ANSI colors, stored in localStorage
• MD3 design language -- consistent with agent-comm and agent-tasks dashboards
• System tray -- minimize to tray with context menu for quick terminal launch

Configuration

• 40+ settings -- terminal font/size/cursor/scrollback, dashboard URLs, sidebar position, close-to-tray, start-on-login, bell behavior, notifications
• Config file -- ~/.agent-desk/config.json persists settings, profiles, workspaces, and templates
• Keybinding customization -- ~/.agent-desk/keybindings.json for user overrides
• Config hot-reload -- file watcher triggers live updates on external config changes

Quick Start

Install from npm

npm install -g agent-desk
agent-desk

Or build from source

git clone https://github.com/keshrath/agent-desk.git
cd agent-desk
npm install
npm run build
npm run dev

Or download a binary

Pre-built binaries for Windows, macOS, and Linux are available on the GitHub Releases page:

Platform	Format
Windows	NSIS installer, Portable
macOS	DMG
Linux	AppImage, deb

Keyboard Shortcuts

Terminals

Shortcut	Action
Ctrl+Shift+T	New terminal
Ctrl+Shift+C	New Claude session
Ctrl+W	Close terminal
Ctrl+Tab	Next terminal
Ctrl+Shift+Tab	Previous terminal
Ctrl+Shift+D	Split right
Ctrl+\	Split right (alt)
Ctrl+Shift+E	Split down
Ctrl+Shift+M	Toggle maximize
Ctrl+Shift+S	Save output to file
Ctrl+F	Search in terminal
Ctrl+Shift+F	Search all terminals

Navigation

Shortcut	Action
Alt+Arrow	Focus adjacent pane
Ctrl+1	Terminals view
Ctrl+2	Agent Comm view
Ctrl+3	Agent Tasks view
Ctrl+4	Agent Knowledge view
Ctrl+5	Agent Discover view
Ctrl+6	Event Stream view
Ctrl+7	Settings view
Ctrl+8	Skills & Rules view
Ctrl+B	Blocks panel
Ctrl+Shift+R	Pending edits review
Ctrl+L	Focus unified input

General

Shortcut	Action
Ctrl+Shift+P	Command palette
Ctrl+P	Quick switcher
F1	Show keyboard shortcuts
Ctrl+E	Toggle event stream
Ctrl+Shift+B	Batch agent launcher
Ctrl+Shift+W	Save workspace
Ctrl+Alt+W	Load workspace
Escape	Close overlays / search

All shortcuts are customizable via Settings or ~/.agent-desk/keybindings.json.

Configuration

Config is stored at ~/.agent-desk/config.json and organized into sections:

Section	Key Settings
Terminal	fontSize, fontFamily, cursorStyle, cursorBlink, scrollback
Shell	defaultShell, defaultTerminalCwd, defaultNewTerminalCommand
Dashboard	agentCommUrl, agentTasksUrl, agentKnowledgeUrl
Appearance	sidebarPosition, showStatusBar, tabCloseButton, theme
Behavior	closeToTray, startOnLogin, newTerminalOnStartup
Notifications	bellSound, bellVisual, desktopNotifications

Documentation

• Setup Guide -- installation, configuration, shell integration
• Architecture -- process model, IPC, file structure
• Features -- detailed feature documentation
• Changelog
• Contributing

License

MIT -- see LICENSE