xbunax

Agent Tmux Notify

Productivity community

SOURCE https://github.com/xbunax/agent-tmux-notify

Description

A tmux-based monitor that watches Claude Code CLI instances across panes and automatically pops up an interactive curses TUI when user input is needed (permission requests, plan approvals, task completions), with optional Claude Code hook integration for richer context.

Installation

This entry records only its repository, not the path inside it, so there is no exact command to give. Open the source below and copy the folder into ~/.claude/skills/, or the file into ~/.claude/agents/.

README

agent-tmux-notify

[**中文**](README.zh.md) | English

Monitor Claude Code CLI instances inside tmux, automatically popping up an interactive TUI window when user input is needed.

Showcase

Permission Request

Permission request demo

Plan Approval

Plan approval demo

Features

Auto Discovery: Scans all tmux panes on startup, binding to running Claude Code processes (PID)
Hook-Driven Core: Receives PreToolUse, PermissionRequest, Notification and other events pushed by Claude Code hooks, directly triggering popups and sending user decisions back to Claude Code
Buffer-Assisted Parsing: Reads recent tmux buffer lines only as auxiliary context to recover option lists and current selection
Popup Interaction: When input is needed, opens a curses TUI next to the current pane, displaying context, questions, and options
Plan File Reading: In plan approval scenarios, automatically reads plan files from ~/.claude/plans/ and renders the full Plan in the popup
Idle Notification: Pops up a notification when Claude Code is idle waiting for input, with one-key focus to the corresponding pane
Rich Markdown Rendering: Popup context is rendered with the rich library, supporting syntax highlighting
Configurable Parse Rules: Parse rules (regex + keywords) for permission/plan prompts are customizable in the config file
Focus Jump: In the popup, you can jump directly to the corresponding pane
macOS Service: Provides launchd service configuration, supporting startup on boot and background operation

Installation

Homebrew (via tap)

brew tap xbunax/tap
brew install xbunax/tap/agent-tmux-notify
brew services start xbunax/tap/agent-tmux-notify

From Source

Requires Python 3.13+ and [uv](https://github.com/astral-sh/uv).