code-commander

<p align="center"> <h1 align="center">Code Commander</h1> <p align="center"> <strong>See what your AI agents are actually doing.<br/>Run multiple coding agent sessions. Watch every file change in real time. One orchestrator to coordinate them all.</strong> </p> <p align="center"> <a href="#the-problem">The Problem</a> · <a href="#how-it-works">How It Works</a> · <a href="#orchestrator">Orchestrator</a> · <a href="#getting-started">Getting Started</a> · <a href="#architecture">Architecture</a> </p> <p align="center"> <a href="https://github.com/Dominien/code-commander/stargazers"><img src="https://img.shields.io/github/stars/Dominien/code-commander?style=flat&color=58a6ff" alt="Stars"></a> <a href="https://github.com/Dominien/code-commander/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-AGPL--3.0-blue?style=flat" alt="License"></a> <a href="https://github.com/Dominien/code-commander/releases"><img src="https://img.shields.io/badge/platform-macOS%20%7C%20Linux-lightgrey?style=flat" alt="Platform"></a> </p> </p> <br/> <!-- TODO: replace with actual screenshot or demo GIF --> <!-- <p align="center"><img src="docs/demo.gif" width="900" /></p> --> ## The Problem You run your coding agent 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. <br/> ## How It Works ```mermaid graph LR subgraph Commander["Code Commander"] direction TB SB["Sidebar<br/>All your projects"] TERM["Tabbed Terminals<br/>Agent + 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 ``` ### 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 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 agent 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 the agent Each project gets a **tabbed terminal area**. The agent 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. <br/> ## Orchestrator Once you're running multiple sessions, you'll want one agent that can see everything. The orchestrator is a dedicated agent session with MCP tools that give it control over every other session. ```mermaid 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 ``` Click the orchestrator icon at the top of the sidebar. It launches with permission bypass flags 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 an agent 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 | <br/> ## Getting Started ```bash git clone https://github.com/Dominien/code-commander.git cd code-commander npm install npm run dev ``` **Prerequisites** - Node.js 20+ - A CLI-based AI coding agent installed and in your PATH - Git <br/> ## Architecture ```mermaid 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 → agent 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 → agent CLI"] SC3 --- PTY3["node-pty → agent CLI"] ORC --- PTY4["node-pty → agent 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 ``` ### Why a stdio bridge? Most CLI agents' MCP implementations only support servers spawned via `command`/`args` (stdio transport). They don't support connecting directly to HTTP/SSE endpoints. So the orchestrator's MCP tools work through a bridge: ```mermaid sequenceDiagram participant CC as Orchestrator<br/>(Agent CLI) 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 ``` The bridge script is generated at runtime with the correct port and `NODE_PATH` baked in. <br/> ## 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 | <br/> ## Project Structure ``` src/ ├── main/ # Electron main process │ ├── CodebaseManager.ts # Codebase + orchestrator lifecycle │ ├── SessionController.ts # PTY session management per codebase │ ├── ProcessManager.ts # Spawns agent 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 (agent 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) ``` <br/> ## Development ```bash 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 ``` <br/> ## 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 <br/> ## License [AGPL-3.0](LICENSE)