Agent Monitor

A web dashboard to run, monitor, and manage Claude Code and Codex agents in one place. Create agents with a cloneable task template. Real-time streaming, task pipelines, and notifications via Email / WhatsApp / Slack — all from your browser.

Documentation | Quick Start

Key Features

Spin Up Agents Instantly with Cloneable Templates

Clone agent — Duplicate any agent's configuration (directory, provider, flags, CLAUDE.md) to instantly spin up a new one with the same setup — no re-entering settings
CLAUDE.md templates — Create reusable instruction sets and load them when spawning agents or pipeline tasks
Auto-detect CLAUDE.md — When selecting a project directory, automatically detects an existing CLAUDE.md and offers to load it
Live editing — Modify an agent's CLAUDE.md at any time without restarting

Multi-Agent Orchestration

Unified dashboard — Create, monitor, and manage Claude Code and Codex agents from a single interface
Task pipelines — Define sequential and parallel task workflows; the built-in Meta Agent Manager automates execution end-to-end (validates pending tasks before start)
Git worktree isolation — When the working directory is a git repo, each agent operates in its own worktree branch, preventing conflicts. Non-git directories are used directly with no worktree overhead

External Agent Discovery

Auto-detect running agents — Claude Code and Codex processes started outside the dashboard (e.g., from a terminal) are automatically discovered and displayed with an EXT badge
Full integration — External agents can be monitored, chatted with, and managed just like agents created through the UI
Toggle visibility — Show or hide external agents on the dashboard with a single click; preference persists across sessions

Real-Time Monitoring & Interaction

Live streaming — Watch agent output in real-time over WebSocket (works locally and through relay), with automatic polling fallback
PTY web terminal — Toggle a fully interactive shell (node-pty + xterm.js) in the agent's working directory — run any command, launch claude, or debug directly from the browser
Web chat interface — Structured chat view with 25+ slash commands matching CLI behavior; both interfaces coexist and you can switch freely
Session resume — Send a message to a stopped agent to automatically restart it with --resume, continuing the conversation with full history
Clone agent — Duplicate an existing agent's configuration to quickly create a new one with the same settings
Interactive prompts — When an agent needs input (permission prompts, choices), the web UI shows notification banners and clickable choice buttons
Cost & token tracking — Per-agent cost (Claude) and token usage (Codex) displayed in real time
Double-Esc interrupt — Press Escape twice to send SIGINT to any running agent
Auto-delete expired agents — Configurable retention period for stopped agents (default 24h, adjustable in Settings)

Notifications — Email, WhatsApp & Slack

Stay informed wherever you are. Agent Monitor sends instant notifications when agents need human attention.

Channel	Provider	Setup
Email	Any SMTP server (Gmail, Outlook, Mailgun, etc.)	Configure `SMTP_*` environment variables
WhatsApp	Twilio API	Configure `TWILIO_*` environment variables
Slack	Slack Incoming Webhooks	Configure `SLACK_WEBHOOK_URL` or per-agent webhook
Feishu (Lark)	Feishu Open Platform (WebSocket bot)	Configure `FEISHU_` variables — sends interactive cards with reply buttons*

Notifications are triggered when:

An agent enters waiting_input state and needs human intervention
A pipeline task fails
A stuck agent exceeds the configurable timeout threshold
The entire pipeline completes

All channels can be enabled simultaneously — configure an admin email, WhatsApp phone number, and/or Slack webhook per agent or globally for the Agent Manager.

See the Notifications Guide for detailed setup instructions.

Feishu (Lark) Bot & Notifications

Chat with your agents and receive rich interactive alerts directly in Feishu. The bot connects via WebSocket — no public URL required — and displays live, updateable agent cards with clickable choice buttons for permission prompts and pipeline alerts.

Remote Access via Relay Server

Access from anywhere — Manage agents from your phone, laptop, or any device through a public relay server
Secure WebSocket tunnel — The agent machine connects outbound to the relay; no inbound ports needed
Batch remote agents — Run and monitor dozens of agents on a powerful remote machine while controlling them from any lightweight device
Password-protected dashboard — JWT-based authentication with 24-hour session expiry
Auto-reconnect — Tunnel reconnects automatically if the connection drops (exponential backoff)
Zero overhead locally — When relay is not configured, the server runs in local-only mode with no extra cost

Phone / Laptop ──HTTP──▶ Public Server (Relay :3457) ◀──WS tunnel── Agent Machine (:3456)

See the Remote Access Guide for setup instructions.

Internationalization

7 languages: English, Chinese (中文), Japanese (日本語), Korean (한국어), Spanish, French, German
Language selector persisted across sessions

Demo

Quick Start — Create Agent with Template

Create agent with CLAUDE.md template → agent runs autonomously → task completes

Chat & Terminal

Interactive chat → agent responds with tool calls → PTY terminal → clone agent

Task Pipeline

Agent Manager: add tasks → start manager → watch agents run sequentially

Screenshots

Dashboard	Task Pipeline

Create Agent	Agent Chat

Templates	Multi-Language Support

PTY Web Terminal
	Interactive shell in the agent's working directory — run commands, launch `claude`, or debug directly from your browser (works locally and via relay)

Quick Start

Prerequisites

Node.js >= 18
Claude Code CLI (claude) — for Claude agents
Codex CLI (codex) — for Codex agents
Git — for worktree isolation (optional; non-git directories work without it)

Installation

git clone <repo-url> && cd AgentMonitor
npm install
cd server && npm install && cd ..
cd client && npm install && cd ..

Production

cd client && npx vite build && cd ..
cd server && npx tsx src/index.ts

Open http://localhost:3456 in your browser.

Development

npm run dev    # Starts server (tsx watch) + client (vite dev) concurrently

Client dev server: http://localhost:5173 (proxies API to :3456)
API server: http://localhost:3456

Configuration

All configuration is via environment variables. Copy .env.example to .env and set the values you need.

Server

Variable	Default	Description
`PORT`	`3456`	Server port
`CLAUDE_BIN`	`claude`	Path to Claude CLI binary
`CODEX_BIN`	`codex`	Path to Codex CLI binary

Email Notifications (SMTP)

Variable	Default	Description
`SMTP_HOST`	—	SMTP server hostname (e.g., `smtp.gmail.com`)
`SMTP_PORT`	`587`	SMTP port (`587` for STARTTLS, `465` for TLS)
`SMTP_SECURE`	`false`	Set `true` for port 465
`SMTP_USER`	—	SMTP username
`SMTP_PASS`	—	SMTP password or app-specific password
`SMTP_FROM`	`agent-monitor@localhost`	Sender address

WhatsApp Notifications (Twilio)

Variable	Default	Description
`TWILIO_ACCOUNT_SID`	—	Twilio Account SID
`TWILIO_AUTH_TOKEN`	—	Twilio Auth Token
`TWILIO_WHATSAPP_FROM`	—	WhatsApp-enabled Twilio phone number (e.g., `+14155238886`)

Slack Notifications (Webhook)

Variable	Default	Description
`SLACK_WEBHOOK_URL`	—	Default Slack Incoming Webhook URL

Remote Relay (Tunnel)

Variable	Default	Description
`RELAY_URL`	—	WebSocket URL of relay server (e.g., `ws://your-server:3457/tunnel`)
`RELAY_TOKEN`	—	Shared secret for tunnel authentication

If SMTP, Twilio, or Slack credentials are not set, the respective notification channel is disabled gracefully — events are logged to the server console.

Usage

Creating an Agent

Click "+ New Agent" on the Dashboard
Select Provider — Claude Code or Codex
Set Name, Working Directory (use Browse to pick a directory), and Prompt
If the selected directory contains a CLAUDE.md, you'll be prompted to load it automatically
Configure Flags (e.g., --dangerously-skip-permissions, --chrome, --permission-mode)
Optionally load a CLAUDE.md template or write custom instructions
Enter an Admin Email, WhatsApp Phone, and/or Slack Webhook URL for notifications
Click Create Agent

Tip — Clone an existing agent: Hit the Clone button on any agent card to create a new agent pre-filled with the same directory, provider, flags, and CLAUDE.md. Combine with templates for a reusable agent library: create a template with your standard instructions → create one agent using it → clone whenever you need a fresh instance.

Dashboard

Each agent is represented by a rich information card displaying:

Project & git branch — which repository and branch the agent is working on
Pull Request link — if the agent created a PR, a direct link is shown (auto-detected)
Model & context usage — which LLM model and a visual bar for context window consumption
Status — whether the agent is actively working, idle, or waiting for permission
Task description — a summary of what the agent is currently doing
MCP servers — connected Model Context Protocol servers (parsed from --mcp-config)
Cost / token tracking — per-agent cost (Claude) or token usage (Codex)

Click any card to open the full chat interface.

Agent Chat

Send messages, view conversation history, interrupt with Double-Esc, and use slash commands:

/help /clear /status /cost /stop /compact /model /export

Task Pipeline

Orchestrate multi-step workflows with sequential and parallel task definitions. The Meta Agent Manager automatically provisions agents, monitors progress, sends notifications on failures, and cleans up on completion.

Templates

Create, edit, and reuse CLAUDE.md instruction templates across agents.

API Reference

Agents

Method	Endpoint	Description
GET	`/api/agents`	List all agents
GET	`/api/agents/:id`	Get agent details
POST	`/api/agents`	Create agent
POST	`/api/agents/:id/stop`	Stop agent
POST	`/api/agents/:id/message`	Send message
POST	`/api/agents/:id/interrupt`	Interrupt agent (SIGINT)
PUT	`/api/agents/:id/claude-md`	Update CLAUDE.md
DELETE	`/api/agents/:id`	Delete agent
POST	`/api/agents/actions/stop-all`	Stop all agents

Pipeline Tasks

Method	Endpoint	Description
GET	`/api/tasks`	List pipeline tasks
POST	`/api/tasks`	Create task
DELETE	`/api/tasks/:id`	Delete task
POST	`/api/tasks/:id/reset`	Reset task status
POST	`/api/tasks/clear-completed`	Clear completed/failed tasks
GET	`/api/meta/config`	Get meta agent config
PUT	`/api/meta/config`	Update meta agent config
POST	`/api/meta/start`	Start meta agent manager
POST	`/api/meta/stop`	Stop meta agent manager

Templates

Method	Endpoint	Description
GET	`/api/templates`	List templates
GET	`/api/templates/:id`	Get template
POST	`/api/templates`	Create template
PUT	`/api/templates/:id`	Update template
DELETE	`/api/templates/:id`	Delete template

Settings

Method	Endpoint	Description
GET	`/api/settings`	Get server settings (agent retention, etc.)
PUT	`/api/settings`	Update server settings

Other

Method	Endpoint	Description
GET	`/api/sessions`	List previous Claude sessions
GET	`/api/directories?path=/home`	Browse server directories
GET	`/api/directories/claude-md?path=/project`	Check if CLAUDE.md exists in a directory
GET	`/api/health`	Health check

Socket.IO Events

Event	Direction	Description
`agent:join`	Client → Server	Subscribe to agent messages
`agent:leave`	Client → Server	Unsubscribe
`agent:send`	Client → Server	Send message
`agent:interrupt`	Client → Server	Send interrupt
`agent:message`	Server → Client	Agent output (legacy)
`agent:update`	Server → Client	Full agent snapshot (real-time streaming)
`agent:snapshot`	Server → Client	Dashboard broadcast update
`agent:status`	Server → Client	Status change
`task:update`	Server → Client	Pipeline task updated
`pipeline:complete`	Server → Client	Pipeline complete
`terminal:open`	Client → Server	Open PTY terminal in agent directory
`terminal:input`	Client → Server	Send keystrokes to PTY
`terminal:resize`	Client → Server	Resize PTY dimensions
`terminal:close`	Client → Server	Close PTY session
`terminal:output`	Server → Client	PTY output data
`terminal:exit`	Server → Client	PTY process exited
`meta:status`	Server → Client	Meta agent status

Remote Access (Relay Mode)

Access the Agent Monitor dashboard from anywhere — phone, laptop, or any device — via a public relay server. The relay forwards all HTTP and WebSocket traffic through a secure tunnel.

Phone/Laptop → HTTP → Public Server (Relay :3457) ← WS tunnel ← Local Machine (:3456)

Setup

Deploy the relay to a public server:

bash relay/scripts/deploy.sh <your-secret-token> <your-dashboard-password>

Connect the local server by setting environment variables:

RELAY_URL=ws://your-server:3457/tunnel RELAY_TOKEN=<your-secret-token> npx tsx server/src/index.ts

Open the dashboard from any device at http://your-server:3457 — log in with your password

The relay supports password-based login via RELAY_PASSWORD to protect the dashboard from unauthorized access. Sessions use JWT tokens with 24-hour expiry. The tunnel auto-reconnects if the connection drops. When RELAY_URL is not set, the server runs in local-only mode with no relay overhead.

Feishu (Lark) Bot Integration

Use Feishu (Lark) as an interactive bot interface alongside the web dashboard and terminals. The bot uses Feishu's WebSocket long-connection — no public URL needed on your agent machine.

Features

Live agent cards — Agent status, messages, cost, and branch are displayed as updateable interactive Feishu cards (auto-refreshed on every change, debounced to respect rate limits)
Choice buttons everywhere — When an agent waits for human input, permission prompts and choices appear as clickable card buttons — both in the bound chat and in proactive notification alerts
Unified notifications — Feishu replaces or complements email/WhatsApp/Slack: task failures, stuck agents, and pipeline completion all send rich cards to the admin chat instead of plain text
Commands — /list, /attach, /detach, /stop, /status, /help
Access control — Restrict bot access to specific Feishu open_ids via FEISHU_ALLOWED_USERS
Persistent bindings — Chat-to-agent bindings survive server restarts (stored in data/feishu_bindings.json)

Setup

Create a Feishu bot at Feishu Open Platform
Enable permissions: Receive messages (im:message.receive_v1) and Send messages (im:message:create)
Enable WebSocket long-connection event subscription
Enable Interactive card support
Set environment variables:

FEISHU_APP_ID=cli_xxxxxxxxxxxxxxxx
FEISHU_APP_SECRET=xxxxxxxxxxxxxxxx

# Admin chat for pipeline notifications (task failures, pipeline complete, stuck agents)
FEISHU_ADMIN_CHAT_ID=oc_xxxxxxxxxxxx

# Optional: restrict bot to specific users (comma-separated open_ids)
FEISHU_ALLOWED_USERS=ou_xxxx,ou_yyyy

To send Feishu notifications for a specific agent (e.g., waiting_input), set feishuChatId when creating the agent via API:

{ "feishuChatId": "oc_xxxxxxxxxxxx" }

Usage

Command	Description
`/list`	List all agents with status and a "Connect" button
`/attach <name or ID>`	Bind this chat to an agent (shows live card)
`/detach`	Unbind from the current agent
`/stop`	Stop the currently bound agent
`/status`	Refresh the current agent's status card
`/help`	Show this help

Once attached, send free text to forward it directly to the agent. When the agent is waiting for input, click a choice button or type a reply.

Provider Support

	Claude Code	Codex
Binary	`claude`	`codex`
Flags	`--dangerously-skip-permissions`, `--permission-mode`, `--chrome`, `--max-budget-usd`, `--allowedTools`, `--disallowedTools`, `--add-dir`, `--mcp-config`, `--resume`, `--model`	`--dangerously-bypass-approvals-and-sandbox`, `--full-auto`, `--model`
Tracking	Cost (USD)	Token usage

Testing

npm test    # 40 tests

Architecture

AgentMonitor/
  server/                   # Node.js + Express + Socket.IO
    src/
      services/
        AgentProcess.ts     # CLI process wrapper
        AgentManager.ts     # Agent lifecycle
        MetaAgentManager.ts # Pipeline orchestration
        TunnelClient.ts     # Outbound tunnel to relay server
        tunnelBridge.ts     # Event bridge for tunnel
        TerminalService.ts  # PTY terminal management (node-pty)
        WorktreeManager.ts  # Git worktree ops
        EmailNotifier.ts    # SMTP email notifications
        WhatsAppNotifier.ts # Twilio WhatsApp notifications
        SlackNotifier.ts    # Slack webhook notifications
        SessionReader.ts    # Session history
        DirectoryBrowser.ts # Directory listing
      store/AgentStore.ts   # JSON persistence
      routes/               # REST endpoints
      socket/handlers.ts    # WebSocket handlers
    __tests__/              # Test suite
  relay/                    # Public relay server (deployed independently)
    src/
      index.ts              # Relay entry point
      tunnel.ts             # TunnelManager (WS server)
      httpProxy.ts          # HTTP forwarding through tunnel
      socketBridge.ts       # Socket.IO ↔ tunnel bridge
      config.ts             # Relay configuration
    scripts/deploy.sh       # Build & deploy to public server
  client/                   # React + Vite
    src/
      pages/                # Dashboard, Chat, Pipeline, Templates
      i18n/                 # 7-language localization (EN/ZH/JA/KO/ES/FR/DE)
      api/                  # REST + Socket.IO clients

License

MIT

Name		Name	Last commit message	Last commit date
Latest commit History 105 Commits
.claude/commands		.claude/commands
.github/workflows		.github/workflows
client		client
docs		docs
relay		relay
server		server
test-results		test-results
.env.example		.env.example
.gitignore		.gitignore
README-zh.md		README-zh.md
README.md		README.md
package-lock.json		package-lock.json
package.json		package.json

Folders and files

Latest commit

History

Repository files navigation

Agent Monitor

Table of Contents

Key Features

Spin Up Agents Instantly with Cloneable Templates

Multi-Agent Orchestration

External Agent Discovery

Real-Time Monitoring & Interaction

Notifications — Email, WhatsApp & Slack

Feishu (Lark) Bot & Notifications

Remote Access via Relay Server

Internationalization

Demo

Quick Start — Create Agent with Template

Chat & Terminal

Task Pipeline

Screenshots

Quick Start

Prerequisites

Installation

Production

Development

Configuration

Server

Email Notifications (SMTP)

WhatsApp Notifications (Twilio)

Slack Notifications (Webhook)

Remote Relay (Tunnel)

Usage

Creating an Agent

Dashboard

Agent Chat

Task Pipeline

Templates

API Reference

Agents

Pipeline Tasks

Templates

Settings

Other

Socket.IO Events

Remote Access (Relay Mode)

Setup

Feishu (Lark) Bot Integration

Features

Setup

Usage

Provider Support

Testing

Architecture

License

About

Topics

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages