Guides

Agent integrations

vmux hooks install writes the integration for whichever agents it finds. Once installed, agent state lands in the sidebar without you doing anything else.

Install hooks

vmux hooks install                  # all detected agents
vmux hooks status
vmux hooks install --agent claude   # ~/.claude/settings.json
vmux hooks install --agent codex    # ~/.codex/hooks.json
vmux hooks install --agent grok     # ~/.grok/hooks/vmux.json (+ skill)
vmux hooks install --agent shell

Once installed, agent state — busy, needs input, done, failed — lands in the sidebar with no further setup: Claude (~/.claude/settings.json), Codex (~/.codex/hooks.json), Grok Build (~/.grok/hooks/vmux.json), and a shell hook for anything else. Run vmux hooks status any time to see which are wired up.

Screen-manifest detection

For agents without a hook system, vmux can also read the pane's screen contents against known UI patterns (herdr-style primary status for Claude/Codex/…). Screen rules take priority; hooks fill in when no manifest agent is running.

# Offline explain (read screen dump from stdin or --file):
printf '%s\n' ' ❯  ' | vmux detect --agent claude
vmux detect --agent claude --file screen.txt --osc-title $'⣿ thinking' --json
# Local rule overrides: ~/.config/vmux/agent-detection/<agent>.toml

Status is sticky when it matters

Done (✅) is sticky — it stays until you actually look at the pane, so an agent finishing while you were in another workspace is still there when you get back.

Drive it yourself

To report status from a script or an agent with no built-in integration:

vmux set-status busy --message "working"
vmux set-progress 75
vmux notify --pane pane-1 --status done --color green --message "tests passed"
vmux notifications --limit 10
vmux events --limit 50
vmux events --follow --interval-ms 250
vmux clear-notifications
vmux jump-notification

Or raise notifications with plain OSC escapes, no vmux command in the loop:

printf '\033]9;needs input\a'
printf '\033]777;notify;Claude;waiting for approval\a'

Shell integration and scripting

eval "$(vmux hooks shell)"
vmux hooks setup --dir ~/.config/vmux --rc ~/.bashrc
echo '{"event":"needs-input","message":"waiting"}' | vmux hooks event --pane "$VMUX_PANE_ID"

The shell integration defines helpers you can call from scripts:

vmux_hook_run "tests" cargo test
vmux_hook_attention "waiting for approval"
vmux_hook_progress 50

Automatic tab names

Any tab holding a coding agent names itself after the work in it — see Configuration → automatic tab names for the full source order (OSC titles, hook prompts, status messages, LLM fallback).

Finding your own place in the tree

Panes export discovery variables, so a process can find its own place without being told:

VMUX_SESSION  VMUX_WORKSPACE_ID  VMUX_PANE_ID  VMUX_SURFACE_ID  VMUX_SOCKET_PATH

vmux identify --json
vmux agents
vmux agent read --agent pane-1
vmux agent send --agent pane-1 --enter "continue"

Naming note. vmux was renamed from an earlier project called lmux. The LMUX_PANE_ID environment variable still exists next to VMUX_PANE_ID for backward compatibility — shell hooks read ${VMUX_PANE_ID:-${LMUX_PANE_ID:-}}, and vmux hooks status flags a hook that only mentions the old name as stale.

Multi-agent teams

vmux agent new --command "claude" --title backend --workspace ws-2
vmux agent team --agents codex,claude --cwd "$PWD"
vmux agent list
vmux broadcast --scope workspace --enter "npm test"
vmux run --command "npm test" --title tests --timeout 60
vmux wait --pane pane-1 --status attention,done,error --timeout 600

Edit this page on GitHub