agentoast

A macOS menu bar app for tmux users. Get a toast notification whenever an AI coding agent (Claude Code, Codex, Copilot CLI, opencode) finishes or needs your input — click it to jump right back to the tmux pane it came from.

You kick off a long-running agent task, switch over to a browser or another window, and completely miss the moment it wraps up or asks for permission. agentoast makes sure you never miss it.

Add a hook to your agent's config. All notifications are grouped by repository in the menu bar — clicking one takes you straight to its tmux pane.

A toast pops up whenever an agent completes or needs attention — click it to jump right back to the tmux pane.

Requirements

agentoast auto-detects binary paths by searching well-known locations (Homebrew, system, Nix). If the Sessions panel is empty, see the [system] config to set paths manually.

Installation

brew install shuntaka9576/tap/agentoast-cli
brew install --cask shuntaka9576/tap/agentoast

Or download the DMG from Releases.

To uninstall:

brew uninstall --cask shuntaka9576/tap/agentoast
brew uninstall shuntaka9576/tap/agentoast-cli

Usage

Works With

All agents utilize the built-in CLI (agentoast hook <agent>). See the Integration section for setup details. If you'd like to see support for other agents, please feel free to open an issue.

Config

Opens ~/.config/agentoast/config.toml in your editor, creating a default one if it doesn't exist yet.

agentoast config

Editor resolution priority is config.toml editor field → $EDITOR → vim

# agentoast configuration

# Editor to open when running `agentoast config`
# Falls back to $EDITOR environment variable, then vim
# editor = "vim"

# Toast popup notification
[toast]
# Display duration in milliseconds (default: 4000)
# duration_ms = 4000

# Keep toast visible until clicked (default: false)
# persistent = false

# Notification settings
[notification]
# Mute all notifications (default: false)
# muted = false

# Show only groups with notifications (default: false)
# filter_notified_only = false

# Claude Code agent settings
[notification.agents.claude_code]
# Events that trigger notifications
# Available: Stop, permission_prompt, idle_prompt, auth_success, elicitation_dialog, TeammateIdle, TaskCompleted
# idle_prompt, TeammateIdle, TaskCompleted are excluded by default
# events = ["Stop", "permission_prompt", "auth_success", "elicitation_dialog"]

# Events that auto-focus the terminal (default: none)
# These events set force_focus=true, causing silent terminal focus without toast (when not muted)
# focus_events = []

# Include last-assistant-message as notification body (default: true, truncated to 200 chars)
# include_body = true

# Codex agent settings
[notification.agents.codex]
# Events that trigger notifications
# Available: agent-turn-complete
# events = ["agent-turn-complete"]

# Events that auto-focus the terminal (default: none)
# focus_events = []

# Include last-assistant-message as notification body (default: true, truncated to 200 chars)
# include_body = true

# OpenCode agent settings
[notification.agents.opencode]
# Events that trigger notifications
# Available: session.status (idle only), session.error, permission.asked
# events = ["session.status", "session.error", "permission.asked"]

# Events that auto-focus the terminal (default: none)
# focus_events = []

# Copilot CLI agent settings
[notification.agents.copilot_cli]
# Events that trigger notifications
# Available: agentStop, subagentStop, errorOccurred
# events = ["agentStop"]

# Events that auto-focus the terminal (default: none)
# focus_events = []

# Include error message as notification body (default: true, truncated to 200 chars)
# include_body = true

# Keyboard shortcuts
[keybinding]
# Shortcut to toggle the notification panel (default: super+ctrl+n)
# Format: modifier+key (modifiers: ctrl, shift, alt/option, super/cmd)
# Set to "" to disable
# toggle_panel = "super+ctrl+n"

# System settings
# Override auto-detected binary paths (useful when auto-detection fails)
# [system]
# tmux = "/custom/path/to/tmux"
# git = "/custom/path/to/git"

System Binary Paths

agentoast auto-detects tmux and git by searching in this order.

1. Well-known paths — Homebrew (Apple Silicon / Intel), system (/usr/bin)
2. Nix paths — Home Manager (/etc/profiles/per-user/$USER/bin/), single-user (/nix/var/nix/profiles/default/bin/)
3. $PATH fallback — scans $PATH entries (mise, asdf, etc.)

Note: The $PATH fallback only works when the app is launched from a terminal. Finder / Dock / Spotlight launches do not inherit the shell $PATH.

If auto-detection fails (Sessions panel is empty), override the path in config.toml.

[system]
tmux = "/your/custom/path/to/tmux"
git = "/your/custom/path/to/git"

Keyboard Shortcuts

Panel shortcuts (press ? in the panel to see this list).

The global shortcut to toggle the panel is Cmd+Ctrl+N (configurable in config.toml).

Notification

Integration

Ready-to-use integration scripts are provided for each agent. All agents use built-in CLI subcommands (agentoast hook claude / agentoast hook codex / agentoast hook opencode). opencode uses its plugin system to receive events, then delegates to the CLI subcommand. See examples/notify/ for source code.

Claude Code

~/.claude/settings.json

{
  "hooks": {
    "Stop": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "agentoast hook claude"
          }
        ]
      }
    ],
    "Notification": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "agentoast hook claude"
          }
        ]
      }
    ]
  }
}

No Deno dependency required. The CLI reads hook data from stdin and writes directly to the notification database. See examples/notify/claude.ts for a Deno-based alternative.

Codex

~/.codex/config.toml

notify = [
  "agentoast hook codex",
]

No Deno dependency required. The CLI reads hook data from the last command-line argument and writes directly to the notification database. See examples/notify/codex.ts for a Deno-based alternative.

opencode

Drop the plugin file into ~/.config/opencode/plugins/ and it gets picked up automatically. The plugin forwards all events to agentoast hook opencode. Event filtering and notification mapping are configured in config.toml [notification.agents.opencode].

mkdir -p ~/.config/opencode/plugins
cp examples/notify/opencode.ts ~/.config/opencode/plugins/

Supported events

Copilot CLI

~/.copilot/config.json (global) or .github/hooks/*.json (per-repo):

{
  "hooks": {
    "agentStop": [
      {
        "type": "command",
        "bash": "agentoast hook copilot --event agentStop",
        "timeoutSec": 10
      }
    ],
    "errorOccurred": [
      {
        "type": "command",
        "bash": "agentoast hook copilot --event errorOccurred",
        "timeoutSec": 10
      }
    ]
  }
}

Unlike other agents, Copilot CLI configures separate hook entries per event. The --event flag tells agentoast which event triggered the hook. The notification body is extracted from the session transcript (events.jsonl).

Supported events

Send Notification

agentoast send \
  --badge "Stop" \
  --body "Task Completed" \
  --badge-color green \
  --icon claude-code \
  --repo my-repo \
  --tmux-pane %0 \
  --meta branch=main

Clicking a notification dismisses it and brings you back to the terminal. With --tmux-pane, all notifications sharing the same --tmux-pane are dismissed at once. Sending a new notification with the same --tmux-pane replaces the previous one, so only the latest notification per pane is kept.

When a terminal is focused and the notification's originating tmux pane is the active pane, notifications are automatically suppressed — since you're already looking at it.

For a quick test, you can fire off notifications straight from the CLI.

Claude Code

agentoast send \
  --badge "Stop" \
  --badge-color green \
  --icon claude-code \
  --repo your-repo \
  --tmux-pane %0 \
  --meta branch=your-branch

Codex (OpenAI)

agentoast send \
  --badge "Notification" \
  --badge-color blue \
  --icon codex \
  --repo your-repo \
  --meta branch=your-branch

opencode

agentoast send \
  --badge "Stop" \
  --badge-color green \
  --icon opencode \
  --repo your-repo \
  --tmux-pane %0 \
  --meta branch=your-branch

Tips

Set up a shell alias for command completion notifications. With --tmux-pane, clicking the notification jumps back to the pane.

alias an='agentoast send --badge Done --badge-color green --tmux-pane "$TMUX_PANE"'

sleep 10; an -b "body"