Getting started

Before you start

Install Bun 1.1 or newer. Ayjnt uses Bun for its CLI, host runtime, package management, and compiled executables.

Create the project

bunx ayjnt new my-agent
cd my-agent
bun install
bun run dev

Open http://localhost:8787. The starter includes a stateful counter and a small browser interface. Changes to agent code and UI code are picked up while the development server runs.

Add a browser interface

Put app.tsx beside an agent. Ayjnt generates a typed useAgent() hook for that route and serves the interface at the same URL as the agent instance.

// agents/counter/app.tsx
import { useAgent } from "@ayjnt/counter";

export default function Counter() {
  const agent = useAgent();
  return (
    <button onClick={() => agent.call("increment", [1])}>
      Count: {agent.state?.count ?? 0}
    </button>
  );
}

Visit /counter/demo. The final segment names the instance, so /counter/alice is a separate stateful agent.

Add a terminal interface

A root cli.ts is the foreground program for local and compiled harnesses. It runs in Bun and receives typed handles to every agent.

// cli.ts
import type { AyjntCli } from "@ayjnt/cli";

export default async function ({ agents }: AyjntCli) {
  const counter = agents.counter("demo");
  console.log(await counter.increment(1));
}

Run it with bunx ayjnt run. When the function returns, the local runtime shuts down cleanly.

Choose the next capability

• Use tools.ts for tools that should run with the agent.
• Use tools.host.ts for explicit access to files, shells, SQLite, and other Bun APIs.
• Use workflow.ts for durable, multi-step jobs.
• Use scheduling methods when an agent should wake itself later.

See the curated examples for complete applications of each pattern.