# Add to your Claude Code skills
git clone https://github.com/sverrirsig/claude-control
README.md
When you're running several Claude Code instances across different repos and worktrees, it's hard to keep track of what each one is doing. Claude Control auto-discovers all running sessions and gives you a single dashboard with live status, git changes, conversation previews, and quick actions — without leaving the app.
Features
Auto-discovery — Detects all running claude CLI processes via the process table, uses hook events for authoritative PID-to-JSONL mapping with mtime-based fallback
Live status — Classifies each session as Working, Idle, Waiting (needs input), Errored, or Finished using real-time hook events from Claude Code, with CPU/JSONL heuristic fallback
Git integration — Shows branch name, changed files, additions/deletions, and detects open pull requests via gh
PR status badges — Live CI check rollup (passing/failing/pending), review decision, unresolved threads, merge conflicts, and merged/closed state
Task context — Extracts Linear issue titles and descriptions from MCP tool results to show what each session is working on
Conversation preview — Shows the last assistant message, active tool, and user prompt for each session
Approve/reject from dashboard — Approve or reject tool-use permission prompts directly from the dashboard without switching to the terminal
Keyboard shortcuts — Number keys (1-9) to select sessions, Tab/Shift+Tab to cycle, A/X to approve/reject, Enter to focus terminal, E/G/F/P for editor/git/finder/PR
Desktop notifications — Native macOS notifications when sessions finish working or need attention (configurable)
Notification sounds — Subtle two-tone chime on status transitions (configurable)
Quick actions — One-click buttons to focus the terminal tab, open your editor, git GUI, Finder, or PR link for any session
Multiple terminal support — Full tab-level control for iTerm2, Terminal.app, kitty, WezTerm, and cmux; basic support for Ghostty, Warp, and Alacritty (see Terminal support)
tmux integration — Run sessions inside tmux with per-project session grouping or manual session selection; approve/reject without terminal focus via send-keys
A .node-version file is included for version managers like fnm and nvm. With auto-switching enabled, both will pick up the correct version when you cd into the project. Otherwise, run fnm use or nvm use.
Install from DMG
Download the latest .dmg from the Releases page, open it, and drag the app to Applications. Both Apple Silicon and Intel builds are available.
Build from source
# Clone the repo
git clone https://github.com/sverrirsig/claude-control.git
cd claude-control
# Install dependencies
npm install
# Run in development mode (hot-reload)
npm run electron:dev
# Or build a distributable DMG
npm run electron:build
The development server runs on port 3200. The Electron shell loads it automatically.
Scripts
| Command | Description |
|---|---|
| npm run electron:dev | Dev mode with hot-reload (Next.js + Electron) |
| npm run electron:build | Production build → DMG + ZIP in dist/ |
| npm run electron:pack | Production build → unpacked app in dist/ |
| npm run dev | Next.js dev server only (no Electron shell) |
| npm run build | Next.js production build only |
| npm run test | Run unit tests (Vitest) |
| npm run test:watch | Run tests in watch mode |
| npm run lint | Run ESLint |
| npm run typecheck | Run TypeScript type checking |
How it works
Session discovery
Finds all processes named claude via ps
Filters out Claude Desktop (only CLI instances)
Gets each process's working directory via lsof
Reads hook event files (~/.claude-control/events/<pid>.json) for authoritative PID→JSONL mapping and session status
Falls back to mtime-based JSONL discovery for sessions without hook events
Reads the tail of each JSONL file to extract conversation preview and task context
Hook events are installed automatically into ~/.claude/settings.json on first launch. Each Claude process writes its status, session ID, and transcript path to a <pid>.json file on every lifecycle event.
Status classification
Primary (hook events):
| Status | Hook Event |
|---|---|
| Working | UserPromptSubmit, SubagentStart, PostToolUseFailure |
| Waiting | PermissionRequest (overridden to Working if CPU > 15%) |
| Idle | SessionStart, Stop |
| Finished | SessionEnd |
Fallback (heuristic, when hooks unavailable):
| Status | Condition |
|---|---|
| Working | JSONL modified recently AND CPU > 5%, or CPU > 15% |
| Waiting | Pending tool use (after 3s settle) or asking for user input |
| Idle | Process alive, low activity |
| Errored | Last message contains error indicators |
| Finished | Process no longer running |
No database — all state is derived from the process table, hook event files, and JSONL transcripts on every request.
Terminal support
Claude-control auto-detects which terminal each Claude session is running in by walking the process tree. Capabilities vary by terminal:
Full support
These terminals support tab-level focus, text input, and keystroke sending — clicking "focus" in the dashboard switches to the exact tab running that session.
| Terminal | Focus method | How it works |
|---|---|---|
| Terminal.app | AppleScript (TTY matching) | Matches tabs by TTY, uses System Events for keystrokes. Works out of the box. |
| iTerm2 | AppleScript (TTY matching) | Iterates windows/tabs/sessions, matches by TTY path. Native write text for keystrokes. Works out of the box. |
| kitty | Remote control (Unix socket) | Uses kitten @ IPC to resolve window by PID, then focus by window ID. Supports tmux-in-kitty matching. Requires configuration (see below). |
| WezTerm | CLI (wezterm cli) | Uses wezterm cli to list panes, focus by pane ID, and send text directly. Works out of the box. |
| cmux | AppleScript (panel ID) | Reads cmux's native session JSON to resolve TTY → panel ID, then focuses via AppleScript. Works out of the box. |
kitty configuration
kitty requires remote control to be enabled. Add the following to ~/.config/kitty/kitty.conf:
You must restart kitty after making these changes (listen_on is not reloaded on config refresh).
allow_remote_control socket-only — Allows external programs to control kitty via the Unix socket, while preventing programs running inside kitty (e.g. scripts you run) from doing so. This is the recommended security setting.
listen_on unix:/tmp/kitty-{kitty_pid} — Creates a socket at /tmp/kitty-<pid> that claude-control uses to send commands. The {kitty_pid} placeholder ensures each kitty instance gets its own socket.
To verify it's working, run this inside kitty:
kitten @ ls
If it outputs JSON with your windows and tabs, remote control is active. Without these settings, claude-control falls back to basic app activation (no tab selection).
Basic support
These terminals are detected and can be activated, but focus goes to the app — not a specific tab. Text and keystrokes are sent via macOS System Events.
| Terminal | Notes |
|---|---|
| Ghostty | Has AppleScript support since v1.3 but lacks PID/TTY properties for tab matching (#10756). Full support expected when 1.4 ships. |
| Warp | No tab-level IPC available. |
|
The agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Cursor and beyond.
A Claude Code plugin that automatically captures everything Claude does during your coding sessions, compresses it with AI (using Claude's agent-sdk), and injects relevant context back into future sessions.
