tmux status bar monitor for Claude Code, Codex & Gemini — track AI coding sessions in real time

node version

English | 한국어

Why marmonitor?

Running multiple AI coding agents in tmux is now the norm — Claude Code refactoring your backend, Codex writing tests in another pane, Gemini reviewing docs in a third. But as sessions multiply, you hit the same wall:

You switch to a pane only to find the agent has been waiting for allow for 10 minutes
You forget which window has the Codex session you were just working with
You have no idea how many tokens you've burned across sessions

There's no dashboard for this. You're alt-tabbing between panes, checking each one manually.

marmonitor fixes this. One line in your tmux.conf, and your status bar becomes a live control panel for every AI session on your machine.

marmonitor tmux statusbar
Agent counts, phase badges, and numbered attention pills — all in your tmux bar

What it does

tmux statusline — always visible at the bottom of your terminal:

Agent counts (Cl 12, Cx 2, Gm 1) — how many sessions are running
Phase alerts (⏳ 1, 🤔 2, 🔧 1) — which sessions need attention
Numbered pills (1 ⏳Cl my-project allow, 2 •Cx api-server 6m) — jump to any session with Option+1~5

Attention priority — sessions that need your input come first:

⏳ permission (allow waiting) is always #1 — you need to approve
🤔 thinking (AI responding) is #2 — result coming soon
Then most recently active sessions, so you can quickly return to what you were working on

Quick jump — press Option+1 to jump directly to the #1 attention session's tmux pane. No searching through windows.

Full status — marmonitor status shows everything:

marmonitor status output
All sessions with status, tokens, phase, CPU/MEM, and worker process tree

Zero instrumentation — no API keys, no agent plugins, no code changes. marmonitor reads local process info and session files from the outside. Two commands to get started: npm install -g marmonitor then marmonitor setup tmux.

Built for the tmux + AI multi-session workflow. If you run 5+ AI coding sessions daily across different projects, marmonitor turns context-switching from guesswork into a glance at your status bar.

Supported Agents

Agent	Detection	Session Enrichment	Phase Tracking
Claude Code	Native binary	Tokens, timestamps, model	thinking, tool, permission, done
Codex	Binary + cmd fallback	Tokens, timestamps, model	thinking, tool, done
Gemini	cmd fallback	Tokens, timestamps, model	thinking, tool, done

Install

1. Install marmonitor

npm install -g marmonitor

2. Set up tmux integration

marmonitor setup tmux

This adds the marmonitor-tmux plugin to your ~/.tmux.conf. Then press prefix + I inside tmux to activate.

After upgrading marmonitor, run:

marmonitor update-integration

This checks whether your tmux integration also needs a TPM/plugin update.

If you updated the TPM plugin with prefix + U but click actions or popup keybindings still behave like the old version, re-apply the plugin in the running tmux server:

tmux run-shell ~/.tmux/plugins/marmonitor-tmux/marmonitor.tmux

This mainly affects existing tmux sessions after a plugin upgrade. Fresh installs via prefix + I usually load the current bindings immediately.

Or add manually to ~/.tmux.conf

set -g @plugin 'mjjo16/marmonitor-tmux'

Requires tpm.

Manual install (without tpm)

git clone https://github.com/mjjo16/marmonitor-tmux ~/.tmux/plugins/marmonitor-tmux

Add to ~/.tmux.conf:

run-shell ~/.tmux/plugins/marmonitor-tmux/marmonitor.tmux

Install from source (development)

git clone https://github.com/mjjo16/marmonitor.git
cd marmonitor
npm install && npm run build
npm link

Quick Start

Once installed, your tmux status bar automatically shows AI session badges. You also get:

Shortcut	Action
`prefix + a`	Attention popup — choose a session to review
`prefix + j`	Jump popup — pick a session to jump to
`prefix + m`	Dock — compact monitor pane
`Option+1~5`	Direct jump to attention session #1~5

CLI commands:

marmonitor status       # Full session inventory
marmonitor attention    # What needs your input?
marmonitor watch        # Live full-screen monitor
marmonitor help         # All commands and options

Phase Icons

Icon	Phase	Meaning
⏳	`permission`	AI requesting tool approval — user input needed
🤔	`thinking`	AI generating a response
🔧	`tool`	Approved tool executing
✅	`done`	Response complete, awaiting next instruction

Status Labels

Label	Meaning
`[Active]`	CPU activity detected
`[Idle]`	Process alive, no recent activity
`[Stalled]`	No activity for extended period
`[Dead]`	Session file exists but process is gone
`[Unmatched]`	AI process found but no matching session

tmux Plugin

The marmonitor-tmux plugin handles all tmux setup automatically:

2nd status line with agent badges and attention pills
Key bindings for popup, jump, and dock
Option+1~5 direct jump

All settings are customizable via @marmonitor-* options. See the plugin README for details.

Badge styles

tmux badges and terminal text output can share one style via integration.tmux.badgeStyle.

basic — default colored pills
basic-mono — monochrome pills with Powerline borders
text — plain colored text, no filled background
text-mono — grayscale text only

Configuration

Config is loaded from (first found wins):

$XDG_CONFIG_HOME/marmonitor/settings.json
~/.config/marmonitor/settings.json
~/.marmonitor.json

# View current config path and values
marmonitor settings-path
marmonitor settings-show

# Generate a starter config
marmonitor settings-init --stdout

Example Config

{
  "display": {
    "attentionLimit": 10,
    "statuslineAttentionLimit": 5
  },
  "status": {
    "stalledAfterMin": 20,
    "phaseDecay": {
      "thinking": 20,
      "tool": 30,
      "permission": 0,
      "done": 5
    }
  },
  "integration": {
    "tmux": {
      "badgeStyle": "basic",
      "keys": {
        "attentionPopup": "a",
        "jumpPopup": "j",
        "dockToggle": "m",
        "directJump": ["M-1", "M-2", "M-3", "M-4", "M-5"]
      }
    }
  }
}

Uninstall

marmonitor uninstall-integration    # Remove tmux settings + restore status bar
npm uninstall -g marmonitor         # Remove CLI

Safety

Read-only by default — observes only, never modifies your sessions
No network — zero outbound connections, all data stays local
Conservative defaults — all integrations are opt-in
tmux-first — terminal-native WezTerm/iTerm2 surfaces are currently paused

Contributing

See CONTRIBUTING.md for setup, commit conventions, and PR guidelines. For architecture details, see ARCHITECTURE.md.

Known Limitations

Pane jump requires tmux
WezTerm / iTerm2 native bars are paused for now; tmux is the supported surface
Gemini permission detection is limited due to Ink TUI architecture
Phase detection relies on heuristics — accuracy varies by agent
macOS first; Linux support is untested

License

MIT — MJ JO