Gentle Agent State — AI skill for Claude Code

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.

  1 api o      2 claude x      3 notes
  (orange)    (red, beeps)    (idle)

---

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, Zellij, or Ghostty.

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

State	Meaning	tmux display	Zellij display	Ghostty display	Alert
working	Agent is running	o in orange	pane title: o	title marker: o	none
blocked	Agent is waiting for you	x in red	pane title: x	title marker: x	sound + flash/message in tmux/Zellij, sound in Ghostty
idle	Agent finished or is not running	no marker	pane title restored	marker removed	sound after busy state

tmux behavior

The window state marker shows the **worst state across panes**:

blocked > working > idle

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 op