> ## Documentation Index
> Fetch the complete documentation index at: https://lightsage.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Agent Tracking: See Which AI Agents Visit Your Docs
> Add one line of middleware to detect AI coding agent visits to your website and documentation in real time, with zero performance impact.
Agent Tracking is a lightweight middleware layer that detects when AI coding agents visit your website or documentation. When Claude Code, OpenCode, ChatGPT, or any of the other supported agents reads your docs pages, Lightsage records the visit — giving you real data on which agents are actively researching your API.
## Why this matters
You can optimize your documentation for AI agents without knowing which ones are actually visiting. But with Agent Tracking, you see the real picture: Claude Code visits your quick start 40 times a day, while Codex primarily reads your API reference. That's not a guess — it's a signal you can act on.
Understanding agent visit patterns helps you:
* Prioritize which agents to run API Performance evaluations against
* Identify which documentation pages agents read most (and which they skip)
* Detect when a new agent starts using your docs after you publish or update content
* Correlate documentation changes with changes in agent visit frequency
## How it works
The middleware inspects incoming HTTP requests for agent-specific user agent strings. When it detects a known AI coding agent or answer engine, it logs the visit — including which page was accessed and a timestamp — and forwards the data to Lightsage. The middleware adds no detectable latency to normal user traffic.
## Installation
Create or update your `middleware.ts` file at the root of your project:
```typescript middleware.ts theme={null}
import { withAgentTracking } from '@lightsage/agent-tracker/next';
export default withAgentTracking({
apiKey: process.env.LIGHTSAGE_API_KEY
});
export const config = {
matcher: ['/((?!api|_next|admin).*)'],
};
```
Install the package:
```bash theme={null}
npm install @lightsage/agent-tracker
```
Then add your API key to `.env.local`:
```bash theme={null}
LIGHTSAGE_API_KEY=your_api_key_here
```
The `matcher` config applies the middleware to all routes except `api`, `_next`, and `admin`. This ensures you're tracking documentation and marketing page visits without adding overhead to your own API routes or Next.js internals.
If you're deploying to Vercel without Next.js, add the middleware directly to your Vercel project. Create `middleware.ts` at the project root:
```typescript middleware.ts theme={null}
import { withAgentTracking } from '@lightsage/agent-tracker/vercel';
import { NextRequest } from 'next/server';
export default withAgentTracking({
apiKey: process.env.LIGHTSAGE_API_KEY
});
export const config = {
matcher: ['/((?!api|_next|admin).*)'],
};
```
Set the environment variable in your Vercel project settings under **Settings → Environment Variables**:
```
LIGHTSAGE_API_KEY = your_api_key_here
```
Add the Lightsage tracker to your Cloudflare Worker:
```typescript worker.ts theme={null}
import { createAgentTracker } from '@lightsage/agent-tracker/cloudflare';
const tracker = createAgentTracker({
apiKey: env.LIGHTSAGE_API_KEY
});
export default {
async fetch(request: Request, env: Env): Promise {
await tracker.track(request);
return fetch(request);
}
};
```
Add the secret to your Worker via Wrangler:
```bash theme={null}
wrangler secret put LIGHTSAGE_API_KEY
```
Add the middleware to your Express app before your route handlers:
```typescript server.ts theme={null}
import express from 'express';
import { agentTracker } from '@lightsage/agent-tracker/express';
const app = express();
app.use(agentTracker({
apiKey: process.env.LIGHTSAGE_API_KEY
}));
// Your routes below
app.get('/', (req, res) => {
res.send('Hello world');
});
```
Set the environment variable before starting your server:
```bash theme={null}
LIGHTSAGE_API_KEY=your_api_key_here node server.js
```
Add an edge function to your Netlify project. Create `netlify/edge-functions/agent-tracker.ts`:
```typescript netlify/edge-functions/agent-tracker.ts theme={null}
import { createAgentTracker } from '@lightsage/agent-tracker/netlify';
const tracker = createAgentTracker({
apiKey: Deno.env.get('LIGHTSAGE_API_KEY')
});
export default tracker.handler;
export const config = {
path: '/*'
};
```
Add the environment variable in the Netlify dashboard under **Site configuration → Environment variables**.
## The LIGHTSAGE\_API\_KEY
Your API key connects the middleware to your Lightsage account. Find it in your Lightsage dashboard under **Settings → API Keys**.
Never commit your `LIGHTSAGE_API_KEY` to version control. Use environment variables in your deployment platform — `.env.local` for local development (already excluded by `.gitignore` in most frameworks), and the platform's secret management for production.
## The matcher config (Next.js and Vercel)
The `matcher` pattern controls which routes the middleware runs on:
```typescript theme={null}
export const config = {
matcher: ['/((?!api|_next|admin).*)'],
};
```
This regex matches every path **except**:
* `/api/*` — your own API routes (no need to track these)
* `/_next/*` — Next.js internal assets and static files
* `/admin/*` — your admin panel (if one exists)
If your documentation lives on a subdirectory like `/docs`, you can narrow the matcher to only track those pages:
```typescript theme={null}
export const config = {
matcher: ['/docs/:path*'],
};
```
## What you see in the dashboard
After installing the middleware, the **Agent Analytics** section of your dashboard shows:
| Data point | Description |
| ----------------- | ------------------------------------------------------------------ |
| **Agent name** | Which AI agent made the visit (e.g., Claude Code, Cursor, ChatGPT) |
| **Visit count** | Total visits from that agent over your selected time range |
| **Pages visited** | Which specific pages the agent accessed, ranked by visit count |
| **Timestamps** | When each visit occurred, shown in your local timezone |
| **Visit trends** | Day-over-day and week-over-week visit volume per agent |
You can filter by agent, date range, and page path to drill into specific patterns.
## Agents detected
Lightsage's middleware detects all 17 tracked AI platforms:
Claude Code, OpenAI Codex, Cursor, GitHub Copilot, Gemini CLI, OpenClaw, OpenCode, Hermes, Pi, Kilo
ChatGPT, Google AI Overviews, Google AI Mode, Gemini Search, Perplexity, Claude, Microsoft Copilot
The middleware tracks visits from AI agent user agents, not human developer visits. Your existing analytics tools continue to capture human traffic normally. Agent Tracking adds a parallel view of your AI audience without replacing or interfering with any existing analytics setup.
## Performance impact
The middleware operates asynchronously — it sends tracking data to Lightsage without blocking the request. For your human users, response times are unaffected. For AI agent visits, tracking adds no perceptible delay because agents are making HTTP requests regardless and aren't sensitive to single-digit millisecond differences.
Lightsage does not proxy your traffic. Requests go directly from the agent to your server; the middleware reads the request headers and fires a non-blocking event to Lightsage in the background.