{"id":44585518,"url":"https://github.com/shuntaka9576/agentoast","last_synced_at":"2026-05-11T05:01:32.681Z","repository":{"id":338361729,"uuid":"1157598458","full_name":"shuntaka9576/agentoast","owner":"shuntaka9576","description":"🍞 Toast notifications from AI coding agents on your macOS menu bar, with tmux pane switching","archived":false,"fork":false,"pushed_at":"2026-04-17T12:56:24.000Z","size":24811,"stargazers_count":14,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-17T14:37:40.233Z","etag":null,"topics":["anthropic","claude","claude-ai","claude-code","codex","openai","opencode","tmux"],"latest_commit_sha":null,"homepage":"","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/shuntaka9576.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-02-14T02:39:48.000Z","updated_at":"2026-04-17T12:56:13.000Z","dependencies_parsed_at":"2026-02-20T05:01:16.943Z","dependency_job_id":null,"html_url":"https://github.com/shuntaka9576/agentoast","commit_stats":null,"previous_names":["shuntaka9576/agentoast"],"tags_count":54,"template":false,"template_full_name":null,"purl":"pkg:github/shuntaka9576/agentoast","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shuntaka9576%2Fagentoast","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shuntaka9576%2Fagentoast/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shuntaka9576%2Fagentoast/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shuntaka9576%2Fagentoast/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/shuntaka9576","download_url":"https://codeload.github.com/shuntaka9576/agentoast/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shuntaka9576%2Fagentoast/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32076296,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-21T02:38:07.213Z","status":"ssl_error","status_checked_at":"2026-04-21T02:38:06.559Z","response_time":128,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["anthropic","claude","claude-ai","claude-code","codex","openai","opencode","tmux"],"created_at":"2026-02-14T06:04:22.410Z","updated_at":"2026-04-25T02:05:16.769Z","avatar_url":"https://github.com/shuntaka9576.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n  \u003cimg src=\"src-tauri/icons/128x128.png\" width=\"96\" alt=\"agentoast icon\" /\u003e\n  \u003ch1\u003eagentoast\u003c/h1\u003e\n  \u003cp\u003e\n    \u003cimg alt=\"macOS\" src=\"https://img.shields.io/badge/macOS-000?logo=apple\u0026logoColor=white\" /\u003e\n  \u003c/p\u003e\n\u003c/div\u003e\n\n![main](docs/assets/main.gif)\n\nA 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.\n\nYou 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.\n\nAdd a [hook](#integration) to your agent's config. All notifications are grouped by repository in the menu bar — clicking one takes you straight to its tmux pane.\n\n\u003cimg src=\"docs/assets/menubar.png\" width=\"400\" alt=\"menubar\" /\u003e\n\nA toast pops up whenever an agent completes or needs attention — click it to jump right back to the tmux pane.\n\n![toast](docs/assets/toast.gif)\n\n\u003cimg src=\"docs/assets/toast.png\" width=\"400\" alt=\"toast\" /\u003e\n\n## Requirements\n\n| Command | Purpose                                | Required |\n| ------- | -------------------------------------- | -------- |\n| `tmux`  | Session/pane management, agent status  | Yes      |\n| `git`   | Repository detection, branch info      | Yes      |\n| `ps`    | Agent process detection (process tree) | Built-in |\n\nagentoast auto-detects binary paths by searching well-known locations (Homebrew, system, Nix). If the Sessions panel is empty, see the [`[system]` config](#system-binary-paths) to set paths manually.\n\n## Installation\n\n```bash\nbrew install --cask shuntaka9576/tap/agentoast\n```\n\nThis installs the menu bar app and the `agentoast` CLI in one step.\n\nOr download the DMG from [Releases](https://github.com/shuntaka9576/agentoast/releases).\n\nTo uninstall:\n\n```bash\nbrew uninstall --cask shuntaka9576/tap/agentoast\n```\n\n## Usage\n\n### Works With\n\n| Agent                                                    | Hook Config                            | Events                              | Status Detection                       |\n| -------------------------------------------------------- | -------------------------------------- | ----------------------------------- | -------------------------------------- |\n| [Claude Code](https://github.com/anthropics/claude-code) | `~/.claude/settings.json`              | Stop, Permission, Auth, Elicitation | Running / Idle / Waiting / Agent Teams |\n| [Codex](https://github.com/openai/codex)                 | `~/.codex/config.toml`                 | Turn Complete                       | Running / Idle / Waiting               |\n| [Copilot CLI](https://github.com/github/copilot-cli)     | `.github/hooks/*.json`                 | Agent Stop, Error                   | Running / Idle / Waiting               |\n| [opencode](https://github.com/anomalyco/opencode)        | Plugin (`~/.config/opencode/plugins/`) | Session Idle, Error, Permission     | Running / Idle / Waiting               |\n| 🚧 [Kiro CLI](https://github.com/aws/kiro-cli)           | —                                      | —                                   | —                                      |\n\nAll agents utilize the built-in CLI (`agentoast hook \u003cagent\u003e`). See the [Integration](#integration) section for setup details. If you'd like to see support for other agents, please feel free to [open an issue](https://github.com/shuntaka9576/agentoast/issues).\n\n### Config\n\nOpens `~/.config/agentoast/config.toml` in your editor, creating a default one if it doesn't exist yet.\n\n```bash\nagentoast config\n```\n\nEditor resolution priority is `config.toml` `editor` field → `$EDITOR` → `vim`\n\nFor 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 \u0026 Relaunch** button is shown when needed.\n\n```toml\n# agentoast configuration\n\n# Editor to open when running `agentoast config`\n# Falls back to $EDITOR environment variable, then vim\n# editor = \"vim\"\n\n# Toast popup notification\n[toast]\n# Display duration in milliseconds (default: 4000)\n# duration_ms = 4000\n\n# Keep toast visible until clicked (default: false)\n# persistent = false\n\n# Notification settings\n[notification]\n# Mute all notifications (default: false)\n# muted = false\n\n# Show only groups with notifications (default: false)\n# filter_notified_only = false\n\n# Show tmux panes without an AI coding agent (default: false)\n# show_non_agent_panes = false\n\n# Claude Code agent settings\n[notification.agents.claude_code]\n# Events that trigger notifications\n# Available: Stop, permission_prompt, idle_prompt, auth_success, elicitation_dialog, TeammateIdle, TaskCompleted\n# idle_prompt, TeammateIdle, TaskCompleted are excluded by default\n# events = [\"Stop\", \"permission_prompt\", \"auth_success\", \"elicitation_dialog\"]\n\n# Events that auto-focus the terminal (default: none)\n# These events set force_focus=true, causing silent terminal focus without toast (when not muted)\n# focus_events = []\n\n# Include last-assistant-message as notification body (default: true, truncated to 200 chars)\n# include_body = true\n\n# Codex agent settings\n[notification.agents.codex]\n# Events that trigger notifications\n# Available: agent-turn-complete\n# events = [\"agent-turn-complete\"]\n\n# Events that auto-focus the terminal (default: none)\n# focus_events = []\n\n# Include last-assistant-message as notification body (default: true, truncated to 200 chars)\n# include_body = true\n\n# OpenCode agent settings\n[notification.agents.opencode]\n# Events that trigger notifications\n# Available: session.status (idle only), session.error, permission.asked\n# events = [\"session.status\", \"session.error\", \"permission.asked\"]\n\n# Events that auto-focus the terminal (default: none)\n# focus_events = []\n\n# Copilot CLI agent settings\n[notification.agents.copilot_cli]\n# Events that trigger notifications\n# Available: agentStop, subagentStop, errorOccurred\n# events = [\"agentStop\"]\n\n# Events that auto-focus the terminal (default: none)\n# focus_events = []\n\n# Include error message as notification body (default: true, truncated to 200 chars)\n# include_body = true\n\n# Keyboard shortcuts\n[keybinding]\n# Shortcut to toggle the notification panel (default: super+ctrl+n)\n# Format: modifier+key (modifiers: ctrl, shift, alt/option, super/cmd)\n# Set to \"\" to disable\n# toggle_panel = \"super+ctrl+n\"\n\n# System settings\n# Override auto-detected binary paths (useful when auto-detection fails)\n# [system]\n# tmux = \"/custom/path/to/tmux\"\n# git = \"/custom/path/to/git\"\n```\n\n#### System Binary Paths\n\nagentoast auto-detects `tmux` and `git` by searching in this order.\n\n1. **Well-known paths** — Homebrew (Apple Silicon / Intel), system (`/usr/bin`)\n2. **Nix paths** — Home Manager (`/etc/profiles/per-user/$USER/bin/`), single-user (`/nix/var/nix/profiles/default/bin/`)\n3. **`$PATH` fallback** — scans `$PATH` entries (mise, asdf, etc.)\n\n\u003e **Note:** The `$PATH` fallback only works when the app is launched from a terminal. Finder / Dock / Spotlight launches do not inherit the shell `$PATH`.\n\nIf auto-detection fails (Sessions panel is empty), override the path in `config.toml`.\n\n```toml\n[system]\ntmux = \"/your/custom/path/to/tmux\"\ngit = \"/your/custom/path/to/git\"\n```\n\n### Keyboard Shortcuts\n\nPanel shortcuts (press `?` in the panel to see this list).\n\n| Key                 | Action                            |\n| ------------------- | --------------------------------- |\n| `j` / `k`           | Next / Previous                   |\n| `Enter`             | Open / Fold                       |\n| `d`                 | Delete notif                      |\n| `D`                 | Delete all notifs                 |\n| `C` / `E`           | Collapse all / Expand all         |\n| `F`                 | Filter notified                   |\n| `Tab` / `Shift+Tab` | Jump to next / prev notified pane |\n| `Esc`               | Close                             |\n| `?`                 | Help                              |\n\nThe global shortcut to toggle the panel is `Cmd+Ctrl+N` (configurable in `config.toml`).\n\n### Notification\n\n#### Integration\n\nReady-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](https://opencode.ai/docs/plugins) to receive events, then delegates to the CLI subcommand. See [`examples/notify/`](examples/notify/) for source code.\n\n##### Claude Code\n\n`~/.claude/settings.json`\n\n```json\n{\n  \"hooks\": {\n    \"Stop\": [\n      {\n        \"matcher\": \"\",\n        \"hooks\": [\n          {\n            \"type\": \"command\",\n            \"command\": \"agentoast hook claude\"\n          }\n        ]\n      }\n    ],\n    \"Notification\": [\n      {\n        \"matcher\": \"\",\n        \"hooks\": [\n          {\n            \"type\": \"command\",\n            \"command\": \"agentoast hook claude\"\n          }\n        ]\n      }\n    ]\n  }\n}\n```\n\nNo Deno dependency required. The CLI reads hook data from stdin and writes directly to the notification database. See [`examples/notify/claude.ts`](examples/notify/claude.ts) for a Deno-based alternative.\n\n##### Codex\n\n`~/.codex/config.toml`\n\n```toml\nnotify = [\n  \"agentoast hook codex\",\n]\n```\n\nNo 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`](examples/notify/codex.ts) for a Deno-based alternative.\n\n##### opencode\n\nDrop 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]`.\n\n```bash\nmkdir -p ~/.config/opencode/plugins\ncp examples/notify/opencode.ts ~/.config/opencode/plugins/\n```\n\nSupported events\n\n| Event                   | Notification      |\n| ----------------------- | ----------------- |\n| `session.status` (idle) | Stop (green)      |\n| `session.error`         | Error (red)       |\n| `permission.asked`      | Permission (blue) |\n\n##### Copilot CLI\n\n`~/.copilot/config.json` (global) or `.github/hooks/*.json` (per-repo):\n\n```json\n{\n  \"hooks\": {\n    \"agentStop\": [\n      {\n        \"type\": \"command\",\n        \"bash\": \"agentoast hook copilot --event agentStop\",\n        \"timeoutSec\": 10\n      }\n    ],\n    \"errorOccurred\": [\n      {\n        \"type\": \"command\",\n        \"bash\": \"agentoast hook copilot --event errorOccurred\",\n        \"timeoutSec\": 10\n      }\n    ]\n  }\n}\n```\n\nUnlike 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`).\n\nSupported events\n\n| Event           | Notification |\n| --------------- | ------------ |\n| `agentStop`     | Stop (green) |\n| `subagentStop`  | Stop (green) |\n| `errorOccurred` | Error (red)  |\n\n#### Send Notification\n\n```bash\nagentoast send \\\n  --badge \"Stop\" \\\n  --body \"Task Completed\" \\\n  --badge-color green \\\n  --icon claude-code \\\n  --repo my-repo \\\n  --tmux-pane %0 \\\n  --meta branch=main\n```\n\n| Option          | Short | Required | Default     | Description                                                                                                                                                                 |\n| --------------- | ----- | -------- | ----------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `--badge`       | `-B`  | No       | `\"\"`        | Badge text displayed on notification card                                                                                                                                   |\n| `--body`        | `-b`  | No       | `\"\"`        | Notification body text                                                                                                                                                      |\n| `--badge-color` | `-c`  | No       | `gray`      | Badge color (`green`, `blue`, `red`, `gray`)                                                                                                                                |\n| `--icon`        | `-i`  | No       | `agentoast` | Icon preset (`agentoast` / `claude-code` / `codex` / `copilot-cli` / `opencode`)                                                                                            |\n| `--repo`        | `-r`  | No       | auto        | Repository name for grouping notifications. Auto-detected from git remote or directory name if omitted                                                                      |\n| `--tmux-pane`   | `-t`  | No       | `\"\"`        | tmux pane ID. Used for focus-on-click and batch dismiss (e.g. `%0`)                                                                                                         |\n| `--bundle-id`   | —     | No       | auto        | Terminal bundle ID for focus-on-click (e.g. `com.github.wez.wezterm`). Auto-detected from `__CFBundleIdentifier` env var if not specified                                   |\n| `--focus`       | `-f`  | No       | `false`     | Focus 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 |\n| `--meta`        | `-m`  | No       | -           | Display metadata as key=value pairs (can be specified multiple times). Shown on notification cards                                                                          |\n\nClicking 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.\n\nWhen 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.\n\nFor a quick test, you can fire off notifications straight from the CLI.\n\nClaude Code\n\n```bash\nagentoast send \\\n  --badge \"Stop\" \\\n  --badge-color green \\\n  --icon claude-code \\\n  --repo your-repo \\\n  --tmux-pane %0 \\\n  --meta branch=your-branch\n```\n\nCodex (OpenAI)\n\n```bash\nagentoast send \\\n  --badge \"Notification\" \\\n  --badge-color blue \\\n  --icon codex \\\n  --repo your-repo \\\n  --meta branch=your-branch\n```\n\nopencode\n\n```bash\nagentoast send \\\n  --badge \"Stop\" \\\n  --badge-color green \\\n  --icon opencode \\\n  --repo your-repo \\\n  --tmux-pane %0 \\\n  --meta branch=your-branch\n```\n\n### Tips\n\nSet up a shell alias for command completion notifications. With `--tmux-pane`, clicking the notification jumps back to the pane.\n\n```bash\nalias an='agentoast send --badge Done --badge-color green --tmux-pane \"$TMUX_PANE\"'\n```\n\n```bash\nsleep 10; an -b \"body\"\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fshuntaka9576%2Fagentoast","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fshuntaka9576%2Fagentoast","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fshuntaka9576%2Fagentoast/lists"}