- Coding agents: Claude Code, OpenCode, Cursor, GitHub Copilot, OpenAI Codex, Gemini CLI, OpenClaw, Hermes, Pi, Kilo
- Answer engines and crawlers: ChatGPT, Google AI, Perplexity, and their associated crawlers
Getting your API key
Find yourLIGHTSAGE_API_KEY in your Lightsage account settings. Store it as an environment variable — never commit it to source control.
Installation
Installing the package
- npm
- pnpm
- yarn
The matcher config
For Next.js and Vercel, thematcher config controls which routes the middleware runs on. The pattern /((?!api|_next|admin).*) means: run on all routes except those starting with api/, _next/, or admin/.
You should exclude:
api/— your own API routes (you don’t need to track server-to-server calls as agent visits)_next/— Next.js static assets and build artifactsadmin/— internal tooling that agents shouldn’t be visiting anyway
What you see in the dashboard
Once the middleware is deployed and agents begin visiting your site, the Lightsage dashboard shows:- Agent identity — which coding agent made the visit (Claude Code, Cursor, etc.)
- Pages visited — which documentation pages the agent read, in order
- Visit frequency — how often each agent crawls your docs
- First seen / last seen — when an agent first discovered your docs and when it most recently visited
- Correlation with recommendations — Lightsage links agent visit patterns to your prompt tracking data so you can see whether agents that crawl your docs more frequently also recommend you more often
The first agent visits may appear in your dashboard within minutes of deploying the middleware, depending on how actively the agents currently crawl your domain. If you see no visits within 48 hours, verify that your robots.txt is not blocking AI crawlers. See Optimize your API for AI coding agent discovery for the robots.txt configuration.