@infrasity/agent-tracker

Track AI coding agent traffic (Claude Code, Codex, Cursor, Aider…) and LLM crawlers (GPTBot, PerplexityBot, ClaudeBot…) hitting your docs site.

Drop-in middleware. Fire-and-forget beacon. Won't slow down your site.

Install

npm install @infrasity/agent-tracker
# or
pnpm add @infrasity/agent-tracker

Get an API key from Dev Intelligence → Agent Traffic in your Infrasity dashboard.

Next.js (App Router, 13+)

Create or edit middleware.ts at the root of your project:

import { withAgentTracking } from '@infrasity/agent-tracker/next';

export default withAgentTracking({
  apiKey: process.env.INFRASITY_API_KEY!,
});

export const config = {
  // Skip API routes, static assets, and admin paths
  matcher: ['/((?!api|_next/static|_next/image|favicon.ico|admin).*)'],
};

Add the env var:

# .env.local
INFRASITY_API_KEY=infra_live_xxxxxxxxxxxxx

Express

import express from 'express';
import { agentTracker } from '@infrasity/agent-tracker/express';

const app = express();
app.use(agentTracker({ apiKey: process.env.INFRASITY_API_KEY! }));

Generic

If you're on another framework, call track() directly from anywhere that has access to request headers:

import { track, shouldTrack } from '@infrasity/agent-tracker';

if (shouldTrack(request.headers.get('accept'))) {
  track({ apiKey: process.env.INFRASITY_API_KEY! }, {
    host: request.headers.get('host')!,
    path: new URL(request.url).pathname,
    userAgent: request.headers.get('user-agent') ?? '',
    accept: request.headers.get('accept') ?? '',
  });
}

Configuration

| Option | Type | Default | Description | | --- | --- | --- | --- | | apiKey | string | required | API key from your Infrasity dashboard | | endpoint | string | https://app.infrasity.com/api/dev-intelligence/track | Override for self-hosted setups | | timeoutMs | number | 2500 | Hard timeout for the beacon | | debug | boolean | false | Log warnings to console |

What gets tracked

Only requests that look like AI agents or crawlers. Specifically:

• Requests with Accept: text/html or text/markdown (filters out asset, JSON-API, and XHR traffic)
• Server-side classified by User-Agent — anything matching a known coding agent (Claude Code, Codex, Cursor, Aider, Devin, Copilot CLI, etc.) or LLM crawler (GPTBot, PerplexityBot, ClaudeBot, etc.)
• Browser User-Agents are dropped server-side — never stored

What's sent

Only request metadata. Never page contents, query params (unless you opt in), or cookies.

{
  "host": "docs.acme.com",
  "path": "/sdk/python/quickstart",
  "user_agent": "claude-code/0.5.2",
  "accept": "text/html,application/xhtml+xml",
  "country": "US",
  "referer": null
}

Local development

Don't set INFRASITY_API_KEY in your dev environment, or use a separate dev key. The middleware no-ops when the API key is empty.

License

MIT