# Installing Agent Recon

## Prerequisites

- **Node.js >= 22** — [nodejs.org](https://nodejs.org/). This is the only runtime you need —
  the server, CLI, hook forwarder, and all setup scripts run on Node.

> **Ubuntu / Debian users:** The default `apt install nodejs` package ships Node.js 12 (Ubuntu 22.04)
> or 18 (Ubuntu 24.04) — both too old. Install Node 22+ via:
>
> - **nvm** (recommended, no root required): [github.com/nvm-sh/nvm](https://github.com/nvm-sh/nvm)
>   ```bash
>   nvm install 22
>   nvm use 22
>   ```
> - **NodeSource** (alternative, requires root):
>   [github.com/nodesource/distributions](https://github.com/nodesource/distributions)

> **Windows users:**
>
> - **Install Node.js 22+.** Download the LTS installer from [nodejs.org](https://nodejs.org/), or run `winget install OpenJS.NodeJS.LTS`. Restart your terminal afterward so `node` is on PATH.
> - **Install Claude Code first.** Agent Recon hooks merge into Claude Code's `settings.json` — it must exist before running `agent-recon install`.
> - **Set PowerShell ExecutionPolicy.** The default `Restricted` policy blocks npm scripts. Run once:
>   ```powershell
>   Set-ExecutionPolicy RemoteSigned -Scope CurrentUser
>   ```
> - **Allow Node.js through Windows Firewall.** Windows Defender may block `node.exe` on dynamic ports. When prompted, allow access for private networks. Or create a rule manually: **Windows Security → Firewall → Allow an app → node.exe**.
> - **Node version managers.** If you use nvm-windows / Volta / fnm, Claude Code's Git Bash may not see the shim on PATH. The installer probes `node --version` at install time and falls back to the absolute path of the current Node runtime. Re-run `agent-recon install` after switching Node versions.
> - **Restart your terminal after installing prerequisites.** PATH changes from winget/installer may not be visible in existing shell sessions.

## npm (Recommended)

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

Then run the guided installer:

```bash
agent-recon install
```

The installer will:
1. Detect your platform and existing configuration
2. Copy hook scripts to your Claude Code hooks directory
3. Register 24 lifecycle events in Claude Code settings
4. Optionally configure LLM API keys for analysis features
5. Optionally set up an auto-start service (systemd / launchd / Windows Service)
6. Verify the server starts and responds

For unattended CI or remote installs, pass `--yes` to accept all defaults without prompts:

```bash
agent-recon install --yes
```

## From Source

```bash
git clone <repository-url>
cd agent-recon

# Install server dependencies
cd server && npm install && cd ..

# Install installer dependencies
cd installer && npm install && cd ..

# Run the guided installer
node installer/cli.js install

# Or start the server manually
node server/start.js
```

## Upgrading

```bash
# If installed via npm
npm update -g agent-recon
agent-recon upgrade

# If installed from source
git pull
agent-recon upgrade
# or: node installer/cli.js upgrade
```

## Uninstalling

```bash
agent-recon uninstall
```

This removes hooks from Claude Code settings, stops any auto-start service, and optionally
deletes the database and stored credentials. The source directory is never deleted.

To also remove the npm package:

```bash
npm uninstall -g agent-recon
```

## Multi-Tool Support (Cursor & GitHub Copilot CLI)

Agent Recon can observe sessions from Cursor and GitHub Copilot CLI alongside
Claude Code. When the installer detects one of these tools, it registers a hook
forwarder for it automatically:

| Agent | Detected via | Hook config written |
|-------|--------------|---------------------|
| Cursor | `~/.cursor/` directory | `~/.cursor/hooks.json` (merged — any third-party hooks are preserved) |
| GitHub Copilot CLI | `~/.copilot/` directory | `~/.copilot/hooks/agent-recon.json` (a dedicated file) |

The per-agent forwarder scripts are installed alongside the Claude Code hook in
`~/.claude/hooks/`. Installed Cursor or Copilot CLI after running the installer?
Re-run `agent-recon install` to add them — it is idempotent. `agent-recon
uninstall` removes only Agent Recon's own hook entries.

**Token cost:** Cursor and Copilot CLI do not expose token usage in their hook
payloads, so the Tokens tab and per-event cost badges stay Claude-Code-only. The
live feed, Security tab, PII redaction, and environment detection work fully for
every supported agent.

## CLI Commands

```
agent-recon install            # Guided installation (default)
agent-recon install --yes      # Unattended install (accept all defaults)
agent-recon upgrade            # Upgrade existing installation
agent-recon uninstall          # Remove Agent Recon
agent-recon uninstall --yes    # Unattended uninstall (preserve data)
agent-recon start              # Start the server (foreground; --detach for background)
agent-recon stop               # Stop the server gracefully
agent-recon status             # Health check — exit 0 if running, 1 if not
agent-recon detect             # Print environment detection report
agent-recon --help             # Show help
agent-recon --version          # Show version
```

If you skipped the auto-start service during install, use `agent-recon start`
(or `agent-recon start --detach` to run it in the background) to bring the
dashboard up again in a later session.

The `--yes` flag (aliases: `-y`, `--non-interactive`) accepts all defaults without prompts. It is also enabled automatically when stdin is not a TTY (e.g., piped scripts, CI runners).

## Platform Package Managers

Prefer your OS package manager over npm? Agent Recon publishes a Homebrew formula and a Scoop manifest on each release (both pull in Node.js automatically).

### Homebrew (macOS / Linux)

```bash
brew tap genxcoder1999/agent-recon
brew install agent-recon
```

Then run `agent-recon install` to register hooks and start the server. The formula depends on `node@22`, so Homebrew installs Node for you.

### Scoop (Windows)

```powershell
scoop bucket add agent-recon https://github.com/genxcoder1999/scoop-agent-recon
scoop install agent-recon
```

Then run `agent-recon install`. The manifest depends on `nodejs`, so Scoop installs Node for you.

## TLS / HTTPS Setup

Agent Recon supports browser-trusted HTTPS via [mkcert](https://github.com/FiloSottile/mkcert), eliminating "Not Secure" browser warnings without self-signed certificate interstitials.

### Prerequisites

Install mkcert for your platform:

| Platform | Command |
|----------|---------|
| macOS | `brew install mkcert` |
| Windows | `choco install mkcert` |
| Linux / WSL | `apt install mkcert` or `brew install mkcert` |

Then run the one-time CA installation (requires admin/sudo):

```bash
mkcert -install
```

### Enable TLS during install

```bash
agent-recon install --tls
```

This pre-selects the mkcert option in the guided installer. You can also choose TLS interactively during a normal `agent-recon install`.

### Enable TLS on an existing installation

```bash
agent-recon tls setup     # configure mkcert TLS via server API
agent-recon tls status    # check current TLS status
agent-recon upgrade --tls # add TLS during upgrade
```

After enabling TLS, restart the server. The dashboard will be available at `https://localhost:3132` with a green padlock.

### WSL note

On WSL2, mkcert installs the CA into the Windows trust store via interop. Both Windows browsers and WSL-side `curl` will trust the certificate. Ensure `mkcert -install` is run from WSL (it automatically uses the Windows `certutil` via `/mnt/c/`).

### Custom certificates

For CA-signed or enterprise certificates, choose "Custom certificate" during install or set the paths in Settings. Provide PEM-encoded cert and key file paths.

## Verifying Installation

```bash
# Check environment detection
agent-recon detect

# Check server health (server must be running)
curl http://localhost:3131/health
```

## Data Directory

When installed globally via npm, Agent Recon stores its database and data files in a platform-specific user-writable directory:

| Platform | Default path |
|----------|-------------|
| Linux / WSL | `~/.config/agent-recon/data/` |
| macOS | `~/Library/Application Support/agent-recon/data/` |
| Windows | `%APPDATA%\agent-recon\data\` |

If `%APPDATA%` is not set on Windows, the fallback is `~/.config/agent-recon/data/`.

To override the data directory, set the `AGENT_RECON_DATA_DIR` environment variable before starting the server:

```bash
AGENT_RECON_DATA_DIR=/custom/path node server/start.js
```

When installed from source, data is stored in `data/` relative to the project root (the pre-v1.0.3 behavior).

## Troubleshooting

### `better-sqlite3` build failure

Prebuilt binaries are downloaded automatically for most platforms. If that fails, npm falls back to compiling the C++ addon from source, which requires build tools:

- **Windows:** `npm install -g windows-build-tools` or install Visual Studio Build Tools
- **macOS:** `xcode-select --install`
- **Linux (Debian/Ubuntu):** `sudo apt install build-essential`
- **Linux (Fedora/RHEL):** `sudo dnf groupinstall "Development Tools"`
- **Linux (Arch):** `sudo pacman -S base-devel`

If the build still fails:

1. Try rebuilding manually: `cd server && npm rebuild better-sqlite3`
2. On WSL, ensure you are on a native ext4 filesystem, not an NTFS mount (`/mnt/c/...`)

### Node not found in Git Bash (Windows)

Claude Code on Windows invokes hook commands through Git Bash, which sometimes doesn't share
PATH with the shell that installed Agent Recon (nvm-windows / Volta / fnm shims). The
installer probes `node --version` at install time and falls back to the absolute path of
the current Node runtime when the probe fails.

- If you switch Node versions after installing Agent Recon, re-run `agent-recon install`
  to refresh the hook command in `~/.claude/settings.json`.
- On macOS/Linux/WSL, `node` on PATH is always reliable and no fallback is needed.

### Permission errors on global install

If `npm install -g` fails with permission errors:

- **Recommended:** Configure npm to use a user directory:
  ```bash
  mkdir -p ~/.npm-global
  npm config set prefix '~/.npm-global'
  # Add to ~/.bashrc or ~/.zshrc:
  export PATH="$HOME/.npm-global/bin:$PATH"
  ```
- **Not recommended:** `sudo npm install -g agent-recon` (avoid running npm as root)

### Server won't start

1. Check that port 3131 is available: `lsof -i :3131` (macOS/Linux) or `netstat -ano | findstr 3131` (Windows)
2. Ensure the database directory is writable: `ls -la data/`
3. Check logs: set `AGENT_RECON_DEBUG=1` before starting

### EACCES permission denied on server start (global install)

If `sudo npm install -g agent-recon` was used and the server crashes with `EACCES: permission denied, mkdir '...data'`, the data directory is in a root-owned location. As of v1.0.3, the server automatically uses a user-writable path (see [Data Directory](#data-directory) above). Upgrade to v1.0.3+ to resolve this.

As a workaround, override the data directory:

```bash
AGENT_RECON_DATA_DIR=~/.config/agent-recon/data agent-recon start
```

### Credential storage on headless Linux / SSH

On headless Linux servers or SSH sessions, `libsecret` requires a D-Bus session and unlocked keyring, which are typically unavailable. Without a working OS keystore the server has no way to encrypt stored secrets, so **it refuses to start** rather than fall back to writing them unencrypted.

Provide a master key so the server can encrypt secrets itself. This is **required** on headless/SSH hosts:

```bash
export AGENT_RECON_MASTER_KEY=$(openssl rand -hex 32)
agent-recon start
```

Store the key securely — it's needed to decrypt any previously encrypted API keys, and losing it means those keys must be re-entered.

> **Unsafe opt-out:** setting `AGENT_RECON_ALLOW_PLAINTEXT=1` lets the server start with secrets stored **unencrypted** on disk. It is presence-checked (any value, including `0`, enables it), so only set it when you understand the exposure — prefer `AGENT_RECON_MASTER_KEY`.