Open-source observability & audit trail for AI agents
AgentLens is a flight recorder for AI agents. It captures every tool call, approval decision, data exchange, and error — then presents it through a queryable API and real-time web dashboard.
MCP-native. Add one config block → every tool call is captured automatically. Zero code changes.
- 🔌 MCP-Native — Ships as an MCP server. Agents connect to it like any other tool. Works with Claude Desktop, Cursor, and any MCP client.
- 📊 Real-Time Dashboard — Session timelines, event explorer, cost analytics, and alerting in a beautiful web UI.
- 🔒 Tamper-Evident Audit Trail — Append-only event storage with SHA-256 hash chains per session. Cryptographically linked and verifiable.
- 💰 Cost Tracking — Track token usage and estimated costs per session, per agent, over time. Alert on cost spikes.
- 🚨 Alerting — Configurable rules for error rate, cost threshold, latency anomalies, and inactivity.
- 🔗 AgentKit Ecosystem — First-class integrations with AgentGate (approval flows) and FormBridge (data collection).
- 🏠 Self-Hosted — SQLite by default, no external dependencies. MIT licensed. Your data stays on your infrastructure.
┌─────────────────────────────────────────────────────────────┐
│ AI Agents (Claude Desktop, Cursor, GPT-4, Custom) │
│ │ │
│ │ MCP Protocol (stdio) │
│ ▼ │
│ ┌──────────────────────────────────────┐ │
│ │ @agentlensai/mcp │ │
│ │ Tools: session_start · log_event │ │
│ │ session_end · query_events │ │
│ └──────────────┬───────────────────────┘ │
│ │ HTTP (batched events) │
└─────────────────┼───────────────────────────────────────────┘
▼
┌─────────────────────────────────────────────────────────────┐
│ @agentlensai/server │
│ │
│ ┌────────────┐ ┌────────────┐ ┌────────────┐ │
│ │ Ingest │ │ Query │ │ Alert │ │
│ │ Engine │ │ Engine │ │ Engine │ │
│ └─────┬──────┘ └─────┬──────┘ └────────────┘ │
│ └───────────────┘ │
│ │ │
│ ┌──────┴──────┐ ┌─────────────┐ │
│ │ SQLite │ │ Dashboard │ │
│ │ (append │ │ React SPA │ │
│ │ only) │ │ (served │ │
│ └─────────────┘ │ at /) │ │
│ └─────────────┘ │
└──────────────────────────────────────────────────────────────┘
Integrations: AgentGate ──┐
FormBridge ─┤──► POST /api/events/ingest
Generic ────┘ (HMAC-SHA256 verified)
Opens on http://localhost:3400 with SQLite — zero config.
curl -X POST http://localhost:3400/api/keys \
-H "Content-Type: application/json" \
-d '{"name": "my-agent"}'
Save the als_... key from the response — it’s shown only once.
Claude Desktop (claude_desktop_config.json):
{
"mcpServers": {
"agentlens": {
"command": "npx",
"args": ["@agentlensai/mcp"],
"env": {
"AGENTLENS_API_URL": "http://localhost:3400",
"AGENTLENS_API_KEY": "als_your_key_here"
}
}
}
}
Cursor (.cursor/mcp.json):
{
"mcpServers": {
"agentlens": {
"command": "npx",
"args": ["@agentlensai/mcp"],
"env": {
"AGENTLENS_API_URL": "http://localhost:3400",
"AGENTLENS_API_KEY": "als_your_key_here"
}
}
}
}
Navigate to http://localhost:3400 — see sessions, timelines, analytics, and alerts in real time.
| Endpoint | Description |
|---|---|
POST /api/events |
Ingest events (batch) |
GET /api/events |
Query events with filters |
GET /api/sessions |
List sessions |
GET /api/sessions/:id/timeline |
Session timeline with hash chain verification |
GET /api/analytics |
Bucketed metrics over time |
GET /api/analytics/costs |
Cost breakdown by agent |
POST /api/alerts/rules |
Create alert rules |
POST /api/events/ingest |
Webhook ingestion (AgentGate/FormBridge) |
POST /api/keys |
Create API keys |
AgentLens works alongside two companion projects for unified agent lifecycle management:
Together: data collection → approvals → observability.
Approval events from AgentGate and form submissions from FormBridge appear directly in AgentLens session timelines, giving you a single view of the complete agent lifecycle.
# Clone and install
git clone https://github.com/amitpaz/agentlens.git
cd agentlens
pnpm install
# Run all checks
pnpm typecheck
pnpm test
pnpm lint
# Start dev server
pnpm dev
- Node.js ≥ 20.0.0
- pnpm ≥ 10.0.0