# @composio/is-browser-agent

> Detect when your site is being opened from an AI-agent browser.

Latest version **0.0.1** (published 2026-05-02) · MIT license · 0 weekly downloads

## Install

```sh
npm install @composio/is-browser-agent
pnpm add @composio/is-browser-agent
yarn add @composio/is-browser-agent
bun add @composio/is-browser-agent
```

## Health

**Score 50/100 (C)** — status: stable.

Positive: esm support; no vulnerabilities.

Warnings: low downloads; no types; pre 1.0.

## Facts

| | |
|---|---|
| Version | 0.0.1 |
| Published | 2026-05-02 |
| First published | 2026-05-02 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | ESM |
| Dependencies | 0 |
| Unpacked size | 6.6 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 0 |
| Author | Composio |
| Maintainers | sarahsimionescu, malayvasa, abir-taheer, jkomyno, cryogenicplanet, haxzie, lingalarahul7 |

## Links

- npm: https://www.npmjs.com/package/@composio/is-browser-agent
- Repository: https://github.com/ComposioHQ/is-browser-agent
- Homepage: https://github.com/ComposioHQ/is-browser-agent#readme
- Issues: https://github.com/ComposioHQ/is-browser-agent/issues
- npm.io page: https://npm.io/package/@composio/is-browser-agent

## Recent versions

- 0.0.1 (latest) — 2026-05-02

## README

# @composio/is-browser-agent

Detect when your site is being opened from an AI-agent browser.

Today this package detects **Codex** user agents. The API is intentionally small and typed so we can add more agent browsers later without changing app-side DX.

## Install

```bash
pnpm add @composio/is-browser-agent
```

```bash
npm install @composio/is-browser-agent
```

## Why

Some AI coding agents and agentic browsers visit normal web pages with their own user-agent token. If your app wants to offer an agent-native path — for example, redirecting Codex to `agents.composio.dev` or showing a special CTA — this package gives you one place to detect that safely.

## Server-safe API

Use the root export anywhere you have a user-agent string: Next.js middleware, route handlers, server components, API routes, edge functions, or plain Node.

```ts
import { detectIsBrowserAgent } from "@composio/is-browser-agent";

const detection = detectIsBrowserAgent(request.headers.get("user-agent"));

if (detection.isBrowserAgent) {
  console.log(detection.agent.id); // "codex"
  console.log(detection.agent.name); // "Codex"
}
```

### Next.js middleware example

```ts
import { NextResponse, type NextRequest } from "next/server";
import { detectIsBrowserAgent } from "@composio/is-browser-agent";

export function middleware(request: NextRequest) {
  const detection = detectIsBrowserAgent(request.headers.get("user-agent"));

  if (detection.isBrowserAgent && detection.agent.id === "codex") {
    return NextResponse.redirect("https://agents.composio.dev");
  }

  return NextResponse.next();
}
```

## React hook

Use the React hook from the `/react` subpath. This entry is client-only.

```tsx
"use client";

import { useIsBrowserAgent } from "@composio/is-browser-agent/react";

export function AgentSignupBanner() {
  const detection = useIsBrowserAgent();

  if (!detection.isBrowserAgent) return null;

  return (
    <aside>
      <p>Hello {detection.agent.name}.</p>
      <a href="https://agents.composio.dev">Sign up as an agent</a>
    </aside>
  );
}
```

## Convenience helper

If you only care about Codex for now:

```ts
import { isCodexUserAgent } from "@composio/is-browser-agent";

if (isCodexUserAgent(userAgent)) {
  // Codex browser detected
}
```

## Type safety

`detectIsBrowserAgent` returns a discriminated union:

```ts
type BrowserAgentDetection =
  | {
      isBrowserAgent: true;
      agent: {
        id: "codex";
        name: "Codex";
      };
    }
  | {
      isBrowserAgent: false;
      agent: null;
    };
```

That means TypeScript narrows automatically:

```ts
const detection = detectIsBrowserAgent(userAgent);

if (detection.isBrowserAgent) {
  detection.agent.id; // typed as "codex"
} else {
  detection.agent; // typed as null
}
```

## API

### `detectIsBrowserAgent(userAgent)`

```ts
function detectIsBrowserAgent(userAgent: string | null | undefined): BrowserAgentDetection;
```

Detects whether the provided user-agent belongs to a supported AI-agent browser.

### `isCodexUserAgent(userAgent)`

```ts
function isCodexUserAgent(userAgent: string | null | undefined): boolean;
```

Returns `true` when the user-agent contains the Codex browser token.

### `useIsBrowserAgent()`

```ts
function useIsBrowserAgent(): BrowserAgentDetection;
```

React client hook that reads `window.navigator.userAgent` after mount and returns the same typed detection shape.

## Supported agents

| Agent | User-agent token |
| ----- | ---------------- |
| Codex | `Codex/...`      |

Example Codex user agent:

```txt
Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Codex/26.429.30905 Chrome/146.0.7680.179 Electron/41.2.0 Safari/537.36
```

## Development

```bash
pnpm install
pnpm check
pnpm test
pnpm build
```

---
_Source: https://npm.io/package/@composio/is-browser-agent · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._
