Documentation

What is AgentLens

AgentLens is an audit trail for AI agents. It captures every tool call your agent makes and explains it in plain English in real time.

Works with Claude Desktop, Claude Code, Cursor, Cline, and any MCP-compatible agent. See every file read, every command run, every file written — as it happens.

Quick Start

npx agentlens-cli setup-all --api-key YOUR_KEY --app-id YOUR_ID

How it works

AgentLens sits between your AI agent and its tools. When your agent calls a tool (read a file, run a command, write code), AgentLens captures the call, sends it to the dashboard, and an AI explainer generates a plain-English summary with a severity rating.

Claude Desktop Setup

npx agentlens-cli setup \
  --api-key YOUR_KEY \
  --app-id YOUR_APP_ID

This automatically edits your claude_desktop_config.json file. Restart Claude Desktop after running.

Config file locations

Claude Code Setup

npx agentlens-cli setup-hooks \
  --api-key YOUR_KEY \
  --app-id YOUR_APP_ID \
  --agent claude-code

Installs a PostToolUse hook that logs every tool call. Restart Claude Code after running.

Any Agent (Direct API)

POST directly to the AgentLens API from any language or framework. No SDK installation needed.

POST https://agentlens.vercel.app/api/ingest
Header: x-api-key: YOUR_KEY

Request body (JSON)

{
  "tool_name": "write_file",
  "arguments": { "path": "/src/app.js" },
  "result": { "success": true },
  "session_id": "your-session-uuid",
  "app_id": "your-app-uuid",
  "ai_model": "gpt-4",
  "llm_reasoning": "optional context"
}

Response

{ "success": true, "event_id": "uuid" }

JavaScript example

await fetch(
  'https://agentlens.vercel.app/api/ingest',
  {
    method: 'POST',
    headers: {
      'x-api-key': 'YOUR_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      tool_name: 'write_file',
      arguments: { path: '/src/app.js' },
      result: { success: true },
      session_id: crypto.randomUUID(),
      app_id: 'YOUR_APP_ID',
      ai_model: 'gpt-4'
    })
  }
)

Python example

import requests, uuid

requests.post(
    'https://agentlens.vercel.app/api/ingest',
    headers={'x-api-key': 'YOUR_KEY'},
    json={
        'tool_name': 'write_file',
        'arguments': {'path': '/src/app.js'},
        'result': {'success': True},
        'session_id': str(uuid.uuid4()),
        'app_id': 'YOUR_APP_ID',
        'ai_model': 'gpt-4'
    }
)

CLI Commands

Quick Start (one-liner)

npx agentlens-cli setup-all --api-key YOUR_KEY --app-id YOUR_ID

Auto-detects and configures all AI agents on your machine. Supports Claude Desktop, Claude Code, Cursor, Cline, Windsurf, Antigravity.

List Connected Agents

npx agentlens-cli list

Shows which agents are connected to AgentLens with configured hooks or MCP entries, along with masked API key previews.

Detection

npx agentlens-cli detect

Scans your machine for installed AI agents and shows what's found.

Individual Setup (advanced)

npx agentlens-cli setup --api-key KEY --app-id ID

Configure Claude Desktop only (MCP interceptor).

npx agentlens-cli setup-hooks --api-key KEY --app-id ID --agent claude-code

Configure a specific agent's hooks manually.

Background Watchdog

npx agentlens-cli daemon start

Start background watchdog. Auto-heals config, flushes offline queue every 5 minutes.

npx agentlens-cli daemon stop

Stop the background watchdog.

npx agentlens-cli daemon status

Check watchdog health, configured agents, and queue status.

Offline Queue

npx agentlens-cli queue status

See how many events are queued while offline.

npx agentlens-cli queue flush --api-key KEY --app-id ID

Manually send all queued events to the dashboard.

npx agentlens-cli queue clear

Delete all queued events without sending.

Verify

npx agentlens-cli verify

Check all config files and test API key connectivity. Useful for debugging setup issues.

Uninstall

npx agentlens-cli uninstall

Remove AgentLens from all agents, stop daemon, clean up local files.

Configuration

AgentLens is configured through CLI flags at setup time. There is no separate config file to manage.

Required parameters

Optional parameters

Environment variables

You can also set credentials via environment variables instead of CLI flags:

export AGENTLENS_API_KEY=your-key
export AGENTLENS_APP_ID=your-app-id

Event Format

{
  "tool_name": "string",       // tool that ran
  "arguments": {},             // tool input
  "result": {},                // tool output
  "before_snapshot": {},       // file state before
  "session_id": "string",     // groups events
  "app_id": "string",         // your app UUID
  "ai_model": "string",       // which AI ran this
  "seq": 0,                   // event order
  "llm_reasoning": "string"   // optional context
}

POST /api/ingest

The main endpoint for sending events to AgentLens.

Authentication

All API requests require an x-api-key header. Get your API key from the Settings page after creating an app.

API keys are tied to a specific app. Each app has its own key. You can regenerate a key at any time — the old key is immediately revoked.

Rate Limits

Severity Levels

Reading the Dashboard

The Sessions page shows all captured agent sessions. Each session is a group of tool calls from a single agent run.

Click a session to see the event timeline — a chronological list of every tool call with plain-English explanations, severity badges, and expandable before/after diffs.

Use the filter bar to search by keyword, severity level, or date range. The stats bar shows total sessions, events today, destructive events, and active apps at a glance.

Sharing Sessions

Every session has a unique URL. Click the "Share session" button on any session detail page to copy the link.

Session URLs use unguessable UUIDs, so they act as share tokens. Anyone with the link can view the session — no login required.

Plan Limits