Gentle Agent State

gentle-agent-state

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

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

- tmux: colored state markers in the window/tab bar, rolled up from all panes.
- Zellij: the tab title can roll up agent state; the exact agent pane title changes too.
- Ghostty: the native window/tab title shows the latest agent state and plays transition sounds.
- Agents: opencode, pi, Claude Code, and Codex.

Quick path

Then restart your agents inside tmux, Zellij, or Ghostty.

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

Want only specific agents?

What you get

tmux behavior

The window state marker shows the worst state across panes:

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

Zellij behavior

Zellij does not expose tmux-style window user options, so the backend uses native
pane renaming actions. By default it does not rename tabs, preserving
user-managed tab names exactly; the exact agent pane title shows its own state.

If you prefer tab-title rollup, opt in with AGENT_ZELLIJ_RENAME_TAB=1. In that
mode the tab title appends the worst state across panes in that tab, and the
backend best-effort restores the original tab name when the tab returns to idle.

Ghostty behavior

Native Ghostty support uses TERM_PROGRAM=ghostty, updates the terminal title
with OSC escape sequences, and plays the same best-effort transition sounds as
other backends: blocked sound when the state becomes blocked, and idle sound
when working returns to idle. A direct blocked → idle transition stays
quiet to avoid double-playing blocked and…