@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

pnpm add @composio/is-browser-agent

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.

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

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.

"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:

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

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

Type safety

detectIsBrowserAgent returns a discriminated union:

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

That means TypeScript narrows automatically:

const detection = detectIsBrowserAgent(userAgent);

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

API

detectIsBrowserAgent(userAgent)

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

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

isCodexUserAgent(userAgent)

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

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

useIsBrowserAgent()

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:

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

pnpm install
pnpm check
pnpm test
pnpm build