Set up local coding agent notifications in 2-3 minutes for Feishu/Lark, Slack, Discord, Telegram, Microsoft Teams, email, ntfy, Pushover, webhook, WhatsApp, or WeChat. Feishu/Lark Personal Agent can also turn project rooms into a two-way Codex Desktop control surface; thread replies are Experimental.

中文文档：docs/README.zh-CN.md

Quick start

"Imagine Codex Desktop App keeps working while you make coffee or do laundry.

The moment the job finishes, you get a notification and know it is time to come back."

⚡ Local-first signal routing for AI coding agents.

Built for local agents like Codex Desktop, Codex CLI, Claude Code, GitHub Copilot CLI, Gemini CLI, Aider, Cursor CLI, OpenCode CLI, OpenClaw, and Hermes Agent CLI.

Built in Rust 🦀. Fast, small, and quiet in the background.

Agent on your computer -> Agents Router -> Your provider

No cloud account. No hosted backend. No extra dashboard.

✅ Support

Agents:

Codex Desktop on macOS and Windows
Codex CLI through hooks on macOS, Linux, and Windows
Claude Code through hooks on macOS, Linux, and Windows
GitHub Copilot CLI through hooks on macOS, Linux, and Windows
Gemini CLI through hooks on macOS, Linux, and Windows
Aider through notification commands on macOS, Linux, and Windows
Cursor CLI through a completion wrapper on macOS, Linux, and Windows
OpenCode CLI through plugins on macOS, Linux, and Windows
OpenClaw through plugin hooks on macOS, Linux, and Windows
Hermes Agent CLI through plugin hooks on macOS, Linux, and Windows

Providers (Where do you want to get the notification?):

Feishu/Lark Personal Agent; QR setup, project rooms, and Experimental Codex Desktop thread replies (guide)
Slack
Discord
Telegram
Microsoft Teams
Email SMTP
ntfy
Pushover
Feishu/Lark Custom Bot fallback (Feishu, Lark)
Webhook
WhatsApp
WeChat personal chat through iLink

🔒 Privacy

Agents Router runs locally.

Your data does not go to an Agents Router cloud.

Notifications go directly from your computer to your provider.

For Codex Desktop, it reads only completion data needed for the notification:

project
project path
session
Codex thread link
duration
branch
time
final answer preview by default, or full answer when enabled
prompt only when explicitly enabled
computer name

In Feishu/Lark, notifications are sent as Codex-colored interactive cards with a clickable Open in Codex button. The button opens a local browser URL first, then hands off to Codex Desktop.

⚙️ Install - Step 1

Pick one install method. That is enough.

Recommended:

Copy this into your Terminal:

npx --yes --prefer-online agents-router@latest setup

Prefer a persistent npm install:

npm install -g agents-router
agents-router setup

Without Node.js/npm:

curl -fsSL https://raw.githubusercontent.com/lumpinif/agents-router/main/install.sh | sh
agents-router setup

Windows PowerShell:

irm https://raw.githubusercontent.com/lumpinif/agents-router/main/install.ps1 | iex
agents-router setup

To upgrade later, rerun the same install method you used the first time. If the local service is already running, the installer restarts it after replacing the binary so the background service uses the new version too.

From source:

git clone https://github.com/lumpinif/agents-router.git
cd agents-router
cargo install --path .
agents-router setup

🚀 Setup - Step 2

agents-router setup

First choose the CLI language. English is the default, and Simplified Chinese is available.

Then setup asks for three choices:

Which agent should it watch?
Where should notifications go?
Which completed tasks should send notifications?

Then it writes config and starts the service. Providers with a fixed destination send a test notification. Feishu/Lark Personal Agent does not choose a single room during setup: scan the QR code, then use direct chat with /new /absolute/project/path what you want Codex to do to start a new Codex thread, or use /bind /absolute/project/path to choose where that project should send updates. You can also add the Personal Agent to a room, mention it, and send /bind /absolute/project/path to connect that room directly. If Codex later updates an unconnected project, Agents Router can ask you in direct chat whether to create a room, use an existing room, or ignore that project.

For optional settings such as answer detail, prompt inclusion, and advanced project filters, see Setup.

Use Feishu/Lark Personal Agent when you want the two-way project-room experience. Use Feishu/Lark Custom Bot only when you want a simple one-way fallback.

🎉 That's it

The service runs locally:

macOS: LaunchAgent
Linux: systemd user service
Windows: Task Scheduler

To stop using the service, run agents-router stop.

Provider setup guides:

Agent setup guides:

🧹 Uninstall

Remove Agents Router cleanly:

npx --yes agents-router uninstall

If you installed it globally with npm, remove the npm package after local cleanup:

agents-router uninstall
npm uninstall -g agents-router

🧭 Commands

agents-router setup    # set up or change agent/provider
agents-router start    # start existing service
agents-router status   # check service status
agents-router safety reset # clear delivery safety pause state
agents-router stop     # stop service
agents-router uninstall # remove service, config, logs, and state
agents-router watch    # foreground debug worker

For Codex CLI, Agents Router installs the recommended Stop hook automatically when the active config includes codex_cli. Manual CLI hooks can submit events with:

agents-router ingest --source codex_cli --format codex_cli_stop

Codex Desktop and Codex CLI may be enabled together. If the shared Codex Stop hook fires for a session that Agents Router can identify as Codex Desktop, the hook is ignored and the Desktop watcher handles that completion.

Agents Router also has a delivery safety guard. If the same logical message is sent to the same provider 5 times within 10 seconds, that message line is suppressed. If 3 different message lines trigger suppression within 2 minutes, provider delivery pauses until you run agents-router safety reset. Suppressed notifications are intentionally dropped, not delayed for later replay.

agents-router emit \
  --source claude_code \
  --title "Claude Code" \
  --body "Claude Code finished a task."

agents-router emit \
  --source opencode_cli \
  --title "OpenCode CLI" \
  --body "OpenCode CLI finished a task."

agents-router emit \
  --source gemini_cli \
  --title "Gemini CLI" \
  --body "Gemini CLI finished a task."

emit only talks to the local service. Providers are sent by the service.

✨ Example

Codex Desktop + Lark integration, including Apple Watch push notifications.

Original source: Codex Desktop	Lark desktop notification

Lark push preview	Apple Watch notification

Codex Desktop

Project: agents-router
Session: README polish
Open in Codex: codex://threads/019e1049-2d6d-7de2-bcdf-f47346930b71
Duration: 1m 32s
Branch: main
Time: 2026-05-10 01:35:42 +08:00
Session ID: 019e1049-2d6d-7de2-bcdf-f47346930b71

Preview: Updated the README with a clearer setup flow...