Skip to content

Dominien/claude-code-commander

BranchesTags

Repository files navigation

Claude Code Commander

See what your AI agents are actually doing.
Run multiple Claude Code sessions. Watch every file change in real time. One orchestrator to coordinate them all.

The Problem · How It Works · Orchestrator · Getting Started · Architecture

Stars License Platform


The Problem

You run Claude Code in a terminal. It edits files, runs commands, builds features. But you can't see what it's doing. You're staring at a terminal scrolling past, and the only way to know what changed is to git diff after it's done.

Now multiply that by three or four repos — a frontend, a backend, a shared library. You have multiple terminal windows open, agents running in each, and zero visibility into what code is actually being written across any of them.

Every other tool out there gives you a chat window. None of them show you the code changes as they happen, let you browse the file tree, or give you a diff view while the agent is still working.

That's what Commander solves.


How It Works

graph LR
    subgraph Commander["Claude Code Commander"]
        direction TB
        SB["Sidebar<br/>All your projects"]
        TERM["Tabbed Terminals<br/>Claude + shell tabs"]
        DIFF["Diff View<br/>Every change, live"]
        TREE["File Explorer<br/>What changed, what's new"]
        ENV["Env Variables<br/>Per-project secrets"]
        EDIT["File Editor<br/>Edit & save in-app"]
    end

    YOU([You]) --> SB
    SB --> TERM
    SB --> DIFF
    SB --> TREE
    SB --> ENV
    SB --> EDIT

    style Commander fill:#0d1117,stroke:#30363d,color:#e6edf3
    style YOU fill:#3fb950,stroke:#3fb950,color:#fff
Loading

1. Add your projects

Register any git repository from the sidebar. Add as many as you want — your frontend, backend, infra, libraries, monorepo packages. Each project gets its own independent workspace.

2. Start a session and talk to the agent

Click a project, hit Start Session, and a real Claude Code CLI session launches in that directory. This isn't a chat wrapper — it's a full PTY terminal with scrollback, ANSI colors, clickable links, and keyboard input. Talk to your agent, give it tasks, ask it questions. Everything you can do in a terminal, you can do here.

3. See what the agent is doing — while it's doing it

This is the core of Commander. While the agent works, you see:

  • Live file tree — which files were added, modified, or deleted, updating in real time with status badges
  • Diff view — unified or side-by-side diffs with syntax highlighting, refreshing as the agent writes code
  • File editor — click any file to read and edit it with line numbers, dirty indicator, and Cmd+S to save
  • One-click revert — undo changes per file or revert the entire codebase

You don't have to wait for the agent to finish. You don't have to run git diff. You see every change as it happens.

5. Environment variables — safe, per-project

Click the Env button in the top bar to open a Vercel-style key-value editor. Set secrets, API keys, or config per project. Values are masked by default with an eye toggle.

  • Stored in ~/.commander-central/envs/ — never in the repo, nothing to accidentally commit
  • Automatically injected into Claude sessions and shell terminals at spawn time
  • .env* files also show up in the file tree so you can edit them directly if you prefer

6. Shell terminals alongside Claude

Each project gets a tabbed terminal area. The Claude tab is always present, and you can spawn as many shell tabs as you need — run dev servers, builds, tests, linters, anything.

  • Click + in the terminal tab bar to spawn a new shell
  • Each shell runs in the project directory with your env vars injected
  • Close a tab (x) to kill the process, or exit to auto-remove it
  • All terminals stay mounted when switching tabs — no lost state

4. Manage multiple sessions at once

The sidebar shows every project with a live status indicator:

  🟢  Active     — agent is generating output
  🟡  Waiting    — agent needs your input
  🔵  Starting   — session is booting up
  ⚪  Idle       — ready for the next prompt
  🔴  Error      — session crashed

Switch between projects instantly. Each one keeps its own terminal history, diff state, and file tree. Toggle auto-accept per session to let agents run fully autonomously, or keep manual approval on.


Orchestrator

Once you're running multiple sessions, you'll want one agent that can see everything. The orchestrator is a dedicated Claude Code session with MCP tools that give it control over every other session.

graph LR
    You([You]) -->|talk to| Orch[Orchestrator Agent]
    Orch -->|start/stop<br/>send commands<br/>read output| S1[Agent: Frontend]
    Orch -->|start/stop<br/>send commands<br/>read output| S2[Agent: Backend]
    Orch -->|start/stop<br/>send commands<br/>read output| S3[Agent: Infra]
    Orch -->|read files<br/>view diffs| Any[Any Codebase]

    style Orch fill:#58a6ff,stroke:#58a6ff,color:#fff
    style You fill:#3fb950,stroke:#3fb950,color:#fff
Loading

Click the orchestrator icon at the top of the sidebar. It launches with --dangerously-skip-permissions so it can act without interruption.

What you can say to the orchestrator

"Start sessions in all repos and run their test suites"

"The backend agent is stuck — check its output and help it"

"Read the API types from the frontend repo and send them to the backend agent"

"Which repos have uncommitted changes? Commit them all with good messages"

MCP tools

Tool Description
list_codebases List all registered repos with IDs, names, paths
get_all_statuses Session status for every codebase at once
get_session_output Read the last N lines of terminal output from any session
send_to_session Send text input to any running agent
start_session Spin up a Claude Code session in any repo
stop_session Kill a running session
get_diff Get the full git diff from any codebase
read_file Read any file from any registered codebase

Getting Started

git clone https://github.com/Dominien/claude-code-commander.git
cd claude-code-commander
npm install
npm run dev

Prerequisites


Architecture

graph TB
    subgraph Electron["<b>Electron Main Process</b>"]
        direction TB
        CM["<b>CodebaseManager</b><br/>Lifecycle orchestration"]

        CM --> SC1["SessionController<br/><i>Repo A</i>"]
        CM --> SC2["SessionController<br/><i>Repo B</i>"]
        CM --> SC3["SessionController<br/><i>Repo N...</i>"]
        CM --> ORC["SessionController<br/><i>Orchestrator</i>"]
        CM --> API["McpServer<br/><i>HTTP API on localhost</i>"]

        SC1 --- PTY1["node-pty → claude CLI"]
        SC1 --- GIT1["GitManager<br/>Diffs · File tree · Edit · Revert"]
        SC1 --- FW1["FileWatcher<br/>Polling · No EMFILE"]
        SC1 --- SH1["ShellManager<br/>Multiple shell PTYs"]

        CM --- ENV["EnvStore<br/>Per-project env vars<br/><i>~/.commander-central/envs/</i>"]

        SC2 --- PTY2["node-pty → claude CLI"]
        SC3 --- PTY3["node-pty → claude CLI"]
        ORC --- PTY4["node-pty → claude CLI<br/><i>with MCP tools</i>"]
    end

    subgraph MCP["<b>MCP Bridge (stdio ↔ HTTP)</b>"]
        BRG["mcp-bridge.cjs"]
    end

    PTY4 <-->|"stdin/stdout<br/>(MCP protocol)"| BRG
    BRG <-->|"HTTP<br/>localhost"| API

    subgraph UI["<b>Renderer Process</b>"]
        direction TB
        APP["React 19 · Zustand · Tailwind CSS 4"]
        APP --- SB["Sidebar<br/>Codebase list · Status dots"]
        APP --- CV["CodebaseView<br/>File tree · Diff · Terminal"]
        APP --- OV["OrchestratorView<br/>Dashboard · Terminal"]
    end

    Electron <-->|"Electron IPC<br/>Preload bridge"| UI

    style Electron fill:#0d1117,stroke:#30363d,color:#e6edf3
    style UI fill:#0d1117,stroke:#30363d,color:#e6edf3
    style MCP fill:#0d1117,stroke:#30363d,color:#e6edf3
Loading

Why a stdio bridge?

Claude Code's MCP implementation only supports servers spawned via command/args (stdio transport). It doesn't support connecting to HTTP/SSE endpoints. So the orchestrator's MCP tools work through a bridge:

sequenceDiagram
    participant CC as Orchestrator<br/>(Claude Code)
    participant Bridge as mcp-bridge.cjs
    participant API as McpServer<br/>(Electron main)
    participant Session as Target Session

    CC->>Bridge: tool call via stdio
    Bridge->>API: HTTP POST /api/call
    API->>Session: Execute (read output, send input, etc.)
    Session-->>API: Result
    API-->>Bridge: JSON response
    Bridge-->>CC: tool result via stdio
Loading

The bridge script is generated at runtime with the correct port and NODE_PATH baked in.


Tech Stack
Runtime Electron 33 · node-pty
Frontend React 19 · TypeScript 5.6 · Tailwind CSS 4 · Zustand 5
Terminal xterm.js 5.5 (FitAddon, WebLinksAddon)
Git simple-git · diff2html · highlight.js
MCP @modelcontextprotocol/sdk (StdioServerTransport)
Storage electron-store
Build electron-vite 5 · electron-builder 25

Project Structure

src/
├── main/                        # Electron main process
│   ├── CodebaseManager.ts       # Codebase + orchestrator lifecycle
│   ├── SessionController.ts     # PTY session management per codebase
│   ├── ProcessManager.ts        # Spawns claude CLI via node-pty
│   ├── GitManager.ts            # Diffs, file trees, file editing, revert
│   ├── FileWatcher.ts           # Polling-based (avoids EMFILE on large repos)
│   ├── EnvStore.ts              # Per-project env var persistence (JSON)
│   ├── ShellManager.ts          # Multiple shell PTYs per codebase
│   ├── ipc-handlers.ts          # All IPC handler registrations
│   ├── store.ts                 # Persistent codebase storage
│   └── mcp/
│       ├── McpServer.ts         # HTTP JSON API for tool calls
│       └── mcp-config.ts        # Generates bridge script + .mcp.json
│
├── renderer/                    # React frontend
│   ├── App.tsx                  # Root — routing between views
│   ├── components/
│   │   ├── Sidebar.tsx          # Codebase list + orchestrator button
│   │   ├── CodebaseView.tsx     # Main workspace (explorer + diff + tabbed terminals)
│   │   ├── OrchestratorView.tsx # Orchestrator dashboard + terminal
│   │   ├── Terminal.tsx         # xterm.js with PTY integration (Claude sessions)
│   │   ├── ShellTerminal.tsx    # xterm.js wrapper for shell PTYs
│   │   ├── DiffView.tsx         # Unified/split diff with syntax highlighting
│   │   ├── FileTree.tsx         # Recursive git-aware file explorer
│   │   ├── FilePreview.tsx      # File editor with line numbers + Cmd+S save
│   │   ├── EnvPanel.tsx         # Vercel-style env var key-value editor
│   │   ├── StatusIndicator.tsx  # Animated status dots
│   │   ├── AddCodebaseDialog.tsx
│   │   └── EmptyState.tsx
│   ├── hooks/
│   │   ├── useSession.ts       # Session start/stop/state
│   │   ├── useDiff.ts          # Git diff fetching
│   │   ├── useFileTree.ts      # File tree fetching
│   │   └── useIPC.ts           # Real-time IPC event subscriptions
│   ├── stores/appStore.ts      # Zustand — all UI state
│   └── styles/globals.css      # Dark theme + xterm + diff2html overrides
│
├── shared/types.ts              # TypeScript interfaces shared across processes
└── preload/index.ts             # Secure IPC bridge (context isolation)

Development

npm run dev          # Dev server with hot reload
npm run build        # Production build
npm run package      # DMG (macOS) / AppImage (Linux)
npm run rebuild      # Rebuild node-pty for your platform

Contributing

PRs are welcome. The codebase is small enough to read in an afternoon.

If you're adding a new MCP tool for the orchestrator:

  1. Add the tool definition to TOOLS array in src/main/mcp/McpServer.ts
  2. Add the handler in the handleToolCall switch statement
  3. That's it — the bridge script picks up tools dynamically

License

AGPL-3.0

About

Desktop command center for managing multiple Claude Code sessions across codebases. Multi-agent orchestration via MCP.

Resources

Readme

License

AGPL-3.0 license
Activity

Stars

14 stars

Watchers

0 watching

Forks

2 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages