_cmd

The operator's glass cockpit for local AI coding agent swarms.

---

_cmd is a Command Center for AI Agents — a passive, real-time observability surface for monitoring local AI coding swarms. It subscribes to live JSON event streams and transforms them into a premium, multi-panel TUI and desktop dashboard—allowing you to inspect what your agents are doing, where they are stuck, and how they are spending tokens, without ever interfering with their execution.

🔭 Why _cmd?

Once you start running multiple agents, the bottleneck shifts from execution to visibility.

• Scattered Logs: Tailing five different terminal panes to find one error is a nightmare.
• Guesswork: You know agents are running, but are they healthy or just "stalled"?
• Information Overload: Raw JSON is great for machines, but terrible for human split-second decisions.

_cmd solves this by providing a dedicated, high-performance cockpit that is passive (never mutates state), real-time (60fps rendering), and high-density (sparklines, cards, and feeds in one _cmd).

✨ Features

• 🚀 Dual-Surface Engine: Choose between a blazing-fast Ratatui TUI for the terminal or a premium egui Desktop UI for native macOS feel.
• ⚡ Passive Observation: Zero interference. Subscribes to stdin or WebSocket streams without blocking the observed processes.
• 📊 Real-time Analytics: Tracks agent activity over a rolling 50-sample window with live sparklines.
• 🛡️ Error Awareness: Highlights status, error levels, and warnings with level-aware color systems (info, warn, error, success).
• 🧩 Multi-Agent Orchestration: Seamlessly toggle between Grid (high-density wall) and Focus (deep-dive drill-down) modes.
• 🔍 Global Search & Filter: Instantly filter by Agent ID, Project, Role, Branch, or Status across the entire swarm.
• 💾 LAN-Ready: Built-in Axum web server and WebSocket fan-out for remote monitoring across the local network.

🏁 Quick Start

1. The Demo (Rehearsal Mode)

The fastest way to see _cmd in action without any live agents:

# Start the TUI Dashboard
VIEW_DEMO=1 cargo run -p cli

# Start the Desktop Dashboard
VIEW_DEMO=1 cargo run -p desktop

2. Live Ingestion

Pipe any newline-delimited JSON stream (NDJSON) directly into the dashboard:

# Pipe your agent logs
tail -f agent_events.json | cargo run -p cli

⌨️ Global Shortcuts

Action	Shortcut
Quit	q / Ctrl + C
Toggle Mode (Grid/Focus)	Tab
Navigate Selection	j / k or Arrows
Jump Page	PgUp / PgDn
Filter Status	f (Cycle All/Busy/Active/Offline)
Search Swarm	/ (type to filter)
Clear Search/Focus	Esc

🏗️ Repository Architecture

_cmd is built with a strictly decoupled architecture, ensuring the core engine remains UI-agnostic.

crates/
├── core/      — Domain state, engine, listener, and event schemas (No UI deps)
├── cli/       — TUI surface via Ratatui + Crossterm
├── desktop/   — Native Desktop shell via egui + eframe
└── web/       — Web API + WebSocket server via Axum

🛠️ Technical Stack

• Rendering: Ratatui (TUI) & egui (Desktop)
• Async Runtime: Tokio
• Networking: Axum (Web/WS)
• Serialization: Serde JSON
• Terminal Hygiene: RAII-guarded raw mode handling via crossterm.

📡 Event Contract

_cmd consumes two main types of JSON payloads. If you want your agent to be "visible", just emit these to stdout or a socket:

Snapshot Payload (Seeds the roster)

{
  "kind": "snapshot",
  "agents": [
    {
      "id": "agent-01",
      "instance_name": "executor-alpha",
      "role": "executor",
      "project": "_cmd-dashboard",
      "branch": "main",
      "status": "busy",
      "metadata": { "tokens": "24500", "rai_level": "info" }
    }
  ]
}

Lifecycle Payload (Live updates)

{
  "kind": "updated",
  "current": {
    "id": "agent-01",
    "status": "idle",
    "metadata": { "rai_level": "success", "log": "Task completed successfully" }
  }
}

🗺️ Roadmap

• High-performance Ratatui TUI
• egui Desktop Shell with macOS polish
• Demo mode for UI iteration
• Pluggable event adapters (Socket, Tail, HTTP)
• Persistent event history export
• Project-level aggregate analytics
• Global CLI publish as _cmd

📄 License

MIT License. Built for the operator, the builder, and the dreamer.

---

Part of a trilogy of tools for the agentic era. See also Kaku and Warp.