ayjnt
documentation

Everything you need to ship an agent.

ayjnt is a thin framework over the Cloudflare Agents SDK. These docs walk you from your first scaffold to the last detail of the build pipeline. Read top-to-bottom to ramp up, or jump straight to the reference for daily lookups.

Start reading Source on GitHub ayjnt on npm
Quick start

From zero to running agent in four steps

  1. 01

    Install Bun

    ayjnt is Bun-first 
    									$curl -fsSL https://bun.com/install | bash
  2. 02

    Scaffold a project

    Minimal or with React UI 
    									$bunx ayjnt new my-app --with-ui
  3. 03

    Install + dev

    wrangler dev with live reload 
    									$cd my-app && bun install && bun run dev
  4. 04

    Deploy

    Git preflight, then wrangler deploy 
    									$bun run deploy
my-app/agents/counter/agent.ts ts 
import { Agent } from "agents";
import type { GeneratedEnv } from "@ayjnt/env";

type State = { count: number };

export default class CounterAgent extends Agent<GeneratedEnv, State> {
  override initialState: State = { count: 0 };

  override async onRequest(): Promise<Response> {
    return Response.json({ instance: this.name, ...this.state });
  }
}
01

Getting Started

  1. Introduction What ayjnt is, who it's for, how it relates to the Cloudflare Agents SDK.
  2. Installation Bun, Cloudflare account, and scaffolding your first project with ayjnt new.
  3. Your first agent Build a working agent end-to-end: write, run, and hit it with curl.
  4. Project anatomy Tour the generated .ayjnt/ directory and the files you author vs the files you never touch.
02

Guides

  1. File conventions agent.ts, middleware.ts, app.tsx, route groups, nested folders — the tree is the config.
  2. Agent state this.state, this.setState, persistence, and the relationship between DOs and agent instances.
  3. Routing & URL shape How folder paths become URLs, route groups, instance id parsing, HTML vs agent dispatch.
  4. Middleware Writing middleware.ts, root→leaf chaining, short-circuiting, response wrapping, context stash.
  5. Inter-agent RPC getAgent<T>(), typed DO stubs, method autocomplete, exception propagation, structured clone args.
  6. Client integration useAgent, agentFetch, the basePath gotcha, and why ayjnt's URL shape is different.
  7. Co-located React UI app.tsx next to agent.ts, the generated typed hook, and Cloudflare Assets under the hood.
  8. MCP agents Extending McpAgent, registering tools, streamable HTTP and SSE, Claude Desktop integration.
  9. Migrations The committed lockfile, stable agentIds, rename detection, and the git-safety contract.
  10. Deployment ayjnt deploy, git preflight checks, wrangler passthrough, environments, secrets.
03

Reference

  1. CLI Every ayjnt command: arguments, flags, exit codes, forwarded-to-wrangler flags.
  2. Runtime API Every module and export the framework provides: ayjnt, ayjnt/rpc, ayjnt/middleware, @ayjnt/*.
  3. Generated files Every file under .ayjnt/ — what it is, whether it's committed, and how it gets regenerated.
04

Troubleshooting

  1. Gotchas Every failure mode we've documented: basePath vs path, DO state persistence, RPC errors, MCP detection.

Cloudflare Agents reference

ayjnt is built on top of Cloudflare's Agents SDK. For API reference, transport details, and Cloudflare-specific features (Workers AI, D1, R2, KV bindings, etc.) consult the official docs. ayjnt is not affiliated with Cloudflare.