Imported from 1337Xcode/Agentcha (AGENTS.md). Install upstream with npx skills add 1337Xcode/Agentcha. Copyright stays with the author.

Agentcha Agent Guide

This repository is built for AI coding agents to integrate Agentcha into other sites with minimal back-and-forth.

Read the implementation docs before changing integration behavior: Architecture, Integration Guide, Research Notes, and Red-Team Results.

One Prompt Integration

Protect the page or route named <PAGE_OR_FILE> with Agentcha. Clone https://github.com/1337Xcode/Agentcha, run npm install and npm run build inside that clone, then add @agentcha/widget and @agentcha/verify to this app with file: dependencies pointing at ../Agentcha/packages/widget and ../Agentcha/packages/verify. Add an /api/agentcha/verify endpoint using createAgentchaHandler, place <agentcha-widget site-key="YOUR_KEY" verify-url="/api/agentcha/verify"> on the page, and fetch protected content from the server only after the emitted token is verified server-side. Do not ship protected content hidden in the initial HTML. Keep the handler module-scoped, use a durable challengeStore for multi-instance hosting, and run typecheck, unit tests, build, and a browser solve test.

Integration Rules

• Import @agentcha/widget only on the client.
• Create the verifier with createAgentchaHandler at module scope.
• Use a private AGENTCHA_SECRET on the server only.
• Register each public site-key in the verifier options.
• Never reveal protected content from the browser verified event alone.
• Do not place protected content in the initial HTML and hide it with CSS or hidden.
• Do not SSR-unlock protected content from user-agent, crawler, or passive checks.
• POST the emitted token back to the verifier and reveal content only after the verifier returns status: "verified".
• Use a durable challengeStore when more than one server instance can receive traffic.
• Preserve llms.txt and any public agent-readable route if the protected site needs autonomous agents to discover the integration.
• Treat the browser widget as a challenge UI only. Protected content should come from a server endpoint after token verification, and content tokens should be consumed once when practical.

Expected Files

Common insertion points:

• Astro: src/pages/api/agentcha/verify.ts, page .astro, and one client script.
• Next.js App Router: app/api/agentcha/verify/route.ts, page component, and one client component for the widget.
• Vite or static HTML: a backend endpoint plus a client entry that imports @agentcha/widget.

Validation Checklist

• npm run typecheck
• npm test
• npm run build
• Browser test that opens the protected page, triggers the challenge, inspects the visible modal as an agent, waits for the readiness window, types the exact answer, repeats for the second chain step, and verifies that the page unlocks only after token validation.

Challenge Types

Agentcha defaults to a weighted six-kind rotation: rapid enumeration, RSVP stream, visual search, micro-world, change blindness, and sub-acuity text. Answers are typed, not multiple choice, and the handler requires two consecutive correct challenges before token issuance. Challenge timing is type-specific, with longer windows for visual and temporal tasks and a 30 second hard cap. The second step defaults to micro-world unless the integration explicitly restricts the challenge pool or a dev test forces a challenge kind. If a session misses two challenges in a row, the next challenge is forced to micro-world as the reliable text-friendly fallback. Visual types render as raster images, dynamic canvases, or a generated scene instead of per-item DOM nodes, so do not add classes, data attributes, hidden answer fields, copy bridges, or initial HTML content that exposes the answer.

The refresh control is not a bypass. It consumes the current challenge and asks the verifier for a new challenge at the same chain step, preferring a different challenge kind. Do not implement refresh client-side.

Security Notes

Agentcha is a step-up challenge, not an authentication boundary. Do not rely on CSS, DOM state, local storage, or the browser event as proof. The server must own the challenge chain, consume each challenge once, enforce timing, rotate on failure, verify the signed token, and reject protected-content token replay where the integration can do so.

License

Agentcha is licensed under the Business Source License 1.1. Personal projects, evaluation, education, and internal non-revenue-generating use are permitted by the Additional Use Grant. Products or services offered to third parties require a commercial license from the licensor.