Cockpit

Unified desktop hub for Claude Code, Codex, and GitHub Copilot CLI: browse every session across providers, continue any conversation, start new agent runs in isolated worktrees, and manage the shared AI setup — from one window.

Install

Cockpit is early access: pre-1.0, and its releases are not yet signed with an Apple Developer ID (CONTRIBUTING.md › Releases), so macOS blocks the first launch. Installing takes four steps, once:

1. Download the disk image for your Mac from the latest release — Cockpit-<version>-arm64.dmg on Apple silicon, Cockpit-<version>-x64.dmg on Intel (About This Mac says which). Open it and drag Cockpit into Applications. Each release page carries the notes for that version.

2. First launch — open Cockpit from Applications. macOS refuses: "Apple could not verify Cockpit.app is free of malware" on macOS 15 and later, "damaged" or "unidentified developer" before. Click Done, not Move to Trash — the download is fine; the quarantine flag the browser put on it is what Gatekeeper objects to.

3. Allow it — open System Settings › Privacy & Security, scroll to the notice that Cockpit was blocked, click Open Anyway and confirm with your password or Touch ID. Or clear the flag from Terminal and open it again:

   xattr -d com.apple.quarantine /Applications/Cockpit.app

4. Updates — you only do the three steps above once. From then on Cockpit checks GitHub Releases on launch and every few hours, fetches a newer build in the background and swaps it in the next time you quit, clearing the quarantine flag itself so the new version opens without another trip to Privacy & Security. Settings › About shows where it stands, offers Restart now, and holds both switches if you would rather do it by hand. A failed install puts the version you had back and says why.

Every release asset carries a build-provenance attestation, so you can confirm a download is the file the release workflow produced before opening it:

gh attestation verify ~/Downloads/Cockpit-<version>-arm64.dmg --owner tashtit

Run from source

Requires Node 24 (.nvmrc) and the npm 11 it bundles (pinned as packageManager).

npm ci
npm run dev        # dev mode with HMR — first run downloads the Electron binary
npm run typecheck  # tsc (the static gate — there is no linter)
npm test           # vitest: unit + component tiers
npm run test:e2e   # Playwright against the built app (npm run build first)
npm run package    # macOS disk images into dist/ (unsigned without Apple credentials)

CI (.github/workflows/ci.yml) runs typecheck plus all three test tiers, packages the app on every pull request, and cuts a semantic release from main. Setup details and troubleshooting (including "Electron failed to install correctly") are in CONTRIBUTING.md.

What it does (GitHub-first)

• Auto-detects ~/.claude, ~/.codex, ~/.copilot on first run and indexes all sessions found there, grouped by git repository (worktree-aware: sessions in linked worktrees group under their main repo; GitHub owner/repo is read from the origin remote). Non-repo sessions land in a flat "Chats" section at the bottom of the sidebar.
• Compact treeview sidebar, flattened: one owner/repo row per repository with its sessions under it, ordered by last activity (paginated "more…", global search, per-repo archived section, agent-generated session names). The full index is never shipped to or rendered by the UI.
• Home — mission control: a task composer front and center (repo + agent + account + permission mode, ⌘Enter to start), recent activity below. The sidebar stays the exhaustive list.
• AI Setup: one place to manage the shared AI experience across all three agents.
  • Shared instructions: write one baseline (global, or per-repo) and fan it out into each agent's own instructions file (~/.claude/CLAUDE.md, ~/.codex/AGENTS.md, ~/.copilot/copilot-instructions.md; in repos CLAUDE.md + AGENTS.md — Codex and Copilot both read AGENTS.md natively). The shared text lives inside <!-- agent-parity:shared --> markers — the same block the agent-parity plugin manages; older <!-- cockpit:shared --> markers are read too — and everything outside is that agent's own and never touched. Drift detection (in sync / out of date / not applied) with one-click re-apply, plus inline editing of each full file.
  • MCP / skills / plugins / marketplaces inventory, with one-click MCP sharing that translates a server definition into each agent's own config format (~/.claude.json, ~/.codex/config.toml, ~/.copilot/mcp-config.json) and skill copying between Claude and Copilot. Claude's per-project MCP servers (under projects.* in ~/.claude.json) are inventoried too, labeled with their project.
• Per-agent session options: model override for all agents, sandbox mode for Codex — validated main-side before touching argv.
• Agent accounts: detects who each CLI is signed in as per config home (Claude .claude.json OAuth, Codex auth.json JWT, Copilot's native multi-account config.json) plus the gh user; identity chips appear throughout, and New Session lets you pick the account when a provider has several config homes.
• Subscription usage (in Settings), without ever touching credentials: Claude measured locally from session JSONLs (5h block + trailing 7 days), Codex from the rate-limit snapshots its CLI persists, Copilot premium requests via the GitHub billing API.
• Fast by architecture: only per-provider session roots are walked/watched (never pkg/, repos/, logs, or SQLite files); meta parsing reads at most 256KB per file (copilot's session.start line carries repo/branch/cwd); the stat-cache (mtime+size) persists to userData so restarts only re-parse changed files; scans yield to the event loop so IPC never blocks.
• Archiving: sessions can be archived in-app (stored in cockpit config — provider logs have no such flag); archived sessions collapse into a dimmed per-repo section. Sessions archived or deleted in the provider's own app (Copilot's data.db, Codex's archived_sessions/, the Claude desktop app's session store) are hidden entirely.
• Settings view: agent accounts & sources (add/remove extra per-account config homes, with per-source identity and health), a history window (show all sessions or just the last N days), subscription usage, and GitHub identity.
• Watches source dirs — sessions you run in any terminal appear/update live.
• Click a session → parsed transcript (messages, tool calls, results).
• Always worktrees, always PRs: "+ New session" creates a cockpit/<name> branch in an isolated git worktree (under the app's userData, outside your checkout) and runs the agent there. "Create PR" pushes the branch and runs gh pr create. PR state badges (open/draft/merged/closed, GitHub colors) come from gh pr list, cached 60s per repo.
• Notifications when an agent needs you: a desktop notification (agent, session, a one-line outcome — click to open it), a macOS system sound, and a Dock badge counting sessions that landed and haven't been opened, when a turn finishes or fails or a roundtable concludes. Never for the session in front of a focused window; endings that arrive together share one notification. On in installed builds, off in dev and test runs (Settings › Notifications). macOS refuses notifications from unsigned builds — the sound plays and the Dock icon bounces instead.
• Review before landing: "Changes" (⌘D) in a session swaps the transcript for the worktree's diff — branch vs base (with ahead/behind), staged, or unstaged incl. untracked files — unified or split, with line numbers. Pin notes to lines and send them to the agent as one message.
• Fix what the PR is waiting on: with an open PR, the review leads with its failing checks, requested changes, unresolved threads (shown under their lines too) and conflicts; "Fix with " turns them into one prompt — failed-step logs included — ready in the composer.
• Working chat: pick a provider + repo path → chat spawns the CLI headless (claude -p --output-format stream-json, codex exec --json, copilot -p) and streams replies, tool activity, and errors into the window. Multi-turn works via each provider's resume (--resume / exec resume). Opening an indexed session and typing continues that conversation.
• Permission modes per chat: Safe (provider defaults; tools may be blocked in headless mode), Auto-edit (--permission-mode acceptEdits / --full-auto), YOLO (bypass approvals — trusted repos only).
• Extra source dirs (isolated per-account config homes) are stored in the app config (~/Library/Application Support/Cockpit/cockpit-config.json) as {path, provider, label}.

Layout

src/shared/types.ts       domain vocabulary (SessionMeta, RepoInfo, …) — imports nothing from src/
src/shared/contract.ts    the whole renderer↔main IPC surface (CockpitApi, CH, PUSH)
src/main/parsers/         per-provider session log parsers (failure-tolerant)
src/main/repos.ts         cwd → git repo resolution (worktree-aware, GitHub remote)
src/main/indexer.ts       scan + stat-cache + fs.watch(recursive) + repo grouping + paging
src/main/extensions.ts    MCP/skills/plugins inventory + cross-agent MCP/skill sharing
src/main/instructions-core.ts  shared-instructions pure logic (markers, drift, targets)
src/main/instructions.ts  shared-instructions IO (baseline storage + fan-out)
src/main/github.ts        PR status per repo via `gh pr list` (cached)
src/main/workspace.ts     worktree/branch creation + push/`gh pr create`
src/main/chat.ts          ChatManager: spawn provider CLIs, parse stream events
src/main/attention-core.ts  which turn endings are news: landings, Dock badge count, notification bursts (IO-free)
src/main/attention.ts     notifications, system sounds, Dock badge + bounce (Electron), landings persisted to userData
src/main/accounts.ts      who each agent CLI is signed in as, per config home + `gh` user
src/main/usage.ts         subscription usage per provider (local measurement / CLI snapshots / GitHub billing API)
src/main/provider-archived.ts  sessions archived/deleted in the provider's own app → hidden
src/main/env.ts           PATH fix for GUI-launched CLI spawns (macOS)
src/main/updates.ts       app updates from GitHub Releases (electron-updater; installed builds only)
src/main/config.ts        source-dir registry + history window
src/main/index.ts         electron bootstrap + IPC
src/preload/index.ts      contextBridge → window.cockpit
src/renderer/             React UI (HomeView, TreeSidebar, ChatView, NewSession, AiSetup, Settings, Select, logos.tsx)

Notes

• File watching uses Node's fs.watch(root, {recursive: true}) (FSEvents on macOS) — chokidar was dropped after its bundled fsevents native module broke on the Electron 43 upgrade; the indexer does its own debouncing and stat-based dirty tracking.

• Session log formats are provider-internal and drift between releases; parsers skip anything they can't read rather than fail.

• The Copilot parser is best-effort (least documented format). If your sessions don't show up, open an issue-to-self: grab one file from ~/.copilot and adjust src/main/parsers/copilot.ts.

• No SQLite yet on purpose — in-memory index is plenty for M1 and avoids native-module rebuild pain. Revisit at M6 (full-text search).

• Copilot chat streams plain text (no structured events), so a new Copilot chat doesn't learn its session id mid-conversation — the session appears in the sidebar after the first turn; click it to continue with proper resume. Claude/Codex bind their session id from the first response.

• Codex event stream shapes changed between releases; both the old (msg.type) and new (thread.started/item.completed) shapes are handled.

License

Apache-2.0