gentle-agent-state

See when an AI agent needs you without hunting through panes.

gentle-agent-state connects AI coding agents to your terminal multiplexer. Agents emit lifecycle events, this project normalizes them into working, blocked, and idle, then shows the state in tmux or Zellij.

• tmux: colored dots in the window/tab bar, rolled up from all panes.
• Zellij: the tab title rolls up agent state; the exact agent pane title changes too.
• Agents: opencode, pi, Claude Code, and Codex.

  ● 1 api      ● 2 claude      3 notes
  └ working    └ blocked       └ idle
  (orange)     (red, beeps)    (no dot)

Quick path

git clone https://github.com/Gentleman-Programming/gentle-agent-state.git
cd gentle-agent-state
./install.sh --all

Then restart your agents inside tmux or Zellij.

For tmux, either open a fresh tmux session or reload your config:

tmux source-file ~/.config/tmux/tmux.conf

Want only specific agents?

./install.sh --with-opencode --with-pi
./install.sh --with-claude --with-codex

What you get

tmux behavior

The window dot shows the worst state across panes:

blocked > working > idle

So if any pane in a tmux window is blocked, that window turns red.

Zellij behavior

Zellij does not expose tmux-style window user options, so the backend uses native renaming actions instead. The tab title keeps its original name and appends the worst state across panes in that tab, while the exact agent pane title shows its own state. Original tab names are remembered and restored when the tab returns to idle.

Supported agents

Adapters are opt-in. The installer only touches agents you request, except --all, which selects agents whose config directories already exist.

Claude/Codex hook merging is append-only and idempotent. Existing hooks are kept. Legacy tmux-agent-state hook commands are migrated to the neutral gentle-agent-state core path.

Requirements

Required:

• bash
• jq
• python3
• either tmux or zellij

Optional sound players:

• macOS: afplay
• Linux/BSD: paplay, canberra-gtk-play, or aplay

No sound player? Nothing breaks; alerts just become visual/state-only.

Configuration

tmux colors

tmux dot colors live in tmux/agents.conf:

Edit those values if your theme needs different colors.

How it works

Every agent has its own event dialect. gentle-agent-state keeps that complexity at the edge with thin adapters:

opencode ┐
pi       ├──▶  agent-report.sh  ──▶  tmux backend
Claude   │                       └─▶  Zellij backend
Codex    ┘

The core vocabulary is deliberately small:

This is an anti-corruption layer: adding a new agent should require one adapter, not changes to every multiplexer backend.

Installed core files

tmux-specific files

Troubleshooting

I installed it, but nothing changes

Check that you restarted the agent process after installing the adapter. Most agents load plugins/extensions only on startup.

tmux dots do not appear

Reload tmux config:

tmux source-file ~/.config/tmux/tmux.conf

Then confirm your config sources the generated file:

grep agents.conf ~/.config/tmux/tmux.conf ~/.tmux.conf 2>/dev/null

Zellij tab or pane title does not change

Confirm the agent is running inside Zellij and has a pane id:

echo "$ZELLIJ_PANE_ID"
zellij action rename-pane --pane-id "$ZELLIJ_PANE_ID" "test-pane"
zellij action undo-rename-pane --pane-id "$ZELLIJ_PANE_ID"
zellij action current-tab-info
zellij action rename-tab "test-tab"
zellij action undo-rename-tab

Claude or Codex hooks do not fire

Re-run the installer for that agent and inspect the hook file:

./install.sh --with-claude
jq '.hooks' ~/.claude/settings.json

./install.sh --with-codex
jq '.hooks' ~/.codex/hooks.json

I use Herdr

Set HERDR_ENV=1. All adapters exit early and let Herdr own the integration.

Uninstall

./uninstall.sh

This removes:

• the neutral core scripts;
• tmux agents.conf and generated tmux scripts;
• the tmux source line from ~/.config/tmux/tmux.conf or ~/.tmux.conf;
• opencode/pi adapter files;
• Claude/Codex hooks added by this project.

Other hooks and user configuration are preserved.

Development notes

Run quick checks before opening a PR:

bash -n install.sh uninstall.sh scripts/*.sh tmux/scripts/*.sh
node --check adapters/opencode/gentle-agent-state.js

A useful smoke test is installing into a temporary home:

tmp="$(mktemp -d)"
HOME="$tmp" ./install.sh
HOME="$tmp" ./uninstall.sh

License

MIT — see LICENSE.