Documentation

Overview

CmdrZone is a macOS-first desktop command center for developers who juggle many projects and AI coding agents. It replaces a messy wall of iTerm tabs with a single window: a live tree of every project under a folder you choose (e.g. ~/Development), and a per-project workspace with embedded Claude Code (or other CLI agent) terminals, a code editor, git status and more — designed so you can never prompt the wrong project.

Requirements

• macOS (Apple Silicon recommended; Windows / Linux not yet supported).
• Node.js ≥ 20 and pnpm ≥ 10.
• Xcode Command Line Tools — needed to compile the native modules (node-pty, better-sqlite3).
• Optional: tmux on your PATH unlocks durable sessions.

Install & run

Clone, install dependencies, rebuild the native modules for Electron's ABI, then launch with hot reload.

❯ git clone https://github.com/Innoveramera/cmdrzone.git
❯ cd cmdrzone
❯ pnpm install          # installs deps + downloads Electron
❯ pnpm rebuild:native   # rebuild node-pty + better-sqlite3 for Electron
❯ pnpm dev              # launch with hot reload

Build & package

❯ pnpm build      # build main + preload + renderer
❯ pnpm typecheck  # tsc on node + web projects
❯ pnpm dist       # package a macOS DMG (ad-hoc signed by default)

For a distributable signed/notarized DMG, set your Apple Developer ID in apps/desktop/electron-builder.yml and provide notarization credentials.

Use it daily while developing

❯ pnpm app:install   # build + copy CmdrZone.app to /Applications

The installed app stores data in ~/Library/Application Support/CmdrZone, separate from pnpm dev — which runs as "CmdrZone Dev" with its own data store — so development never disturbs your daily setup. First launch of the unsigned build: right-click → Open.

Project tree

Pick a root folder and CmdrZone builds a live tree of every project beneath it — including monorepo sub-projects. Each entry carries:

• Favorites / pins — keep your active projects at the top and jump to them with ⌘1–9.
• A stable per-project color — the same project is always the same color, everywhere in the UI.
• Git dirty count — see uncommitted changes at a glance.
• Live agent / session indicators — know which projects have a running agent.
• Rename on disk — double-click a project name to rename its folder (confirmed first; the board and preferences follow the new name).

Embedded agent terminals

Each project gets real PTY terminals running your agent of choice — Claude Code by default, or Aider / Codex / Gemini / opencode. Terminals spawn a login + interactive shell (zsh -l -i) so your full PATH is present and claude, node and pnpm resolve correctly.

• Resume in one click — pick up the last Claude conversation with claude --continue.
• Split panes — split any terminal tab into row/column panes; each pane is its own live PTY. ⌘D / ⌘⇧D.
• Model-agnostic — agents are just launch recipes, so you can add your own command as a one-click agent.

Durable sessions tmux

When tmux is available on your PATH, each terminal's PTY is a tmux client attached to a session on a detached server. The practical upshot:

• Quit or reload the app — agents keep running. Sessions live on the detached tmux server.
• They reattach on next launch. The renderer persists your tab/pane layout and restores live sessions on boot.
• Closing a tab is the only thing that destroys a session. Disposing a view just detaches the client.

If tmux isn't installed, CmdrZone falls back to a classic direct PTY spawn — everything still works, just without survive-restart durability.

Code editor

A Files + Monaco tab — the same editor that powers VS Code — with multi-file tabs, IntelliSense, a minimap and save. Browse the project tree and edit without leaving the command center.

Board (per-project Kanban)

A Trello-style board for each project — columns Ideas 💡 / To Do / In Progress / Done with card types idea, feature, bug and task. Drag-and-drop cards with notes, persisted in SQLite, so you can track what to build and fix per project.

Launch a Claude session straight from a card

Hit ▶ on a card and CmdrZone seeds a prompt from its title and body (editable preview first), opens the session in the Terminals tab, and slides the card to In Progress — turning a backlog item into a running agent in one move.

Project info

• Docs preview — README / CLAUDE.md / TASKS.md rendered inline.
• One-click scripts — package.json scripts become run buttons.
• Git status — branch and working-tree state.
• Dev-server port detection — open a detected local server in your browser.
• .env presence — see at a glance whether a project has one.

Agent awareness

CmdrZone watches your agents so you don't have to babysit tabs:

• Per-project status — working / waiting / done / error.
• An agent activity rail — a live overview across all projects.
• Native notifications — get pinged when an agent needs your input or finishes.

Keyboard shortcuts

Agent CLI

A cmdrzone CLI lets AI agents (and you) create and manage board cards without the GUI — e.g. a Claude session files a bug/feature/task card when it finishes a piece of work. It talks straight to the SQLite store (cmdrzone.db) via the shared command core and runs under ELECTRON_RUN_AS_NODE, reusing the Electron-ABI better-sqlite3 — no app needs to be running and no extra native build is required.

❯ node bin/cmdrzone.mjs projects list
❯ node bin/cmdrzone.mjs card add --project myapp --column Ideas \
       --title "Add dark mode" --type feature
❯ node bin/cmdrzone.mjs board show --project myapp --json
❯ node bin/cmdrzone.mjs card move --id <cardId> --column "In Progress"

Targets & flags

--project takes a project name or absolute path; --column a name or id. card add --json returns the new card's id for use with move / update / rm.

Full command surface: card add|update|move|rm and column add|rename|rm. Run node bin/cmdrzone.mjs --help for everything. Changes appear in an open board when its window regains focus.

MCP server

Point any MCP client (Claude Code / Claude Desktop) at the launcher and your agent can manage the board through tools:

{ "mcpServers": { "cmdrzone": {
  "command": "node",
  "args": ["<repo>/bin/cmdrzone-mcp.mjs"],
  "env": { "CMDRZONE_INSTANCE": "daily" }   // or "dev"
}}}

Available tools: list_projects, get_board, create_card, update_card, move_card, delete_card, create_column, rename_column, delete_column.

Architecture

A pnpm workspace. core, pty and shared import nothing from Electron, so they stay portable; all privileged work crosses a typed IPC contract.

shared/    types + typed IPC contract (no electron / node)
core/      domain logic: env, project scanner, agents, persistence, fs
pty/       node-pty session manager (PTY-host utilityProcess)
main/      electron main process + pty-host entry
preload/   contextBridge surface (the only renderer→main bridge)
renderer/  React UI: Zustand store, xterm terminals, Monaco editor

The renderer is locked down — sandbox: true, contextIsolation: true, no nodeIntegration. Native modules (node-pty, better-sqlite3) load only in the main / PTY-host processes.

Stack

Headless checks

Two smoke checks run without a GUI — handy for CI or a quick sanity pass:

# native modules + PTY runs `claude --version`
❯ SB_SMOKE=1 node_modules/.bin/electron apps/desktop
# prints the project scan
❯ SB_SCAN=1  node_modules/.bin/electron apps/desktop

Roadmap

• Vercel deploy status; richer dev-server detection.
• Windows support.
• More built-in agent recipes.

Durable, tmux-backed sessions have landed — see Durable sessions.

Contributing

Issues and PRs are welcome. CmdrZone is GPL-3.0-or-later © Fredrik Hammarström and developed in public.