Index / tool

AgentPulse for tmux

github.com/jerriclynsjohn/tmux-agent-pulse

Category: Developer Tools
Rank: No. 3369Tools index
Previous survey · No. 3221 · 17 October 2026
Pricing: Open Source
Type: TOOL
Use case: Productivity & Collaboration
Interfaces: Host Plugin
GitHub: 6 stars
Date: Published Sep 9, 2026

About

AgentPulse is a tmux plugin that shows live status (working, waiting, idle, cancelled, unknown) for Claude Code and Codex CLI sessions across panes and windows, with an optional popup picker and sidebar for quick navigation. It hooks into each CLI's lifecycle events to track which process owns a conversation, logging only lifecycle metadata rather than prompts or responses.

What it does

A small Python program that sits behind tmux and tells you which of your coding agents needs attention. Claude Code and Codex CLI are configured to call it whenever a session starts, a turn begins, a tool runs or an approval request appears. It turns that stream into a state record for each pane, and a background ticker copies the result into tmux variables that your own status line and border formats can display. Nothing is drawn until you add those variables to your theme.

Why it's ranked here

The state tracking is the careful part. Each record is tied to the agent's process ID plus its start time, so a recycled PID cannot inherit old status, and an event only updates a pane when its process ancestry actually reaches that pane's agent. The unit tests pin down awkward cases: an answer that contains the word cancel, several outstanding questions at once, approval requests that arrive without a call ID. MIT licensed and built on the Python standard library. The README calls it an early preview with no tagged release.

What's good

The installer treats your agent configuration with care. It previews changes before applying them, keeps unrelated hook entries, takes backups and records exactly what it added, so uninstall removes only definitions that are still unchanged. Loading the plugin assigns no keys and changes no theme, and optional key bindings skip any key another plugin already holds and report the conflict. The diagnostic event log is capped at 128KB and keeps session and turn identifiers, never prompt text or tool arguments.

Tradeoffs

Coverage stops at two agents: the process matcher recognises only Claude Code and Codex binaries. Status depends on hooks, so a conversation started before installation, or a Codex setup whose hooks were never trusted, shows as unknown. The compatibility notes list open gaps: no documented minimum tmux version, no measured cost at 10, 50 or 100 panes, and native approval and interruption flows not exercised end to end. Native Windows is out of scope, and desktop notifications exist only on macOS, off by default.

How to use it well

Worth installing if you run several Claude Code or Codex sessions in tmux and keep missing the one stuck on an approval prompt. Add it through TPM (the tmux plugin manager), run the hook installer in preview mode first, then put the window indicator into your status format. Give busy panes custom labels so the sidebar and popup read clearly. Run uninstall before removing the plugin, because TPM deletes files but leaves hooks in the agent configuration. It does not watch other agents or remote sessions.

Technical notes+

agent-pulse.tmux is a Bash shim that execs the Python entry point with the load command. In lib/agent_pulse.py, reduce_event is a pure reducer from hook events to one of idle, working, waiting or cancelled; it ignores subagent events, events from a different session_id or turn_id, and compaction restarts, and visible_record downgrades any record whose owner_pid and owner_start no longer match the live process (from a ps snapshot) to unknown. resolve_hook_pane walks the hook's ancestry and accepts only a single matching pane, so an inherited TMUX_PANE cannot redirect updates. Records are written atomically per pane under an flock; audit_event keeps an allowlisted field set and rotates at AUDIT_MAX_BYTES (128 KiB). lib/install_hooks.py expands the templates in hooks/claude.json and hooks/codex.json (Claude adds Notification and PostToolUseFailure, Codex adds Interrupt, all with a 3 second timeout), refuses to proceed when a managed hook was hand-edited, and writes through symlinks while preserving file mode. lib/plugin_runtime.py verifies the ticker by lock, PID start time and command line before reuse or SIGTERM, and probes key bindings through private key tables to work around tmux list-keys behaviour. docs/compatibility.md and tests/test_agent_pulse.py document and cover the lifecycle edge cases; docs/configuration.md lists every option.

Observed

License: MIT (LICENSE)
Language: Python standard library, with a Bash entry script (agent-pulse.tmux)
Distribution: tmux plugin installed through TPM or run from a local checkout (README.md)
Interface: CLI with load, unload, doctor, install, uninstall, popup, list, sidebar and hook commands (docs/configuration.md)
Supported agents: Claude Code and Codex CLI, via hook templates in hooks/claude.json and hooks/codex.json
Platforms: macOS and Linux; native Windows outside scope (docs/compatibility.md)
Optional dependency: fzf for the popup picker (README.md)
Tests: unittest suite covering lifecycle transitions (tests/test_agent_pulse.py)
Release status: Early preview with no tagged release (README.md)

Read from README.md, agent-pulse.tmux, lib/agent_pulse.py, lib/install_hooks.py, lib/plugin_runtime.py, hooks/claude.json, hooks/codex.json, docs/configuration.md, docs/compatibility.md, tests/test_agent_pulse.py, LICENSE.

What it can do

Hook into Claude Code and Codex CLI lifecycle events to track which process owns a conversation
CLI lifecycle events → Process-to-conversation mapping
Log lifecycle metadata for CLI sessions without recording prompts or responses
CLI lifecycle events → Lifecycle metadata log

Comments (0)

No comments yet

Editorially curated, with community endorsements as a secondary signal. Corrections welcome.