Switchboard

Your command center for Claude Code sessions.

Switchboard is a desktop app that gives you a unified view of all your Claude Code sessions across every project. Launch, resume, fork, and monitor sessions from a single window — no more juggling terminal tabs or digging through ~/.claude/projects to find that one conversation from last week.

Key Features

• Session Browser — All your Claude Code sessions, organized by project, searchable by content
• Built-in Terminal — Connect to running sessions or launch new ones without leaving the app
• Status Notifications — In-app alerts when a session is waiting for permission approval or user input
• Fork & Resume — Branch off from any point in a session's history
• Full-Text Search — Find any session by what was discussed, not just when it happened
• IDE Emulation — Switchboard acts as an IDE for Claude CLI, showing file diffs and opens in a side panel where you can accept, reject, or edit changes before they're applied. Supports both inline and side-by-side diff views. Disable this in Global Settings if you prefer Claude to use your own editor (VS Code, Cursor, etc.)
• Plans & Memory — Browse and edit your plan files and CLAUDE.md memory in one place
• Activity Stats — Heatmap of your coding activity across all projects
• Session Names — Picks up session names from Claude Code's /rename command automatically

Session Grid Overview

Toggle the grid overview from the sidebar for a bird's-eye view of all your open sessions at once, grouped by project.

• Live terminals — Every open session renders its full terminal in a card, so you can monitor multiple Claude agents simultaneously.
• Status at a glance — Each card shows a running/stopped/busy indicator dot and last-activity timestamp.
• Click to focus, double-click to expand — Click a card header to focus it; double-click to switch back to single-terminal view for that session.
• Persistent — Grid preference is saved across restarts.

File Preview Side Panel & Claude IDE MCP Emulator

Switchboard can act as an IDE for your Claude Code sessions. When enabled, Claude's file opens and proposed edits appear in a side panel next to the terminal instead of being sent to an external editor.

• Diff review — When Claude proposes a file change, it shows up as a diff in the side panel. You can review the changes and accept or reject them directly.
• Inline & side-by-side — Toggle between inline (unified) and side-by-side diff views. Your preference is remembered across sessions.
• Partial acceptance — In inline mode, you can accept or reject individual chunks within a diff, then submit the final result.
• File viewer — Clickable file links in terminal output (OSC 8 hyperlinks) open in the side panel with syntax highlighting.

To disable IDE emulation entirely (e.g. if you want Claude to use VS Code or Cursor instead), uncheck IDE Emulation in Global Settings. This stops Switchboard from registering as an IDE, so Claude CLI will discover and connect to your real editor. Changes take effect on new sessions — running sessions are not affected.

Status Notifications

Switchboard monitors all your sessions in the background and shows status indicators in the sidebar so you can tell at a glance which sessions need attention — even when you're working in a different one.

• Waiting for input — A session that needs your response is highlighted so you don't miss it.
• Permission approval — When Claude is blocked waiting for a permission grant, the session badge lets you know immediately.
• Activity indicators — See which sessions are actively running, idle, or finished.

Editor

Shortcut	Action
Cmd+F / Ctrl+F	Find in file (also works in terminal)
Cmd+G / Ctrl+G	Go to line

Documentation

Full user-facing documentation lives in docs/:

• Session Browser — sidebar, project grouping, full-text search, archive, star, filters
• Terminal — built-in terminal, configurable right-click, drag-and-drop, in-terminal find
• Grid Overview — bird's-eye live grid of all open sessions
• IDE Emulation — file diffs in a side panel, inline and side-by-side, partial accept
• Subagents — subagent index, hierarchy, live status, read-only transcript viewer
• Session Restore — persist open sessions and restore them on restart
• Keyboard Shortcuts — editor/terminal shortcuts and rebindable session-nav keys
• Notifications — sidebar status badges
• Plans, Memory, and Work Files — CodeMirror panels for plan files, CLAUDE.md, and .work-files/
• Activity Stats — coding activity heatmap
• Settings Reference — every field in Global and Project Settings

Download

Grab the latest release for your platform:

Download Switchboard

• macOS: .dmg (Apple Silicon & Intel)
• Windows: .exe installer
• Linux: .AppImage, .deb, or .pacman (Arch/Manjaro)

Prerequisites

• Node.js 20+
• npm 10+
• Platform build tools for native modules:
  • macOS: Xcode Command Line Tools (xcode-select --install)
  • Linux: build-essential, python3 (sudo apt install build-essential python3)
  • Windows: Visual Studio Build Tools or npm install -g windows-build-tools

Tooling

task is the preferred entrypoint for all dev operations. Install it once (brew install go-task / snap install task --classic / see taskfile.dev for other platforms), then:

task install       # npm install
task dev           # launch Electron (--no-sandbox, required on Linux)
task test          # node --test  (24 tests)
task lint          # eslint .
task check         # test + lint  — pre-commit / pre-push gate
task ci            # same as check but sequential, verbose
task build         # npm run build:linux
task clean         # wipe dist/, codemirror bundle, local DB (asks for confirmation)
task db:reset      # wipe ~/.switchboard/switchboard.db only

Run task (no args) to list all tasks with descriptions.

The npm scripts are still present and work as before; task just wraps them as a consistent entrypoint.

Development Setup

task install   # install dependencies (runs postinstall automatically)
task dev       # launch Electron

Or with npm directly:

npm install
npm start      # bundles CodeMirror then launches Electron

npm start bundles CodeMirror and launches Electron. For faster iteration after the first run:

npm run electron

Working alongside a running AppImage

If your ~/Applications/Switchboard.AppImage is open while you develop:

• Dev DB isolation — task dev sets SWITCHBOARD_DATA_DIR=~/.switchboard-dev automatically so the dev electron uses its own SQLite database. The AppImage keeps using ~/.switchboard/switchboard.db. They never collide.
• Single-instance lock — if you double-click Switchboard.AppImage while it's already open, the second launch quits immediately and focuses the existing window instead of spawning a duplicate process. This was a real data-loss bug (PTYs orphaned) before the fix landed.
• Rebuilding is risky, replacing is safe — task build invokes electron-builder, which rebuilds native modules (better-sqlite3, node-pty) by default. Those .node files are loaded by your running AppImage; replacing them mid-run can kill the process (witnessed 2026-05-31). Quit Switchboard before running task build unless you've confirmed --config.npmRebuild=false is in effect. However, replacing ~/Applications/Switchboard.AppImage via cp AFTER the build is safe — the live process is fully extracted to /tmp/.mount_*/ and doesn't need the on-disk file. The new code takes effect only on next launch.

For AI agents

If you're an AI working in this repo, read CLAUDE.md at the project root — it documents the fork-specific features, invariants (no double Electron, no Co-Authored-By, worktree isolation pattern), and the helpers worth reusing (enumerateSessionFiles, encodeProjectPath, ViewerPanel).

Building

All build commands bundle CodeMirror first, then invoke electron-builder.

task build            # AppImage + deb (Linux)

# npm equivalents:
npm run build:mac     # DMG + zip (arm64 + x64)
npm run build:win     # NSIS installer (x64 + arm64)
npm run build:linux   # AppImage + deb + pacman (x64 + arm64)

Output goes to dist/.

Building on Arch / Manjaro

The deb and pacman targets are built via the fpm binary bundled by electron-builder, which links against libcrypt.so.1. Arch ships libxcrypt without that legacy ABI, so install the compat shim once:

sudo pacman -S libxcrypt-compat

AppImage builds without it.

The pacman package is published as switchboard-doctly rather than switchboard because the Arch extra repo already ships a package named switchboard (elementary OS's Pantheon Control Center). Renaming avoids the file-conflict that would block installation alongside it. The app itself is still called Switchboard everywhere users see it — only the package identity changes. Uninstall later with sudo pacman -R switchboard-doctly.

Releasing

Releases are driven by git tags:

git tag v0.1.0
git push origin v0.1.0

The GitHub Actions workflow builds for all platforms and publishes to GitHub Releases. You can also release locally:

npm run release   # builds + publishes to GitHub Releases

Set GH_TOKEN in your environment (a GitHub personal access token with repo scope).

Auto-Updates

The app uses electron-updater to check for updates from GitHub Releases on launch and every 4 hours. Updates are only checked in packaged builds (not during development). The flow:

1. App auto-downloads updates in the background
2. A toast notification appears when the update is ready
3. User can restart immediately or dismiss (installs on next quit)

Code Signing

For distribution, set these environment variables:

• macOS: CSC_LINK (p12 certificate) and CSC_KEY_PASSWORD, or sign via Keychain
• Windows: CSC_LINK and CSC_KEY_PASSWORD for EV/OV code signing
• Set CSC_IDENTITY_AUTO_DISCOVERY=false to skip signing (CI artifact builds)

The macOS build uses custom entitlements (build/entitlements.mac.plist) to allow JIT and unsigned memory execution, required by native modules (node-pty, better-sqlite3).

Project Structure

main.js            Electron main process
preload.js         Context bridge (IPC bindings)
db.js              SQLite session cache & metadata
public/            Renderer (HTML/CSS/JS)
scripts/           Build & postinstall scripts
build/             Icons, entitlements, builder resources
.github/workflows/ CI/CD