# Install Botscent

> For coding agents. Botscent tells a site if an AI agent, not a person, is browsing it, and which agent. It has two halves: a server half that reads what one request declares, and a page half (about 5 KB gzipped) that watches the page for the marks agent browsers leave. Both return `{ type: 'agent' | 'human', agent_name?, reasons }`.

## What to do

1. Run every command yourself. Do not ask the user to run them.
2. Detect the stack. The lockfile gives the package manager (`package-lock.json` npm, `pnpm-lock.yaml` pnpm, `yarn.lock` yarn, `bun.lock` bun). `package.json` dependencies, or `requirements.txt` / `pyproject.toml`, give the framework. Use the matching section below. If none matches, use "A plain script tag" for the page half and `inspect(request)` for the server half.
3. Install the package: `botscent` from npm, and `botscent` from PyPI for a Python server.
4. Add the page half and the server half exactly as the section shows. Both are needed: the server half sees agents that sign or declare their requests; the page half sees agents inside a person's browser.
5. Make re-runs harmless. If a file already imports `botscent/auto`, already exports the Botscent proxy, or already lists the middleware, leave it as it is. Wrap an existing proxy or middleware with `withBotscent` instead of replacing it.
6. Start the site and run `npx botscent check <url>` against it. Fix each `fail`, then run `check` again. Investigate and report each `unknown`; it is not necessarily an error. In particular, an `unknown` server half is expected at an origin with transport off. Keep the default transport unless the deployment meets the shared-cache requirements above. `--json` gives the same result as JSON.
7. Report to the user: the files you changed, the output of `check`, and the cause of any remaining `unknown` results.

Do not add blocking, redirects or other behaviour on the verdict unless the user asks. Botscent only reports what it sees.

```sh
npm install botscent      # Python server half: pip install botscent
```

Each framework below has a tested app in [`examples/`](https://github.com/nalinbhardwaj/botscent/blob/main/examples). After the install, run `npx botscent check <url>` ([Verify](#verify)).

### Next.js

```ts
// instrumentation-client.ts (Next.js 15.3 or later): the page half, before hydration
import 'botscent/auto'
```

Before Next.js 15.3, render `<Botscent />` from `botscent/react` once in the root layout.

```ts
// proxy.ts (Next.js 16 or later): the server half
export { proxy } from 'botscent/next'
```

```ts
// middleware.ts (before Next.js 16): the server half
export { proxy as middleware } from 'botscent/next'
```

If you already have a proxy, wrap it. Do not replace it: `export const proxy = withBotscent(existingProxy)`, with `withBotscent` from `botscent/next`. Before Next.js 16, wrap the middleware the same way.

```tsx
'use client'
import { useBotscent } from 'botscent/react'

export function VerdictView() {
  const verdict = useBotscent() // re-renders when the page verdict changes
  return <pre>{JSON.stringify(verdict)}</pre>
}
```

In a route handler, get the request's own verdict with `await inspect(request)`, from `botscent/server`.

### React, Vue, Nuxt, SvelteKit, Astro

```tsx
// React without Next.js: <Botscent /> starts the page half when it mounts
import { Botscent, useBotscent } from 'botscent/react'
```

```ts
// Vue: the plugin starts the page half. useBotscent() returns a read-only ref
import { Botscent, useBotscent } from 'botscent/vue'
createApp(App).use(Botscent).mount('#app')
```

```ts
// Nuxt: a client plugin. useBotscent() is auto-imported
export default defineNuxtConfig({ modules: ['botscent/nuxt'] })
```

```ts
// SvelteKit: in src/hooks.client.ts. Then read $botscent in any component
import 'botscent/auto'
import { botscent } from 'botscent/svelte'
```

```js
// Astro: both halves. Astro.locals.botscent on on-demand routes
import botscent from 'botscent/astro'
export default defineConfig({ integrations: [botscent()] })
```

SvelteKit and Nuxt have no server adapter. To get the request's own verdict in a route, call `inspect`:

```ts
// SvelteKit: hooks.server.ts or a +server.ts route
import { inspect } from 'botscent/server'
const verdict = await inspect(event.request)
```

```ts
// Nuxt: a Nitro server middleware or route
import { inspect } from 'botscent/server'
const verdict = await inspect(event.node.req)
```

### A plain script tag

```html
<script defer src="/botscent.js"></script>
<!-- Serve node_modules/botscent/dist/botscent.js from your own origin. Add data-debug to log. -->
```

The script has no inline code and no `eval`. With a strict Content Security Policy, allow the script's origin in `script-src` (`'self'` if you serve it). Or put a nonce on the tag and use `'strict-dynamic'`. A bundled import needs no change.

The script adds `window.botscent` (`verdict`, `subscribe`, `reportHeaders`, `diagnostics`, `start`, `VERSION`). It sends a `botscent` event on each verdict change.

### Express, Hono, Cloudflare Workers, Netlify, Vercel

```ts
// Express: req.botscent in every handler
import { botscent } from 'botscent/express'
app.use(botscent())
```

```ts
// Hono: c.get('botscent')
import { botscent } from 'botscent/hono'
const app = new Hono().use(botscent())
```

```ts
// Cloudflare Workers: the verdict is the handler's fourth argument
import { withBotscent } from 'botscent/workers'
export default { fetch: withBotscent(async (request, env, ctx, verdict) => fetch(request)) }
```

```ts
// Netlify Edge Functions: the same adapter, then on to the site
import type { Context } from '@netlify/edge-functions'
import { withBotscent } from 'botscent/workers'
export default withBotscent<Context>((request, context) => context.next())
```

```ts
// Vercel Routing Middleware, for projects that are not Next.js: middleware.ts at the project root
export { default } from 'botscent/vercel'
```

### Python: FastAPI, Starlette, Django, Flask

```python
# FastAPI and Starlette: request.state.botscent
from botscent.asgi import BotscentMiddleware
app.add_middleware(BotscentMiddleware)
```

```python
# Django: request.botscent
MIDDLEWARE = [..., "botscent.django.BotscentMiddleware"]
```

```python
# Flask: flask.g.botscent
from botscent.flask import Botscent
Botscent(app)
```

```python
# Any other framework
import botscent
verdict = botscent.inspect(request)  # a Request, a dict of headers, or anything with .headers
```

## Verify

```sh
npx botscent check https://your-site.example/
```

`check` does three things:

1. It requests the page twice: once with its own user agent, and once with no agent evidence.
2. It opens the page in a local Chrome. Like all automation, that Chrome sets the webdriver flag, so the page half reports an agent.
3. It scans the project in the current directory.

Each check prints `pass`, `fail`, `unknown` or `skipped`, and what it saw. A line that is not a pass also gives the likely cause and the fix. Use `--json` for scripts and agents. Use `--report` for a block to paste into an issue. The exit code is 0 when the install works, 1 when it is broken, and 2 when neither half was confirmed.

## More

- Full documentation: https://botscent.nibnalin.me/docs (every page also as Markdown; index at https://botscent.nibnalin.me/llms.txt)
- This page: https://botscent.nibnalin.me/install.md
