Docs — CmdrZone

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.

Status: early but functional. Built in the open — issues and PRs welcome. macOS only for now; Windows / Linux are on the roadmap.

Download

Grab the latest CmdrZone-<version>-arm64.dmg from GitHub Releases, open it and drag CmdrZone to Applications. Builds are for Apple Silicon; on an Intel Mac, build from source.

The app isn't signed with an Apple Developer ID yet, so macOS blocks the first launch ("damaged" or "can't be opened"). Clear the quarantine flag once:

zsh

❯ xattr -dr com.apple.quarantine /Applications/CmdrZone.app
❯ brew install tmux   # recommended: durable sessions

tmux is separate from the app — install it whichever way you run CmdrZone. Without it everything works, but sessions end when the app closes. The ⛓ pill at the right end of the Terminals tab strip shows the mode. Agent CLIs such as claude are detected on your PATH automatically; nothing to configure. The app checks for new versions and opens the release page when one is out.

Requirements

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

Build from source

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

zsh

❯ 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

Run pnpm rebuild:native after every pnpm install. pnpm 10 + Electron require the native modules compiled against Electron's ABI. If you hit a NODE_MODULE_VERSION mismatch, that's the fix.

Build & package

zsh

❯ 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

zsh

❯ 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

Shortcut	Action
`⌘` `K`	Fuzzy project switcher
`⌘` `0`	Open the dashboard
`⌘` `1`–`9`	Jump to a pinned project
`⌘` `T`	New terminal
`⌘` `D`	Split pane
`⌘` `⇧` `D`	Split pane (other orientation)

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.

Build the tool bundles once with pnpm build (emits apps/desktop/out/{cli,mcp}.cjs) before using the CLI or MCP server.

zsh — cmdrzone CLI

❯ 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.

Global flag	Effect
`--json`	Machine-readable output
`--db <path>`	Point at a specific `cmdrzone.db`
`--dev`	Target the CmdrZone Dev store (or `CMDRZONE_INSTANCE=dev`)

MCP server

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

mcp config

{ "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.

apps/desktop/src

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

Electronelectron-viteReact + TypeScript node-pty + xterm.jsMonaco Editorbetter-sqlite3 tmuxpnpm workspace

Headless checks

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

zsh

# 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

Open the repo → CONTRIBUTING.md

Documentation

Overview

Download

Requirements

Build from source

Build & package

Use it daily while developing

Project tree

Embedded agent terminals

Durable sessions tmux

Code editor

Board (per-project Kanban)

Launch a Claude session straight from a card

Project info

Agent awareness

Keyboard shortcuts

Agent CLI

Targets & flags

MCP server

Architecture

Stack

Headless checks

Roadmap

Contributing