tmux-monitor

name	tmux-monitor
description	Use to discover which coding agents are running in tmux, find agents relevant to the current repo, check what they're working on, and coordinate or control them. Run before starting work to avoid conflicts, or to send commands to other agents.

tmux Agent Monitor

Discover and coordinate coding agents running across tmux sessions.

When to Use

• Before starting work on a repo — check if another agent is already there
• To understand what other agents are doing
• To coordinate or send commands to another agent
• When asked "what's running?" or "who's working on X?"

Commands

Check relevant agents (most common)

# Agents in current repo (uses cwd)
tmux-monitor status

# Agents in a specific repo
tmux-monitor status --repo driftdriver

# JSON for programmatic parsing
tmux-monitor status --json

# All agents including unrelated repos
tmux-monitor status --all

Control another agent

The JSON output includes a pane_id field. Use it to send commands:

tmux send-keys -t %272 "your command" Enter

Other commands

# List all sessions
tmux-monitor sessions

# View a pane's log output
tmux-monitor logs "fresh_7.1"

# Run a single heartbeat cycle
tmux-monitor heartbeat

Output Fields

Field	Meaning
session	tmux session name
pane	Window.pane identifier (e.g., fresh:7.1)
pane_id	tmux internal ID for send-keys control (e.g., %298)
type	Agent type: codex, claude-code, opencode, kilocode, pi-dev, shell, idle
title	Pane title from tmux (often shows current task or repo)
relevance	same_repo / related / unrelated
current_task	LLM-extracted task description
summary	LLM-generated paragraph summary of recent activity
controllable	Whether the agent can receive tmux send-keys commands

Coordination Protocol

1. Before starting work: Run tmux-monitor status --json
2. If relevant_count > 0: Read the existing agent's current_task and summary
3. If same task: Coordinate via tmux send-keys or defer
4. If different task: Proceed but note the other agent may have context you need
5. After finishing: No cleanup needed — the monitor tracks lifecycle automatically

State Location

Status file: ~/.local/share/driftdriver/tmux-monitor/status.json Pane logs: ~/.local/share/driftdriver/tmux-monitor/panes/ Daily events: ~/.local/share/driftdriver/tmux-monitor/daily/