@awasero/citela

Google Search Console for AI answers. Know when AI crawlers — GPTBot, ClaudeBot, PerplexityBot, Google-Extended and friends — read your site. One command.

npx @awasero/citela init
# ✓ Listening for AI crawlers.

Then watch them arrive:

npx @awasero/citela report

  Citela — AI crawler activity  (last 7 days)

  Verified crawls by bot
       12  GPTBot (openai, crawler)
        4  PerplexityBot (perplexity, crawler)
        3  ClaudeBot (anthropic, crawler)

  Most-read pages
        9  /pricing
        6  /docs

Why

If ChatGPT, Claude, or Perplexity never read your site, they can't recommend your product. Client-side analytics can't tell you — AI bots don't run JavaScript. Detection has to happen server-side, in middleware. That's what this is.

It works standalone, with no account: a local ring buffer records verified crawler hits and citela report prints them. Connect an API key to stream events to Citela for real-time alerts ("GPTBot read your /pricing 4 minutes ago"), answer tracking, and one-command fixes your coding agent can ship.

Install

npx @awasero/citela init            # standalone
npx @awasero/citela init --api-key <key>   # connected: streaming + real-time alerts

init is non-interactive and idempotent — safe to run from a coding agent, safe to re-run. It:

• writes (or wires into) your middleware.ts
• installs a tiny local sink route (app/api/_citela) for standalone mode
• adds .citela/ to your .gitignore

Supports Next.js (App & Pages Router) today. Express / Astro / SvelteKit adapters are on the roadmap.

What it detects

A maintained registry of AI crawlers and on-demand fetchers, with anti-spoof IP verification against published vendor ranges. User-agents are trivially spoofable, so unverified hits are recorded but excluded from headline counts — a number you can trust.

Detected: GPTBot, OAI-SearchBot, ChatGPT-User, ClaudeBot, Claude-User, PerplexityBot, Perplexity-User, Google-Extended, GoogleOther, Bingbot, Meta-ExternalAgent, Amazonbot, Applebot-Extended, Bytespider, CCBot — refreshed regularly when connected.

Safety

The sensor is built to be invisible to your app:

• Total try/catch — no exception can escape into your request path.
• < 1ms p99 overhead — user-agent match then a fire-and-forget send; no inline network calls.
• < 20KB, zero runtime dependencies.
• Never logs human visitor data. Only matched bot hits are recorded — the bot, the path, the timestamp. Nothing about your human visitors.

Manual wiring

init writes this for you, but if you manage your own middleware:

import { NextResponse } from 'next/server';
import { collect, CITELA_MATCHER } from '@awasero/citela';

export function middleware(request, event) {
  collect(request, event); // fire-and-forget; never throws
  return NextResponse.next();
}

export const config = { matcher: CITELA_MATCHER };

Telemetry

init sends an anonymous, opt-out install ping: a random install id, the framework, and whether an agent ran it. No site data, no visitor data. Disable with CITELA_TELEMETRY=0 or DO_NOT_TRACK=1.

Commands

| Command | Description | |---|---| | citela init [--api-key <key>] [--agent] [--dir <path>] [--json] | Install the sensor | | citela report [--days <n>] [--json] | Print recent AI-crawler activity | | citela help | Show help |

License

MIT © Awasero