┏━┓┏━╸┏━╸┏┓╻╺┳╸┏━┓
┣━┫┃╺┓┣╸ ┃┗┫ ┃ ┗━┓
╹ ╹┗━┛┗━╸╹ ╹ ╹ ┗━┛
┏━╸┏━┓┏┳┓┏┳┓┏━┓┏┓╻╺┳┓┏━╸┏━┓
┃  ┃ ┃┃┃┃┃┃┃┣━┫┃┗┫ ┃┃┣╸ ┣┳┛
┗━╸┗━┛╹ ╹╹ ╹╹ ╹╹ ╹╺┻┛┗━╸╹┗╸

Multi-panel terminal for AI agents that talk to each other.
Run Claude, Codex, and Gemini side by side. Make them talk to each other.

Install • Demo • Features • Agent-to-Agent • Shortcuts • Config • Docs • Contributing

---

What if your AI agents could collaborate?

You tell Claude to analyze code. Claude finds bugs. Claude asks Codex to write the tests. Codex finishes and sends results back to Claude. You watch it happen in real-time, in split panels, in your terminal.

That's Agents Commander.

Quick Start

This README describes Agents Commander 0.1.10, under the MIT License. Use Node.js 22+, Python 3, and macOS, Linux, or WSL2. The bulk-launch workflow, bulk protocol setup, sequenced protocol replay protection and subsequent QA hardening are included in 0.1.6, not 0.1.5. See the QA coverage and remaining manual checks when validating a checkout. Version 0.1.7 fixes unresponsive startup from large directory trees and missing installed prompt templates; the 0.1.6 collaboration features remain unchanged. Version 0.1.8 fixes folder-navigation and modal-focus races found by deeper release QA, repairs delayed protocol detection after terminal-row redraws, and adds packaged 100-panel / 20-agent stress checks. Version 0.1.9 fixes collaboration-template panel addressing and missing error feedback, and teaches exact routing addresses for model-labelled profiles. Registry publication is a separate step; check the npm version listing before installing, or build the current source below.

Version 0.1.10 additionally fixes resize-dependent protocol detection and OpenCode sidebar contamination. These fixes are not part of 0.1.9. For OpenCode, an unrecognized or partially painted layout pauses routing with Protocol waiting for OpenCode layout; it never guesses which text to send. See the redraw QA and limitations.

Install version 0.1.10

npm install -g agents-commander@0.1.10
agents-commander --version
agents-commander --doctor .
agents-commander .

Try the deterministic offline demo without agent accounts or API credentials:

agents-commander --demo

Check --version after upgrading so an older installation on your PATH does not shadow the selected version. Package versions are listed on npm. Quit the old Commander process and start a fresh one after upgrading; an already-running process does not load the new code.

Unresponsive startup or missing templates

Version 0.1.6 could exhaust file descriptors while recursively watching a large home/project tree, making keyboard input appear unresponsive. Version 0.1.7 uses one shallow native watch per distinct file-panel directory, at most 100, and updates that set as panels navigate, close, or become terminals. It does not recursively scan descendants. Successful notifications are not logged, avoiding feedback from Commander's own log writes. A failed watch stops instead of retrying on every refresh; a one-time warning directs you to Ctrl+R from a file panel for manual refresh.

The separate installed-template lookup bug could show 0 templates even when Doctor found 121. Version 0.1.7 resolves the library from the running package, including flat dist chunks, rather than falling back to your working directory.

After upgrading and restarting, check --version, dismiss Welcome with Space, then try Tab, F2 and Ctrl+B. On macOS, F-keys may require Fn; the footer's numbers refer to function keys, not the number row. Node.js 22+ and Python 3 remain required. Node.js 20 is unsupported, but was not established as the cause of the reproduced watcher freeze. See QA evidence.

Version 0.1.8 also keeps automatic refresh from cancelling an in-flight folder change. While the Markdown editor loads a slow file, Esc or Ctrl+Q cancels without sending keys to the underlying panel. A background Vim exit no longer steals keyboard focus from an open dialog; closing that dialog returns focus to the replacement file panel.

If a complete protocol block becomes deliverable only after adding panels or resizing, update to 0.1.8: it repairs stale soft-wrap boundaries after full-row terminal erases. A matching synthetic redraw now reaches the first scheduled scan (50 ms with default settings), without additional user input. This is local detection latency, not a guarantee of provider response time.

Current source version

Use Node.js 22+ and build the desired source checkout:

git clone https://github.com/lech-kalinowski/agents-commander.git
cd agents-commander
npm install
npm run build
node dist/bin/agents-commander.js --doctor .
node dist/bin/agents-commander.js .

If you already have this source checkout, skip cloning. Run the commands from the checkout; replace . with your project directory. The source examples below use the built entrypoint so an older global installation cannot shadow it. npm start -- <options> <directory> is an equivalent source launch command. Cloning checks out main; features in an open pull request require that PR's branch. Check git branch --show-current and rebuild after switching branches.

--doctor checks the runtime, PTY bridge, packaged assets, and working directory before the TUI starts. Commander is a local terminal application; the website is a landing page, not a browser-hosted Commander interface.

For a source QA pass, run npm ci followed by npm run verify. This includes synthetic multi-agent terminal tests, offline hardware fixtures, build/watch checks, and a packed-install smoke test. It does not call paid providers or prove that a physical controller or a particular model is ready.

Upgrading from 0.1.4

Version 0.1.4 advertised Node.js 18+; 0.1.10 requires Node.js 22+ and Python 3, as did 0.1.5–0.1.9. Upgrade Node before installing 0.1.10. The older package supported only --theme, --panels (2, 3, or 4), and --show-hidden, plus help/version. The doctor, conference/demo modes, adaptive density, 100-panel workspace, OpenCode adapter, Codex Micro integration, and capture/dataset commands described here arrived in 0.1.5 and remain in 0.1.10, not 0.1.4. Bulk launch, bulk protocol setup and sequenced replay protection were added in 0.1.6.

Panel controls have also changed: F4 toggles fullscreen, F6 clones a fresh agent panel, F7 reorders panels, and F9 closes a panel. File copy/move/delete remain available from file panels with Shift+F6/Shift+F7/Shift+F9. See the keyboard shortcuts before upgrading a familiar workflow.

---

The Problem

You have Claude Code, Codex CLI, Gemini CLI. All powerful. All isolated. You copy-paste between them like it's 2005.

Agents Commander puts them in one terminal, side by side, and lets them talk to each other.

Requirements

For version 0.1.10:

• Node.js 22 or newer
• Python 3 (used by the PTY bridge)
• macOS, Linux, or WSL2
• For live AI sessions: Claude Code, Codex CLI, Gemini CLI, or OpenCode. The supported Shell adapter can launch a local interactive shell or a configured command.

The deterministic offline demo does not require an AI agent CLI, API credentials, or network access.

Demo

Use the presentation-safe preset with live agent CLIs:

node dist/bin/agents-commander.js --conference .

Conference Mode uses the midnight theme, starts with two panels, hides dotfiles, and skips the welcome dialog. To rehearse without external services, launch the bundled deterministic demo:

node dist/bin/agents-commander.js --demo

Demo Mode creates a temporary seeded workspace, applies the Conference Mode defaults, and offers to launch two bundled local demo roles. The workspace is cleaned up when Commander exits. The compact sketch below omits the demo session's capability suffix from protocol markers.

+---------------------------+---------------------------+
| Panel 1: Demo Coordinator | Panel 2: Demo Reviewer    |
| Seeded workspace ready.   | Waiting for coordinator.  |
|                           |                           |
| ===COMMANDER:SEND:        | [From Demo Coordinator]   |
| generic:2===              | Review brief.md; total?   |
| Review brief.md. Confirm  |                           |
| total=42.                 | STATUS: seeded total 42.  |
| ===COMMANDER:END===       |                           |
|                           | ===COMMANDER:REPLY===     |
| ACK msg=m1 thread=t1      | Deterministic review     |
|                           | passed: total=42.         |
|                           | ===COMMANDER:END===       |
|                           |                           |
+---------------------------+---------------------------+
 F1Help F2Agent F3+Panel F4Full F5Edit F6Clone F7Order F8Mkdir F9Close F10Quit

Features

Multi-Agent Terminal

Keep up to 100 active panels in one workspace. A panel can be a file browser or a PTY-backed agent terminal with ANSI/xterm-256color rendering for common interactive CLI output. Type directly into any agent -- keystrokes are forwarded in real-time.

The workspace size and the visible layout are separate:

• --panels <1-100> chooses how many active panels exist when Commander starts.
• --density auto|2|3|4 chooses how many panels can be visible on one page. auto fits as many readable panels as the window allows; 2, 3, and 4 set a manual cap.
• Shift+F4 reliably cycles auto / 2 / 3 / 4 density without creating, removing, or restarting panels. Ctrl+0, Ctrl+2, Ctrl+3, and Ctrl+4 remain direct aliases on terminals that emit those combinations distinctly.
• Tab moves through every active panel and brings its page into view. Terminal sessions on hidden pages keep running.
• F4 expands the active panel to fullscreen; press F4 again (Back in the function bar) to restore the grid. The configured density and running sessions are preserved.
• F6 opens a new panel at the active panel's working directory and launches a fresh instance of the same agent profile when it has one. It does not copy files. Conversations, terminal buffers, running process state, and protocol capability keys are not copied.
• F7 changes a panel's workspace position. F9 closes the active panel, with confirmation before stopping a live session; it never deletes files.

For example, this creates a 12-panel workspace while showing no more than four panels at once:

node dist/bin/agents-commander.js --panels 12 --density 4 .

Protocol panel IDs (P1, P2, and so on) are stable for the lifetime of the workspace, independently of workspace order. Moving Panel 3 to position 1 with F7 does not change its P3 route; removing Panel 2 does not renumber Panel 3. Gaps are normal. Newly added or cloned panels receive new IDs; Ctrl+E is the explicit reset to fresh Panels 1 and 2.

Cloning a managed agent keeps its configured profile (including its configured model), but starts a separate session. Press Ctrl+P in that new agent to enable its own Commander Protocol session. An unmanaged command, such as Vim, is not replayed: its clone is an idle terminal at the same directory. The bundled scripted demo roles cannot be cloned; use F3 and F2 to launch an independent agent instead.

Supported adapters:

• Claude Code (Anthropic)
• Codex CLI (OpenAI)
• Gemini CLI (Google)
• OpenCode (multi-provider, including custom provider/model profiles)
• Shell (a generic local shell or configured command)

The selector also catalogues five future presets that are not launchable yet: Aider, Cline, Goose, Kiro, and Amp.

Launch one profile in many new panels

Available in 0.1.6, not 0.1.5. Run agents-commander . from that version, or use npm start after building the source checkout with npm run build.

1. Focus the panel whose working directory the new sessions should use.
2. Press F2 and select the desired CLI/profile, such as your prepared APEX/Pi profile.
3. Press N for new-panel batch mode, type 16 (or 10, 20, or another count within the displayed capacity), then press Enter.
4. Review the same-profile/directory and provider-usage confirmation. No is selected by default; approve only the intended launch.

This adds the requested number of new terminal panels. Two existing panels plus a batch of 16 means 18 total panels, not 16. Existing file panels, running agents, idle terminals, and their stable P IDs remain unchanged. Capacity is bounded by the 100-active-panel limit and remaining stable IDs. Without N, F2 retains its existing single-target launch behavior.

Launches are scheduled one at a time. Esc in the progress dialog stops the remaining launches; already-started sessions are kept. A launch failure stops the batch and leaves its terminal available for inspection. Starting a process does not prove that its CLI, authentication, or provider is ready; check the terminal output and use F11 to inspect sessions, including hidden panels. Bulk launch does not send a task, bootstrap the protocol, or enable recording. Use F2 → P for explicit bulk protocol setup after checking the agents are ready, or Ctrl+P for the active agent only.

Every new session uses the same selected profile, arguments, environment, and working directory. These are independent Commander sessions/processes, not isolated worktrees: they can access the same files. Configured resume or startup arguments may reuse provider-side conversation state or perform work; review them first. Starting many CLIs can incur provider usage and local resource costs.

Repeating an APEX/Pi role profile sixteen times does not create the sixteen-role review council below. Its generated profiles contain different missions and fixed P-number expectations; launch each intended role at the matching stable panel instead of cloning one role's prompt across the council.

Enable protocol in many agents

F2 → P is available in 0.1.6, not 0.1.5. Run the selected version or build this checkout with npm run build and run npm start.

1. Launch your agents (for example, 16 copies of an APEX/Pi profile with F2/N). Finish login and permission prompts in each, and leave every selected CLI at an empty, ready input prompt. A running process does not prove readiness.
2. Press F2, then P for protocol setup. No launch profile is selected.
3. Use Up/Down and Space to select panels, or A for all eligible sessions. N clears selection; mouse clicks toggle rows. Hidden panels are included using their stable P numbers. Nothing is selected initially.
4. Press Enter, review the selection, then explicitly confirm Yes. The confirmation defaults to No; model usage may incur provider charges.
5. Watch submitted/already-enabled/failed counts. Esc stops remaining injections; a started paste/submit settles, and completed injections stay.
6. Inspect the agents' responses, then send your collaboration task separately through Ctrl+O or a template. Submission does not prove model compliance.

Each session receives its own private capability, never a shared broadcast key. Already-enabled sessions are skipped without rotating their keys. A stopped, removed, or replaced session fails its original selection; its new process is never silently armed. Other selected sessions can still complete. Reopen F2/P to retry after inspecting failed panels. The built-in generic Shell, unmanaged commands and internal demo roles are excluded. For Pi/APEX use a configured named agent profile; do not select a shell wrapper unless it is actually at the agent's input prompt.

This action does not launch/replace agents, assign roles, submit a collaboration task, or enable recording. Ctrl+P remains active-only and deliberately reinjects with a fresh key; use it if you need to refresh an armed session.

Sixteen-panel APEX collaboration example

The APEX review council prepares sixteen named Pi or OpenCode profiles: one coordinator and fifteen specialists reviewing a fictional booking API in seven human-gated waves. It includes an offline setup generator, role prompts, a runbook, and a 15-SEND/15-REPLY evidence checklist. Supply the exact APEX model and the provider setup for your chosen harness; no provider identity or live-model compatibility is assumed. Preparation does not launch agents or change your saved configuration. This is a source-checkout example, not the two-agent scripted --demo or a verified APEX benchmark.

The Pi guide also provides a configurable --max-tokens output ceiling and a separate three-panel broadcast test (--scenario broadcast-test), with one sender and two receivers that print local receipts. Both Pi scenarios default to a tested 131,072-token request ceiling and a 245,760-token local context allowance; --context-window is configurable too. Run the broadcast test in a fresh Commander instance: broadcasts reach all connected agents, including hidden panels. Preparation and offline tests do not establish a successful live model run. The Pi setup guide includes private credential loading, profile registration and a live model smoke command.

Integrated File Manager

A file manager built into every file panel. Browse, copy (Shift+F6), move or rename (Shift+F7), and delete (Shift+F9) files without leaving the tool. These file operations only apply to file panels; unmodified F6, F7, and F9 control panels. Toggle between file panels and agent terminals with Ctrl+T.

Inter-Agent Communication

The killer feature. Agents can autonomously send tasks to each other using a lightweight protocol. Routing uses local output markers instead of a separate orchestration API or SDK.

Built-in Editor

Preview regular UTF-8 text files with line numbers using Enter from a file panel, edit them in the built-in text editor with F5, or open the selected file in Vim with Ctrl+G.

Themes

Choose between the built-in classic-blue and midnight themes through the CLI or configuration file.

Inter-Agent Communication

This is what makes Agents Commander different from running tmux with multiple agents.

How it works

1. Launch agents in different panels (F2)
2. Send protocol instructions to each running agent (Ctrl+P), or use F2 → P for selected/all agents in 0.1.6 -- each session receives its own instructions and key
3. Give a task that requires collaboration:

"Analyze this codebase for security issues, then ask Codex in Panel 2
to fix every vulnerability you find."

4. Watch it happen. Claude analyzes, finds issues, sends them to Codex. Codex fixes, reports back.

Choose the actual panel address

A SEND address combines the CLI adapter and the stable P ID. It is not the model name, grid position, or the second instance of an agent. For example, if P2 runs OpenCode with APEX and P4 runs Codex, use opencode:2 and codex:4. apex:2 is not a supported address; codex:2 must not replace OpenCode in P2. APEX through a generic/Pi profile uses generic:<P ID>.

Version 0.1.9 supplies explicit addresses during protocol injection and QUERY agents. Refresh the roster when panels change. Authenticated, complete SEND frames with an unknown short type return a CommanderError; mismatched known types return a failed ACK. Nothing is silently redirected or replaced. Read the feedback, verify the intended recipient, then use a new counter for a corrected message. Repainting the old frame does not retry it. Malformed, unauthorized, oversized, or replayed frames can remain inert without feedback.

The Protocol

Five commands, one session-bound routing capability. Ctrl+P generates a fresh private capability for that agent session and teaches the agent the exact marker format. Static or copied markers without the current capability are inert. In the examples below, <session-key> stands for the value injected into the agent.

Version 0.1.6 adds a sequence suffix (not in 0.1.5). Each agent starts its own counter at 1 after protocol injection and increments it for every new command across all five verbs. Replace <N> below with that number; the header and footer must contain the same key and number. A redraw keeps the original number. An intentionally repeated action, even with identical text, needs a new number. Ctrl+P and F2 → P teach this format automatically.

SEND -- direct message to a specific agent:

===COMMANDER:SEND:codex:2:<session-key>:<N>===
Please write unit tests for the auth module.
===COMMANDER:END:<session-key>:<N>===

REPLY -- continue your latest open reply thread (no panel number needed):

===COMMANDER:REPLY:<session-key>:<N>===
Tests written. 12 passing, 0 failing.
===COMMANDER:END:<session-key>:<N>===

Commander claims the newest open reply window and resolves its return session. A successful delivery consumes that window; a failed delivery can restore it if the route is still valid. This is not a permanent "last sender" address.

BROADCAST -- send to every other connected agent at once:

===COMMANDER:BROADCAST:<session-key>:<N>===
Phase 1 complete. All agents: begin phase 2.
===COMMANDER:END:<session-key>:<N>===

STATUS -- report progress (shown as a toast in Commander UI, not sent to agents):

===COMMANDER:STATUS:<session-key>:<N>===
Analyzing file 5 of 10...
===COMMANDER:END:<session-key>:<N>===

QUERY -- ask Commander what agents are running:

===COMMANDER:QUERY:<session-key>:<N>===
agents
===COMMANDER:END:<session-key>:<N>===

Commander's ProtocolScanner watches agent output in real-time, strips ANSI codes, detects these markers across streaming chunks, and routes a message only when its capability matches the currently armed session. The target agent sees:

[From Claude Code in Panel 1 | thread=t1 | msg=m1]: Please write unit tests for the auth module...

After delivery, the sender gets an ACK:

[Commander ACK] status=delivered msg=m1 thread=t1 target="Codex CLI" panel=2

delivered means the input was submitted to the target PTY; it does not mean the model accepted the task or completed it. Failed deliveries return status=failed with an error. BROADCAST's ACK reports queue admission only; subsequent per-target delivery outcomes appear in F12 Activity. STATUS returns a local kind=status status=accepted ACK.

Routing is bidirectional between connected supported sessions.

Redraws, repeated actions, and compatibility

Terminal history can reappear after scrolling, fullscreen changes, or a resize. The 0.1.6 replay guard retains command identities across these changes; a previously seen sequence cannot become a new action because its body, wrapping, destination, or verb changes. Recognized outgoing instruction/prompt echoes stay suppressed rather than becoming agent-authored output after repeated redraws.

• Sequences are positive decimal integers from 1 to 9007199254740991, without leading zeros. One counter covers all five verbs for the current capability.
• Each capability has a 4,096-number sliding replay window. Unseen numbers within that window may arrive out of order; duplicates and older numbers are rejected. This is local replay suppression, not exactly-once delivery or proof that a model completed a task. A suppressed frame may have no ACK.
• Capability-only markers without :<N> remain compatible, but an identical command fingerprint is allowed only once until the agent process or its explicitly armed capability changes. If a CLI rewrites hard line breaks, unsequenced text can be ambiguous. Use sequences for new workflows and for intentionally repeated identical actions.
• Replay storage is bounded: up to 4,096 legacy fingerprints and eight sequence-capability scopes. Exhaustion blocks further outgoing protocol processing and is shown in the panel header; restarting the agent clears it. Resizing or toggling fullscreen does not reset replay history. Explicit Ctrl+P also resets it by arming a fresh capability and counter; old-key output then remains inert. Finish any current input before reinjecting, and inspect prior deliveries before retrying an uncertain task. F2 → P skips already-armed sessions and does not rotate their keys.

Activity, diagnostics, and recording limits

• F12 shows SEND, REPLY, and BROADCAST delivery attempts from an in-memory ledger, not a persistent archive. Default retention is up to 1,000 records / 8 MiB of content, with a 256 KiB per-record content cap; the dialog shows the latest 100 summaries. Evicted records and history are not restored on restart.
• STATUS and QUERY are not retained in Activity; opt-in capture records them.
• Ctrl+L from a file panel opens the diagnostic log at ~/.agents-commander/debug.log. It rotates at 1 MiB with one backup. Routed payloads are represented by metadata and byte counts, not complete message bodies. Diagnostics can still contain names and error details; review them before sharing.
• Opt-in semantic recording and reviewed dataset export are included in 0.1.6 (introduced in 0.1.5). Nothing is recorded by default. Full terminal transcripts, session restore, replay and model training are not implemented. The original design plan retains the broader proposed scope and implementation boundaries.

Create a Commander Protocol training dataset

# Source build, Node.js 22+. Reuse an opaque ID across related project runs.
npm start -- --capture protocol --capture-project project-01 /path/to/project

# Arm each agent with Ctrl+P; submit tasks via Ctrl+O; exit with F10.
# The launch prints the private capture directory.
npm start -- dataset inspect /path/to/capture-uuid
npm start -- dataset prepare /path/to/capture-uuid --out ~/commander-review-01

# Review candidates and explicitly approve quality, context, privacy and rights.
# Edit review.json; decisions start unapproved.
npm start -- dataset export ~/commander-review-01 --out ~/commander-dataset-01 --seed experiment-01
npm start -- dataset validate ~/commander-dataset-01

Exports use conversational prompt / completion JSONL for LoRA/SFT. Audit metadata is separate; real and synthetic examples stay separate; whole project families and detected duplicates stay in one split. Missing/manual-input context and incomplete captures are not silently promoted to training examples. Redaction is best-effort and human review is mandatory. No automatic training or uploads occur. See the dataset guide for schemas, review steps, limitations and the model-specific training gate.

Manual Orchestration

Don't want to wait for agents to figure it out? Press Ctrl+O to manually send a task to any agent in any panel. Commander handles launching, initialization, and delivery.

Choose the target by its stable P-number. A running session with the same profile receives the task directly; a different running profile requires a Replace Session confirmation. To run agents side by side, choose an empty panel instead. In Yes/No dialogs, Left/Up selects Yes, Right/Down selects No, Tab/Shift+Tab switches choices, and Enter accepts. You can also click a choice, press Y/N, or cancel with Escape. No is selected by default. Hardware-only approvals still require the device; terminal input cannot approve them.

Prompt Template Library

121 built-in prompt templates across 14 categories, from multi-agent collaboration workflows to single-agent tasks like security audits, testing, debugging, and architecture reviews.

How to use

1. Press Ctrl+B to open the template browser
2. Browse categories with Up/Down arrows -- the preview pane on the right shows full details
3. Press Enter to select a template
4. Pick a live target panel by its stable panel number and press Enter to confirm
5. Ordinary templates can launch an agent automatically. Collaboration templates first require a running agent armed with Ctrl+P; Commander then binds their protocol examples to that session before sending.

Version 0.1.9 also attaches a fresh roster immediately before submitting a collaboration template. Built-in role placeholders such as <codex-panel> refer to another running agent of that adapter type, not a fixed panel number. For example, Philosophical Debate launched from Claude in P3 targets the unique Codex peer in P4. Missing or ambiguous peers require a user choice; this is model guidance, not an automatic router remap. Custom template bodies and explicit targets are preserved. Finish current CLI input before submitting a template.

Categories

Category	Templates	Description
Collaboration	29	Multi-agent workflows using Commander protocol (code review, security audit, TDD, broadcast kickoff, reply chains, etc.)
Testing	12	Unit tests, integration tests, E2E, property-based, mutation testing, load testing, accessibility
Security	10	OWASP top 10, dependency scanning, secrets detection, auth review, cryptography, compliance
Code Quality	10	Code smells, complexity, SOLID, DRY, error handling, tech debt, type safety
Architecture	8	Design patterns, microservices, event-driven, scalability, resilience, state management
Debugging	8	Root cause analysis, memory leaks, race conditions, flaky tests, performance profiling
DevOps	8	CI/CD, Dockerfiles, IaC, monitoring, deployment strategies, GitHub Actions
Frontend	8	Responsive design, components, web performance, CSS, forms, i18n, PWA
Backend	6	REST APIs, query optimization, caching, background jobs, webhooks, rate limiting
Learning	6	Code walkthroughs, pattern recognition, idioms, concept explainers, best practices
Data	4	Schema design, migrations, GraphQL, data validation
Documentation	4	API docs, onboarding guides, ADRs, changelogs
Project	4	Feature breakdown, tech spikes, release readiness, retrospectives
Single Agent	4	Codebase analysis, performance optimization, explain and document, migration assistant

Custom templates

Create your own templates in ~/.agents-commander/templates/. Each template is a .md file with simple YAML-like frontmatter:

---
name: My Custom Template
description: One-line description shown in the browser
category: my-category
agents: [any]
panels: 1
---
Your prompt content here. This is what gets sent to the agent.

You can include multiple paragraphs, markdown formatting,
numbered steps, or any other text.

Frontmatter fields:

Field	Default	Description
name	Filename without .md	Display name in the template browser
description	Empty	One-line description shown in the preview
category	other	Category for grouping (e.g., testing, security, or your own)
agents	[any]	Recommended agents: [any], [claude], [claude, codex], etc.
panels	1	Recommended number of active panels from 1 to 100

All metadata fields are optional. The lightweight parser supports the scalar and bracketed-list forms shown above; it is not a full YAML parser.

User templates override built-in templates with the same filename. Templates are reloaded each time you open the browser (Ctrl+B).

Example Workflows

Code Review Pipeline

Panel 1 (Claude):  "Review src/ for bugs"
        Claude finds issues  -->  sends to Codex
Panel 2 (Codex):   Receives issues, writes fixes
        Codex finishes  -->  sends results back to Claude
Panel 1 (Claude):  Verifies fixes, reports summary

Multi-Perspective Security Audit

Panel 1 (Claude):  Architecture review
Panel 2 (Gemini):  Security analysis
Panel 3 (Codex):   Writes patches based on both reviews

Divide and Conquer

"Split this refactor: send backend changes to Codex in Panel 2,
frontend changes to Gemini in Panel 3, and write integration
tests yourself."

Keyboard Shortcuts

Function Keys

Key	Action
F1	Help
F2	Launch Agent
F3	Add Panel
F4	Fullscreen active panel / restore grid (Full / Back)
F5	Edit File
F6	Clone panel at the same directory and start a fresh instance of the same agent profile
F7	Change panel workspace position; keep its protocol ID
F8	Create Directory
F9	Close panel; confirm before stopping a live session
F10	Quit

Navigation

Key	Action
Tab	Switch to the next active panel and bring its page into view
F11	Search and jump to any panel by number, path, agent, model, or status
Up/Down	Move cursor / scroll
Enter	Open directory or file
Backspace	Parent directory
Home/End	Jump to first/last
PgUp/PgDn	Scroll page
Insert	Select/deselect file

Agent Management

These shortcuts work everywhere, including on terminal panels with running agents:

Key	Action
Ctrl+B	Browse prompt template library
Ctrl+O	Orchestrate -- send task to any agent
Ctrl+P	Send protocol instructions to the active agent
F2 then P	Select/all running agents for bulk protocol setup (added in 0.1.6)
Ctrl+T	Toggle panel: file <-> terminal
Ctrl+K	Kill running session on active panel
Ctrl+W	Close active panel (same as F9)
Ctrl+C	Send interrupt to agent
Ctrl+D	Send EOF to agent

Layout & System

These are global application shortcuts:

Key	Action
Shift+F4	Cycle automatic, 2-, 3-, and 4-panel visible density
Ctrl+0/2/3/4	Terminal-dependent direct density aliases
F12	Routed-message Activity
Shift+F12	Inter-agent protocol guide

Layout density only changes what is visible. It does not add, remove, renumber, or restart panels. Use F3 to add, F6 to clone, F7 to reorder, and F9 or Ctrl+W to close the active panel. F4 toggles fullscreen and Tab moves across pages.

These file operations are available only from file panels:

Key	Action
Enter	Open directory / preview selected file
F5	Edit selected file
Shift+F6	Copy selected files
Shift+F7	Move / rename selected files
F8	Create directory
Shift+F9	Delete selected files (with confirmation)

These are file-panel actions. On terminal panels they pass through to the running agent, so switch to a file panel with Tab first:

Key	Action
Ctrl+E	Reset to default 2-panel view
Ctrl+G	Edit selected file in Vim
Ctrl+H	Toggle hidden files
Ctrl+R	Refresh all panels
Ctrl+L	View application logs

Codex Micro controls (experimental)

Agents Commander can read the shipping Codex Micro controls directly over USB or Bluetooth on macOS. The native bridge is bundled, uses Python 3 and the device's vendor-HID channel, and does not require reprogramming the factory layer in Work Louder Input. The integration remains opt-in; native input is the default mode after it is enabled.

Native mode uses a sole-reader conflict guard. Before accepting each event, it checks that no other active direct HID reader is attached. If ChatGPT Desktop, Work Louder Input, or another client is reading the device, Commander shows MICRO:BUSY and discards its input. This is an observational safety guard, not an OS-enforced exclusive lock. Fully quit ChatGPT Desktop before starting Commander. You can instead disable ChatGPT under System Settings > Privacy & Security > Input Monitoring, restart ChatGPT, leave that permission enabled for the terminal that launches Commander, and confirm that Doctor passes. Do not use sudo. On the tested firmware 0.4.1, selecting Layer 2 did not isolate the vendor events: another active client still received the same physical press.

Physical control	Agents Commander action
Agent keys 1–6 (AG00–AG05)	Focus active workspace slots 1–6
Fast (ACT06)	Cycle visible panel density
Approve (ACT07)	Guarded one-time approval when decision controls are enabled
Reject (ACT08)	Guarded rejection when decision controls are enabled
Split (ACT09)	Add a panel
Wide Mic key (ACT10 + ACT11)	Open routed-message Activity
Codex (ACT12)	Open the panel navigator
Dial counter-clockwise / clockwise	Focus previous / next panel
Dial press	Open routed-message Activity
Joystick up / down	Previous / next panel page
Joystick left / right	Focus previous / next panel

The names above describe the factory keycap arrangement. The keycaps are swappable; Commander routes the fixed AG00–AG05 and ACT06–ACT12 positions, regardless of which cap is installed.

First allow your terminal application in System Settings > Privacy & Security > Input Monitoring, then verify the connection:

node dist/bin/agents-commander.js --doctor --codex-micro .
node dist/bin/agents-commander.js --codex-micro-test .

For normal opt-in operation:

node dist/bin/agents-commander.js --codex-micro .

Guarded Approve and Reject controls are disabled by default. Enable them explicitly only for a rehearsed session:

node dist/bin/agents-commander.js --codex-micro --codex-micro-decisions .

--codex-micro-test enables the controls for that run and opens the physical-input checklist. --no-codex-micro explicitly disables them. --conference and --demo do not enable Codex Micro automatically. Approval and rejection remain human-confirmed, fail-closed operations: a first press opens a five-second window, the same decision key confirms, and submission occurs only while the active session is Codex and the selected prompt still matches the requested one-time action. They never choose a persistent "always allow" option.

Native device input currently requires macOS. On Linux, or for a controller layer already programmed with the reserved shortcuts, use --codex-micro-keyboard as the legacy fallback. That fallback cannot run the sole-reader guard or decision controls, so keep ChatGPT Desktop fully quit for the entire keyboard-mode session. For the stage, prefer a wired USB-C connection, ensure MICRO:BUSY is not displayed, and keep a conventional keyboard available. The bridge reads controls and safe device status only; it does not read or store device serial numbers, update firmware, or control RGB lighting. See Codex Micro setup and rehearsal.

Configuration

Create ~/.agents-commander/config.json:

{
  "theme": "midnight",
  "panelCount": 2,
  "panelDensity": "auto",
  "showHidden": false,
  "sortBy": "name",
  "sortAscending": true,
  "watchDebounce": 300,
  "editor": {
    "tabSize": 2,
    "wordWrap": true
  },
  "hardware": {
    "codexMicro": {
      "enabled": false,
      "inputMode": "native",
      "decisionControls": false
    }
  },
  "agents": {
    "claude": {
      "command": "claude",
      "args": [],
      "env": {}
    }
  },
  "agentProfiles": [
    {
      "id": "local-reviewer",
      "label": "Local Reviewer",
      "adapter": "opencode",
      "model": "provider/model-name",
      "agent": "reviewer",
      "configPath": "/absolute/path/to/opencode.json"
    }
  ]
}

panelCount is the initial active workspace size (1 to 100), matching --panels. panelDensity is the visible-page policy ("auto", 2, 3, or 4), matching --density. The two settings are independent.

hardware.codexMicro.enabled opts into the control surface. hardware.codexMicro.inputMode is "native" by default; set it to "keyboard" only for a Work Louder Input layer programmed with the legacy shortcuts. hardware.codexMicro.decisionControls separately enables guarded approval and rejection; its safe default is false.

agentProfiles adds named launch choices without removing the built-in profiles. OpenCode models use the full provider/model form; agent is optional, and configPath must be absolute. Keep provider credentials in your normal OpenCode authentication or environment setup rather than committing them to the repository.

Themes

• classic-blue -- Blue panels, cyan highlights. The classic look.
• midnight -- Dark background, blue accents.

Architecture

src/
  app.ts                    # Main application, key bindings, lifecycle
  panels/
    file-panel.ts           # File browser used by workspace panels
    terminal-panel.ts       # PTY-backed agent terminal with key forwarding
    preview-panel.ts        # Full-screen file viewer
    vterm.ts                # Virtual terminal emulator (ANSI/xterm)
  orchestration/
    protocol.ts             # Inter-agent protocol scanner & builder
    orchestrator.ts         # Task routing, agent lifecycle management
    message-ledger.ts       # Bounded in-memory routed messages and reply windows
  agents/
    agent-manager.ts        # Agent process lifecycle
    agent-registry.ts       # Auto-discovery of installed CLI agents
    types.ts                # Agent type definitions & known agents list
    pty-helper.py           # PTY allocator (cross-platform)
  screen/
    layout-manager.ts       # Adaptive, paged workspace for up to 100 active panels
    function-bar.ts         # Bottom menu bar (F-keys)
    status-bar.ts           # Status line
    toast.ts                # Toast notifications
    dialog/                 # Help, agent picker, orchestrate, template browser,
                            # protocol guide, confirm, input, log viewer
  editor/
    markdown-editor.ts      # Built-in text editor
  file-manager/
    file-operations.ts      # Copy, move, delete, mkdir
    file-watcher.ts         # Real-time filesystem monitoring
    file-system.ts          # Directory reading & file info
  templates/
    types.ts                # PromptTemplate interface
    loader.ts               # Template loader (builtin + user custom)
    builtin/                # 121 built-in prompt templates (.md with frontmatter)
  config/
    themes.ts               # Color themes
    loader.ts               # Config file loader (~/.agents-commander/)
    defaults.ts             # Default configuration
  utils/
    dialog-state.ts         # Shared dialog depth counter
    events.ts               # Application event bus
    logger.ts               # File-based debug logger
    format.ts               # Date/size formatting

How the Terminal Works

Each agent panel runs a real pseudo-terminal. This means:

• PTY-backed support for interactive terminal applications
• xterm-256color with ANSI escape sequence processing
• Real-time key forwarding (each keystroke is mapped to its ANSI sequence and sent to stdin)
• A custom VTerm virtual terminal emulator processes the output for display in the blessed UI

This is not a dumb pipe. It's a terminal emulator inside a terminal emulator.

What Agents Commander Adds

Agents Commander combines several local workflows in one TUI:

• up to 100 active file or PTY-backed agent panels in an adaptive, paged workspace
• integrated file browsing and file operations in any file panel
• text-marker scanning and routed SEND, REPLY, BROADCAST, STATUS, and QUERY messages
• one-key protocol instruction delivery, manual orchestration, and routed-message Activity
• a built-in library of 121 prompts

Roadmap

• Supported Claude Code, Codex CLI, Gemini CLI, OpenCode, and Shell adapters
• Prompt template library (Ctrl+B)
• Aider, Cline, Goose, Kiro, Amp support
• Task queue -- chain agent tasks in sequence
• Agent memory -- persistent context across sessions
• Plugin system for custom agents
• Session save/restore
• Opt-in semantic capture and reviewed LoRA/SFT dataset export
• Conversation replay

Documentation and contributions

The documentation index separates current user guides from proposals and historical reviews. See examples for optional collaboration workflows. Conference slides and speaker notes are supporting material, not a requirement for using or contributing to Commander.

Bug reports, documentation improvements, and focused pull requests are welcome. Read CONTRIBUTING.md for setup, the verification gate, and privacy precautions before sharing logs or agent output.

License

Open source under the MIT License, including commercial use. Retain the copyright and permission notice when redistributing the software; see third-party notices for included third-party material. Version 0.1.10 uses MIT. Versions 0.1.5–0.1.9 also used MIT. Earlier published packages retain the license bundled with those versions; updating the source does not relicense older artifacts.

---

Stop copy-pasting between AI agents.
Let them work together.