AI Agent Session Bar

A macOS menu bar app that can be controlled from external processes.

Features

• Show an icon in the menu bar
• Control via UNIX socket (notifications)
• Send notifications to macOS Notification Center
• Notification list menu and clear-all

Install

uv sync

Usage

Start the app

uv run ai-agent-session-bar

Send commands (from another terminal)

# Show a notification
uv run ai-agent-session-bar -message "Processing completed"
uv run ai-agent-session-bar -message "Build: succeeded"

# In a tmux session, metadata (session/window/pane) is attached automatically
uv run ai-agent-session-bar -message "Build: succeeded"
Note: Keep `TMUX` available in the execution environment.
# Shortcut for opening the menu bar item can be changed from:
# "Shortcut" -> "Set shortcut"

# List sessions (JSON: id/tty/tmux/last_message/app/project/activated_at/read_at)
uv run ai-agent-session-bar -list

# List sessions newest first (by activated_at)
uv run ai-agent-session-bar -list-reverse

# Delete a session by tty (see -list output)
uv run ai-agent-session-bar -delete <TTY>

# Mark a session as read by tty (see -list output)
uv run ai-agent-session-bar -mark-read <TTY>

# Delete all sessions
uv run ai-agent-session-bar -delete-all

# Help
uv run ai-agent-session-bar --help

Using with Coding Agent Hooks

When a coding agent executes hooks in a non-interactive context, tmux "current client" may point to the last focused pane (not the pane where the agent was started). ai-agent-session-bar first resolves tmux metadata from TMUX_PANE (tmux display-message -p -t <pane>), then falls back to process TTY (ps -o tty= -p <pid>, tracing parent processes up to 5 levels), so keep TMUX available in hook execution.

Recommended workflow (Codex example)

1. Update the wrapper used by hooks.

cp scripts/ai-agent-session-bar ~/bin/ai-agent-session-bar
chmod +x ~/bin/ai-agent-session-bar

2. Start Codex from the target tmux pane with fixed TMUX.

CODX_TMUX="$TMUX" codex

3. Configure ~/.codex/config.toml.

notify = [
  "bash",
  "-c",
  "TMUX=\"$CODX_TMUX\" ai-agent-session-bar -message '🧠 Codex: Task finished'",
]

4. Verify.

which ai-agent-session-bar
ai-agent-session-bar -list | jq

tmux.window.index and tmux.pane.index should match the pane where Codex was started.

Build as .app

uv run python setup.py py2app

dist/AIAgentSessionBar.app will be generated.

• Run

open "dist/AIAgentSessionBar.app"

Shortcut permission troubleshooting (macOS)

If Shortcut -> Set shortcut fails in the built app:

1. Quit AI Agent Session Bar.
2. Reset TCC permissions for the app bundle identifier.

tccutil reset All com.masakiq.aiagentsessionbar

3. Launch dist/AIAgentSessionBar.app again.
4. In System Settings -> Privacy & Security, enable both:
   • Accessibility for AI Agent Session Bar
   • Input Monitoring for AI Agent Session Bar
5. Quit and relaunch AI Agent Session Bar, then retry Set shortcut.

Runtime wrapper (nc-based)

The build artifact includes a sending script that uses nc.

dist/AIAgentSessionBar.app/Contents/Resources/bin/ai-agent-session-bar -message "Test"
dist/AIAgentSessionBar.app/Contents/Resources/bin/ai-agent-session-bar -list
dist/AIAgentSessionBar.app/Contents/Resources/bin/ai-agent-session-bar -delete <TTY>
dist/AIAgentSessionBar.app/Contents/Resources/bin/ai-agent-session-bar -mark-read <TTY>
dist/AIAgentSessionBar.app/Contents/Resources/bin/ai-agent-session-bar -delete-all

IPC Protocol

Socket path: /tmp/ai_agent_session_bar.sock The ai-agent-session-bar command sends to this socket.

Menu Structure

• Sessions (project basename + last message + activated_at)
• Clear messages
• Quit

On-click Script Execution

On-click script runs with the user's shell as a non-interactive login shell.

• Shell: $SHELL (fallback: /bin/bash)
• Invocation: <shell> -l -c "<script>"
• Timeout: 10 seconds
• Output: stdout/stderr are captured for logging

Development Notes

To use notifications in development mode, an Info.plist is required:

/usr/libexec/PlistBuddy -c 'Add :CFBundleIdentifier string "com.example.aiagentsessionbar"' .venv/bin/Info.plist

If notifications do not appear, check macOS "System Settings → Notifications" and make sure AI Agent Session Bar is allowed. If AI Agent Session Bar does not show up in the list, start the app and send a -message to register it.

To revert the development setup, remove the Info.plist:

rm -f .venv/bin/Info.plist