convez.ai
AgenteProdutividadeIntermediário
shuntaka9576

AgentOast

shuntaka9576/agentoast

Notificações toast para agentes de IA no menu bar do macOS com tmux

Ver no GitHub
BomPluginScore · de 0 a 100

App de menu bar para macOS que notifica quando agentes de IA (Claude Code, Codex, Copilot CLI) terminam tarefas ou precisam de entrada. Integra-se com tmux para permitir pular diretamente para o pane relevante com um clique, sem perder o momento crítico.

Instalação

$npx convez-ai shuntaka9576/agentoast

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
28
Forks
1
Acompanhando
1
Saúde
42%
Último commit
há 1 dia
Versão
v0.51.0
Issues abertas
6
Contribuidores
3

Casos de uso

  • Monitorar conclusão de tarefas longas de agentes de IA enquanto trabalha em outra janela
  • Receber alertas quando agentes pedem permissão ou input do usuário
  • Alternar rapidamente para o pane tmux correto ao ser notificado de um evento de agente

Veredito

Ferramenta especializada e bem executada para desenvolvedores que usam agentes de IA com tmux no macOS. Resolve um problema real: não perder notificações críticas enquanto alterna entre janelas. Implementação em Rust garante performance, mas uso é restrito ao ecossistema específico (macOS + tmux + agentes suportados).

README

A tradução para o português deste README ainda está na fila.

main

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.

toast

Requirements

CommandPurposeRequired
tmuxSession/pane management, agent statusYes

Repository and branch info is read directly from .git metadata, and the process tree is read via native macOS APIs — neither the git binary nor ps is required.

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

Installation

brew install --cask shuntaka9576/tap/agentoast

This installs the menu bar app and the agentoast CLI in one step.

Or download the DMG from Releases.

To uninstall:

brew uninstall --cask shuntaka9576/tap/agentoast

Usage

Works With

AgentHook ConfigEventsStatus Detection
Claude Code~/.claude/settings.jsonStop, Permission, Auth, ElicitationRunning / Idle / Waiting / Agent Teams
Codex~/.codex/config.tomlTurn CompleteRunning / Idle / Waiting
Copilot CLI.github/hooks/*.jsonAgent Stop, ErrorRunning / Idle / Waiting
opencodePlugin (~/.config/opencode/plugins/)Session Idle, Error, PermissionRunning / Idle / Waiting
🚧 Kiro CLI———

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

For the most common options (toast duration, global shortcut, auto-update, editor), you can also right-click the menu bar icon and choose Settings… to open a GUI editor. Changes are written back to config.toml; most take effect after a restart, and a banner with a Quit & Relaunch button is shown when needed.

# 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

# Show tmux panes without an AI coding agent (default: false)
# show_non_agent_panes = 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 the auto-detected tmux binary path (useful when auto-detection fails)
# [system]
# tmux = "/custom/path/to/tmux"

System Binary Paths

agentoast auto-detects tmux 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"

Keyboard Shortcuts

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

KeyAction
j / kNext / Previous
EnterOpen / Fold
dDelete notif
DDelete all notifs
C / ECollapse all / Expand all
FFilter notified
Tab / Shift+TabJump to next / prev notified pane
EscClose
?Help

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/

Note: Earlier versions of examples/notify/opencode.ts included development-time debug logging that wrote every opencode event to /tmp/opencode-notify-debug.log, growing without bound. If you installed the plugin before this was fixed, re-copy the plugin and remove the stale log:

cp examples/notify/opencode.ts ~/.config/opencode/plugins/
rm -f /tmp/opencode-notify-debug.log

Supported events

EventNotification
session.status (idle)Stop (green)
session.errorError (red)
permission.askedPermission (blue)
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

EventNotification
agentStopStop (green)
subagentStopStop (green)
errorOccurredError (red)

Send Notification

agentoast send \
  --badge "Stop" \
  --body "Task Completed" \
  --badge-color green \
  --icon claude-code \
  --repo my-repo \
  --tmux-pane %0 \
  --meta branch=main
OptionShortRequiredDefaultDescription
--badge-BNo""Badge text displayed on notification card
--body-bNo""Notification body text
--badge-color-cNograyBadge color (green, blue, red, gray)
--icon-iNoagentoastIcon preset (agentoast / claude-code / codex / copilot-cli / opencode)
--repo-rNoautoRepository name for grouping notifications. Auto-detected from git remote or directory name if omitted
--tmux-pane-tNo""tmux pane ID. Used for focus-on-click and batch dismiss (e.g. %0)
--bundle-id—NoautoTerminal bundle ID for focus-on-click (e.g. com.github.wez.wezterm). Auto-detected from __CFBundleIdentifier env var if not specified
--focus-fNofalseFocus terminal automatically when notification is sent. A toast is shown with "Focused: no history" label, but the notification does not appear in the notification history
--meta-mNo-Display metadata as key=value pairs (can be specified multiple times). Shown on notification cards

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

Cross-Agent Messaging (Experimental)

Experimental: This feature and its skill packaging are still evolving and may change or be removed without notice.

agentoast send-keys injects a message straight into another agent's prompt running in a different tmux pane, addressed only by its pane id (e.g. %72) — no team, login, or registration. Your own pane ($TMUX_PANE) is appended as a reply address, so the receiving agent can answer back into your pane.

agentoast send-keys --pane %72 "Please review the diff on this branch"
OptionShortDefaultDescription
--pane-t(required)Target tmux pane id (e.g. %72)
--from—$TMUX_PANESender pane id embedded as the reply address
--raw—falseInject the raw message only, without the reply hint
--no-enter—falseType the text without submitting (no trailing Enter)
--force—falseSend even when the target pane runs no detected agent

By default send-keys refuses a target pane that has no detected AI agent (a plain shell), since the message would just be typed into the shell prompt — usually a sign you picked the wrong pane. Pass --force when you are sure an agent is running there but the detector doesn't recognize it.

To let an agent drive this on its own (delegate a task, hand off, or reply to incoming messages), install the bundled agentoast-send skill with apm.

apm install shuntaka9576/agentoast -t claude

This deploys the skill to .claude/skills/. Once installed, asking your agent to "ask the agent in pane %72 to review this" routes through send-keys automatically.

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"
Ver o original no GitHub

Bom para

Relacionados