Agent Recon™

Real-time observability for AI coding agents.

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

🔒 Security classification — regex + LLM-powered risk analysis on every tool call 📊 Token cost tracking — per-session spend with multi-model support 🧠 AI-powered insights — prompt coaching, hallucination detection, session narratives 🌐 Cross-platform — Windows, macOS, Linux, WSL, tmux, VS Code 🔌 Agent-agnostic architecture — Claude Code v1, Cursor/Copilot/Windsurf in v1.1

→ View landing page | Installation guide | Pricing

Quick Start

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 INSTALL.md for prerequisites, troubleshooting, and alternative methods.

Windows: Install Claude Code before Agent Recon. See INSTALL.md for Windows-specific prerequisites.

Option B — From source

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

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
     ▼
.claude/hooks/send-event.py  ──HTTP POST──▶  server/server.js (port 3131)
                                                      │
                                              WebSocket broadcast
                                                      ▼
                                           public/index.html (browser)
                                         icons · sounds · live feed

Every hook registered in .claude/settings.json is wired to send-event.py, 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

| Icon | Category | Hook Events | Sound | |------|----------|-------------|-------| | 🚀 | Session | SessionStart, SessionEnd | Rising arpeggio / falling tone | | 💬 | Prompt | UserPromptSubmit | Soft ping | | ⚡ | Bash | PreToolUse (Bash) | Quick click | | ✍️ | Write | PreToolUse (Write) | Soft click | | ✏️ | Edit | PreToolUse (Edit/MultiEdit) | Soft click | | 👁️ | Read | PreToolUse (Read) | Soft click | | 🔍 | Search | PreToolUse (Glob/Grep) | Soft click | | 🌐 | Web | PreToolUse (WebFetch/WebSearch) | Soft click | | 🔧 | Tool | PreToolUse (other) | Soft click | | ✅ | Done | PostToolUse | Short positive beep | | ❌ | Failure | PostToolUseFailure | Low buzz | | 🤖 | Subagent | SubagentStart, SubagentStop | Spawn/resolve chime | | 🔔 | Notify | Notification | Bell tone | | 🏆 | Complete | Stop, TaskCompleted | Success chord | | ⚠️ | Idle | TeammateIdle | Pulsed alert | | 🗜️ | Compact | PreCompact | Soft tone |

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:

python .claude/hooks/send-event.py

If python is not on your PATH, replace it with the full path to your Python 3 executable, e.g.:

C:\Python312\python.exe .claude/hooks/send-event.py

The forwarder uses only Python standard library modules — no pip install required.

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
       ▼
~/.claude/hooks/send-event-wsl.py  ──HTTP POST──▶  Windows host IP:3131
                                                          │
                                                  (same server.js)
                                                          ▼
                                               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:

cd C:\ProjectGreatLoop\agent-recon\server
node start.js

2 — Inside WSL, run the setup script once:

bash /mnt/c/ProjectGreatLoop/agent-recon/setup-wsl.sh

This script:

• Copies send-event-wsl.py to ~/.claude/hooks/
• Creates ~/.claude/settings.json with all 25 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 reads the nameserver from /etc/resolv.conf (the WSL2 virtual gateway). If that fails it falls back to ip route show default. 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.py          # Windows hook forwarder (stdlib only)
│   │   └── send-event-wsl.py      # WSL hook forwarder (auto-detects host IP)
│   └── settings.json              # Hook registrations for Windows Claude
├── 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