Installing Agent Recon

Prerequisites

• Node.js >= 22 — nodejs.org. This is the only runtime you need — the server, CLI, hook forwarder, and setup scripts all 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) or NodeSource (alternative, requires root).

Windows users:

• Install Claude Code first (recommended). Agent Recon hooks merge into Claude Code’s settings.json. If it doesn’t exist, the installer creates it automatically, but installing Claude Code first ensures hooks are configured correctly.
• Set ExecutionPolicy. Run Set-ExecutionPolicy RemoteSigned -Scope CurrentUser in PowerShell (default Restricted policy blocks npm scripts).
• Allow Node.js through Windows Firewall. Windows Defender may block node.exe on dynamic ports. Allow access for private networks when prompted.
• Node version managers. If you use nvm-windows, Volta, or 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 may not be visible in existing sessions.

• C/C++ build tools — Not typically needed. Prebuilt binaries are downloaded automatically for most platforms. See Troubleshooting if installation fails.

npm (Recommended)

npm install -g agent-recon

Then run the guided installer:

agent-recon install

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

agent-recon install --yes

The installer will:

1. Display the license agreement (EULA)
2. Detect your platform and existing configuration
3. Select an installation directory
4. Copy hook scripts to your Claude Code hooks directory
5. Register 25 lifecycle events in Claude Code settings
6. Optionally configure LLM API keys for analysis features
7. Optionally set up an auto-start service (systemd / launchd / Windows Service)
8. Verify the server starts and responds

Upgrading

# 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

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:

npm uninstall -g agent-recon

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 detect             # Print environment detection report
agent-recon --help             # Show help
agent-recon --version          # Show version

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

Homebrew (macOS / Linux) — Coming Soon

A Homebrew formula is planned for a future release. In the meantime, use npm.

Scoop (Windows) — Coming Soon

A Scoop manifest is planned for a future release. In the meantime, use npm.

TLS / HTTPS Setup

Agent Recon supports browser-trusted HTTPS via mkcert, eliminating “Not Secure” browser warnings without self-signed certificate interstitials.

Prerequisites

Install mkcert for your platform:

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

mkcert -install

Enable TLS during install

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

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

# 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 in a platform-specific user-writable directory:

Override with the AGENT_RECON_DATA_DIR environment variable.

Troubleshooting

better-sqlite3 build failure

This native addon must compile C++ code during installation. If it fails:

1. Ensure C/C++ build tools are installed (see Prerequisites above)
2. Try rebuilding manually: cd server && npm rebuild better-sqlite3
3. 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:

  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 the server crashes with EACCES: permission denied, mkdir '...data', the data directory resolved to a root-owned location. Upgrade to v1.0.3+ which uses a user-writable data directory automatically.

Workaround: AGENT_RECON_DATA_DIR=~/.config/agent-recon/data agent-recon start

Windows-Specific Issues

See the Prerequisites section for Windows setup requirements. Additional notes:

• Python opens Microsoft Store: Disable the Store alias in Settings → Apps → App execution aliases.
• ExecutionPolicy blocks npm: Set-ExecutionPolicy RemoteSigned -Scope CurrentUser
• Node.js blocked by firewall: Allow node.exe in Windows Defender Firewall for private networks.
• PATH not updated: Restart your terminal after installing prerequisites via winget or installers.
• Install order: Installing Claude Code first is recommended. The installer creates settings.json if missing, but having Claude Code already set up ensures hooks work correctly.

Credential storage on headless Linux / SSH

On headless servers or SSH sessions, libsecret requires a D-Bus session and unlocked keyring. The server falls back to PBKDF2 file-based encryption automatically. If credential errors persist, set:

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