Your kitty tabs show what each coding agent is doing.
Blue while it works, amber when it needs you, back to normal when it's done.

Run several agents across kitty tabs and you lose track of which one is grinding, which one is blocked on you, and which one finished ten minutes ago. kitty-agent-status paints each tab by state, so a glance at the tab bar tells you where to look. No daemon, no dependencies - just your agents' own lifecycle events wired to kitten @ set-tab-color.

A finished agent reverts to your normal tab color, so amber always means act on me.

Each agent exposes a different signal, so the tab is driven from whatever each one offers:

• Claude Code - three hooks: UserPromptSubmit → blue, Stop → default, and Notification (only the permission_prompt matcher) → amber. Idle "waiting for input" notifications are ignored on purpose, so a finished session does not get stuck amber.
• Any agent in your shell - a tiny preexec/precmd integration (bash and zsh) turns the tab blue while a known agent command runs and reverts it at the next prompt. Configure which commands count with KAS_AGENT_RE.
• Codex - point its notify at the bundled chain script; it goes amber on each completed turn and forwards your existing notify program untouched.
• The bell - kitty's built-in bell_on_tab already flags any tab whose program rings the bell, a free catch-all for agents that signal that way.

Everything funnels through one script, agent-status.sh <state>, which is a no-op outside kitty.

One line - copies the scripts into ~/.config/kitty/agent-status, sources the shell integration from your ~/.zshrc / ~/.bashrc, and wires the Claude Code hooks:

curl -fsSL https://raw.githubusercontent.com/oleg-koval/kitty-agent-status/main/install.sh | bash

Open a new kitty tab (or source ~/.zshrc) and it's live. Pass --no-claude to skip the Claude Code hooks. Re-running is idempotent.

# 1. grab the scripts
DEST=~/.config/kitty/agent-status
mkdir -p "$DEST/shell"
base=https://raw.githubusercontent.com/oleg-koval/kitty-agent-status/main
for f in agent-status.sh codex-notify.sh shell/integration.sh; do
  curl -fsSL "$base/$f" -o "$DEST/$f"
done
chmod +x "$DEST"/*.sh

# 2. shell integration — add to ~/.zshrc and/or ~/.bashrc
echo 'source ~/.config/kitty/agent-status/shell/integration.sh' >> ~/.zshrc

# 3. Claude Code hooks — add to ~/.claude/settings.json "hooks":
#   "UserPromptSubmit": [{"hooks":[{"type":"command","command":"~/.config/kitty/agent-status/agent-status.sh working"}]}]
#   "Stop":            [{"hooks":[{"type":"command","command":"~/.config/kitty/agent-status/agent-status.sh done"}]}]
#   "Notification":    [{"matcher":"permission_prompt","hooks":[{"type":"command","command":"~/.config/kitty/agent-status/agent-status.sh needs-input"}]}]

Codex allows a single notify program. Point it at the chain script, which tints the tab and then forwards to whatever you had before:

# ~/.codex/config.toml
notify = ["/Users/you/.config/kitty/agent-status/codex-notify.sh"]

Already using notify (e.g. a desktop notifier)? Keep it running:

export CODEX_NOTIFY_FORWARD="/path/to/your/old/notify"

Everything is environment variables - set them before the integration is sourced (e.g. earlier in your rc).

Colors accept a #rrggbb value, a kitty color name, or NONE.

• kitty with allow_remote_control enabled (yes or socket-only)
• bash or zsh for the shell integration
• python3 (only the installer uses it, to edit settings.json)

rm -rf ~/.config/kitty/agent-status

Then remove the source .../integration.sh line from your shell rc, the three agent-status.sh hooks from ~/.claude/settings.json, and the notify line from ~/.codex/config.toml if you set it.

• No dependencies, no daemon, no network. It only calls kitten @ set-tab-color.
• Read-only toward your work. It reads the name of the command you ran and the state your agent reports. It never reads your code or an agent's output.
• Never breaks a prompt. Color calls are best-effort; outside kitty every entry point is a clean no-op.

Issues and PRs welcome - see CONTRIBUTING.md. It's a handful of shell scripts; let's keep it tiny.

MIT © Oleg Koval

_{GitHub · Issues · built for kitty}