Agent Recon™

Monitor every tool call, security event, token cost, and session in real time. Know exactly what your AI agent is doing.

→ View landing page | Installation guide | Pricing

Quick Start

Windows users: Installing Claude Code first is recommended. See the installation guide for Windows-specific prerequisites (ExecutionPolicy, Python Store alias, firewall).

Option A — Install via npm

npm install -g agent-recon
agent-recon install

The guided installer detects your platform, registers hooks, and starts the server. See the Installation Guide for prerequisites, troubleshooting, and alternative methods.

Option B — From source

cd server && npm install && cd ..
node server/start.js

Note: Option B starts the server only. Hooks must be configured separately via node installer/cli.js install or by running the platform setup script.

Open the dashboard

Visit http://localhost:3131 in your browser.

Start Claude Code

Run any claude command from this project directory. Hook events will stream to the dashboard instantly.

How It Works

Claude Code Agent(s)
     |  hook fires → stdin JSON
     v
.claude/hooks/send-event.js  --HTTP POST-->  server/server.js (port 3131)
                                                      |
                                              WebSocket broadcast
                                                      v
                                           public/index.html (browser)
                                         icons · sounds · live feed

Every hook registered in .claude/settings.json is wired to send-event.js, which runs asynchronously (never blocking Claude) and forwards the payload to the local server. The server stores up to 1 000 events in memory and fans them out to every connected browser tab via WebSocket. Late-joining tabs receive the full event history on connect.

Event Categories & Sounds

Dashboard Features

• Timeline view — chronological feed, newest at top with slide-in animation
• Swimlane view — one column per session_id for multi-agent observation
• Category filter — click any badge in the stats bar to isolate a category
• Session filter — dropdown to focus on a single agent session
• Sound controls — mute toggle + volume slider; all tones synthesized via Web Audio API (no audio files)
• Expandable cards — click any card to reveal the full raw JSON payload
• Auto-reconnect — dashboard reconnects automatically if the server restarts
• History on join — opening a new tab replays all stored events immediately

Windows Notes

The hook command in .claude/settings.json is:

node .claude/hooks/send-event.js

If node is not on your PATH when Git Bash runs the hook (e.g. nvm-windows / Volta / fnm shims), the installer falls back to the absolute path of your Node.js executable:

C:/Program Files/nodejs/node.exe .claude/hooks/send-event.js

The forwarder uses only Node.js standard library modules — no npm install required.

Additional Windows considerations:

• Install Claude Code first (recommended) — Agent Recon hooks merge into settings.json. The installer creates it if missing, but having Claude Code installed first is recommended.
• Node on Git Bash PATH — If you use a Node version manager (nvm-windows, Volta, fnm), re-run agent-recon install after switching Node versions to refresh the hook command.
• ExecutionPolicy — Default Restricted blocks npm. Run: Set-ExecutionPolicy RemoteSigned -Scope CurrentUser
• Firewall — Windows Defender may block node.exe. Allow for private networks when prompted.

WSL + tmux Support

Claude Code running inside WSL (including inside a tmux session) can stream events to the same dashboard.

How it works

WSL tmux session
  Claude Code Agent
       |  hook fires → stdin JSON
       v
~/.claude/hooks/send-event.js  --HTTP POST-->  Windows host IP:3131
                                                          |
                                                  (same server.js)
                                                          v
                                               browser dashboard

Events from WSL show a green WSL badge in the dashboard so you can distinguish them from Windows-side sessions.

Quick Setup

1 — On Windows, start the Agent Recon™ server as usual:

agent-recon start
# or if installed from source: node server/start.js

2 — Inside WSL, run the installer:

agent-recon install

Or, if installed from source, run the setup script:

bash /path/to/agent-recon/setup-wsl.sh

This script:

• Copies send-event.js to ~/.claude/hooks/
• Creates ~/.claude/settings.json with all 24 hook registrations
• Verifies the Windows host is reachable

3 — Start Claude in any WSL directory (plain shell or tmux):

tmux new-session -s work
claude

Events will stream to http://localhost:3131 on Windows immediately.

How the WSL forwarder finds the Windows host

It parses /proc/net/route to find the default gateway (the WSL2 virtual gateway is the Windows host). The server accepts connections from all RFC 1918 private ranges (10.x, 172.16-31.x, 192.168.x) in addition to loopback.

File Structure

├── .claude/
│   ├── hooks/
│   │   └── send-event.js          # Cross-platform hook forwarder (stdlib only; auto-detects WSL)
│   └── settings.json              # Hook registrations for Claude Code
├── server/
│   ├── package.json
│   └── server.js                  # Express HTTP + WebSocket server (port 3131)
├── public/
│   └── index.html                 # Single-file dashboard SPA
├── setup-wsl.sh                   # One-time WSL setup script
└── README.md