Status tracking

Workmux can display the status of the agent in your tmux window list, giving you at-a-glance visibility into what the agent in each window is doing.

Agent support

Agent	Status
Claude Code	✅ Supported
OpenCode	✅ Supported
Gemini CLI	In progress
Codex	Tracking issue

Status icons

• 🤖 = agent is working
• 💬 = agent is waiting for user input
• ✅ = agent finished (auto-clears on window focus)

Automated setup

Run workmux setup to automatically detect your agent CLIs and install status tracking hooks:

workmux setup

This detects Claude Code and OpenCode by checking for their configuration directories, then offers to install the appropriate hooks. Workmux will also prompt you on first run if it detects an agent without status tracking configured.

Workmux automatically modifies your tmux window-status-format to display the status icons. This happens once per session and only affects the current tmux session (not your global config).

Claude Code setup

If you prefer manual setup, install the workmux status plugin:

claude plugin marketplace add raine/workmux
claude plugin install workmux-status

Alternatively, you can manually add the hooks to ~/.claude/settings.json. See .claude-plugin/plugin.json for the hook configuration.

OpenCode setup

If you prefer manual setup, download the workmux status plugin to your global OpenCode plugin directory:

mkdir -p ~/.config/opencode/plugin
curl -o ~/.config/opencode/plugin/workmux-status.ts \
  https://raw.githubusercontent.com/raine/workmux/main/.opencode/plugin/workmux-status.ts

Restart OpenCode for the plugin to take effect.

Customization

You can customize the icons in your config:

# ~/.config/workmux/config.yaml
status_icons:
  working: "🔄"
  waiting: "⏸️"
  done: "✔️"

If you prefer to manage the tmux format yourself, disable auto-modification and add the status variable to your ~/.tmux.conf:

# ~/.config/workmux/config.yaml
status_format: false

# ~/.tmux.conf
set -g window-status-format '#I:#W#{?@workmux_status, #{@workmux_status},}#{?window_flags,#{window_flags}, }'
set -g window-status-current-format '#I:#W#{?@workmux_status, #{@workmux_status},}#{?window_flags,#{window_flags}, }'

Jump to completed agents

Use workmux last-done to quickly switch to the agent that most recently finished its task. Repeated invocations cycle through all completed agents in reverse chronological order (most recent first).

Add a tmux keybinding for quick access:

# ~/.tmux.conf
bind l run-shell "workmux last-done"

Then press prefix + l to jump to the last completed agent, press again to cycle to the next oldest, and so on. This is useful when you have multiple agents running and want to review their work in the order they finished.

Toggle between agents

Use workmux last-agent to toggle between your current agent and the last one you visited. This works like vim's Ctrl+^ or tmux's last-window - it remembers which agent you came from and switches back to it. Pressing it again returns you to where you were.

This is available both as a CLI command and as the Tab key in the dashboard.

Add a tmux keybinding for quick access:

# ~/.tmux.conf
bind Tab run-shell "workmux last-agent"

Then press prefix + Tab to toggle between your two most recent agents.