# 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.

[![npm](https://img.shields.io/npm/v/agent-recon)](https://www.npmjs.com/package/agent-recon)
[![License](https://img.shields.io/badge/license-Source--Available-blue)](LICENSE)
[![Platform](https://img.shields.io/badge/platform-Windows%20%7C%20macOS%20%7C%20Linux%20%7C%20WSL-brightgreen)]()

🔒 **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, plus Cursor and GitHub Copilot CLI

→ **[View landing page](https://www.agent-recon.net)** | **[Installation guide](INSTALL.md)** | **[Pricing](https://www.agent-recon.net#pricing)**

## Quick Start

### Option A — Install via npm

```bash
npm install -g agent-recon
agent-recon install
```

The guided installer detects your platform, registers hooks, and starts the server.
See [INSTALL.md](INSTALL.md) for prerequisites, troubleshooting, and alternative methods.

> **Using Cursor or GitHub Copilot CLI?** The installer detects them and wires up their
> hook forwarders automatically. See [INSTALL.md → Multi-Tool Support](INSTALL.md#multi-tool-support-cursor--github-copilot-cli).

> **Windows:** Install Claude Code before Agent Recon. See [INSTALL.md](INSTALL.md) for Windows-specific prerequisites.

### Option B — Homebrew / Scoop

```bash
# macOS / Linux
brew tap genxcoder1999/agent-recon && brew install agent-recon

# Windows
scoop bucket add agent-recon https://github.com/genxcoder1999/scoop-agent-recon && scoop install agent-recon
```

Then run `agent-recon install`. Both pull in Node.js automatically. See [INSTALL.md → Platform Package Managers](INSTALL.md#platform-package-managers).

### Option C — From source

```bash
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.js  ──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.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

| 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:
```
node .claude/hooks/send-event.js
```
If `node` is not on your PATH when Git Bash runs the hook (e.g. when using
nvm-windows / Volta / fnm shims), replace it with the full path to your
Node.js executable, e.g.:
```
C:/Program Files/nodejs/node.exe .claude/hooks/send-event.js
```
The forwarder uses only Node.js standard library modules — no `npm 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.js  ──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:
```powershell
cd C:\ProjectGreatLoop\agent-recon\server
node start.js
```

**2 — Inside WSL**, run the setup script once:
```bash
bash /mnt/c/ProjectGreatLoop/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):
```bash
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.js          # Cross-platform hook forwarder (stdlib only; auto-detects WSL)
│   └── 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
```