@williamking/agent-dashboard

macOS Collector and Codex launcher for the Agent Dashboard Android client, with automatic read-only Prime Agent monitoring.

Requirements

• macOS
• Node.js 22 or newer
• Codex CLI 0.147.0 or newer, installed and signed in
• OpenSSL

Install

npm install --global @williamking/agent-dashboard
agent-dashboard install-service
agent-dashboard install-fish
agent-dashboard doctor

Pair the Android client with a one-time code:

agent-dashboard pair

Start monitored Codex sessions through the Collector:

agent-dashboard codex
agent-dashboard codex -C /path/to/worktree
agent-dashboard codex resume

Prime Agent (optional, read-only)

If prime-agent is available in the Collector's PATH, active Prime sessions and subagents are discovered automatically. The default auto mode discovers the default daemon via prime-agent status --json, validates its private Unix socket, and subscribes to roster changes after checking protocol/schema/capabilities. Changes trigger coalesced list refreshes; a full refresh also runs every 30 seconds. Unsupported protocols, disconnects or timeouts fall back to prime-agent list --json polling (2 seconds after each completed query), with periodic subscription retries.

Set AGENT_DASHBOARD_PRIME_TRANSPORT=cli to force the original polling mode; auto is the default. Other values are rejected. Start Prime normally; no launcher wrapper is needed. The Collector does not start or stop the Prime daemon, attach to sessions or expose the daemon socket over the network. LaunchAgent services do not load interactive shell config; configure overrides in the service environment.

Prime cards show basic state, hierarchy and cumulative input/output tokens. They do not allow input, approval or stop actions. Current context usage is unknown; the dashboard's global plan usage still refers to Codex. Failed polls mark cached Prime cards disconnected; successful empty lists remove them. Missing Prime does not prevent Codex monitoring. Codex remains required for Collector startup.

Version

agent-dashboard version
# Aliases: agent-dashboard --version, agent-dashboard -v

Prints the installed Collector version without starting a service.

Service management

agent-dashboard restart
agent-dashboard uninstall-service

The optional Fish integration installs a managed codex function that forwards all arguments to agent-dashboard codex:

agent-dashboard install-fish
agent-dashboard install-fish --force
agent-dashboard uninstall-fish

An unmanaged existing codex.fish is never replaced unless --force is used; forced replacement creates a backup first.

The LaunchAgent logs to ~/Library/Logs/Agent Dashboard/. Runtime identity, certificates, and paired-client data are stored in ~/Library/Application Support/Agent Dashboard/ and are preserved when the service is uninstalled.