Scripts

Scripts are TypeScript files in src/scripts/. They orchestrate work: load context, call the agent, process results, write files. This is the primary authoring unit — most of what your agent does is a script.

// src/scripts/review.ts
const { file } = defineArgs<{ file: string }>()

const content = await axon.tools.fs.readFile(file)
const prompt = await axon.prompt("review", { file, content })

const { stream } = axon.stream({ prompt })

for await (const entry of stream) {
    if (entry.type === "text") process.stdout.write(entry.content)
}

A script can do anything TypeScript can do. Calling the agent is one option, not the default — the script decides when reasoning is needed. Fetch data, transform it, and only bring in the agent for the step that actually requires judgment.

The two calls

axon.request() — send a task, await the full result. Use it when you need the answer before continuing.

const result = await axon.request({ prompt })
// result.text — the agent's output, ready to use

axon.stream() — send a task, receive entries as the loop produces them. Use it when output should flow somewhere incrementally — a terminal, an HTTP response, a chat surface.

const { stream } = axon.stream({ prompt })
for await (const entry of stream) { ... }

Both take a plain string as shorthand: await axon.request("summarise the open issues").

Arguments

defineArgs declares what the script takes. Typed, validated at invocation:

const { file, verbose } = defineArgs<{ file: string; verbose?: boolean }>()

axon run review --file src/index.ts --verbose

One script, four doors

The same script runs identically from everywhere. Write it once:

axon run review --file src/index.ts     # headless, from the terminal
  • TUI — press !, pick the script. Output streams into the chat.
  • HTTP route — axon.scripts.stream("review") from a handler in server/api/.
  • Another script — axon.scripts.request("review", { file }).

Headless runs are the fast feedback loop: the agent boots, the script runs, the agent exits. No session to set up, no interface in the way.

Next: Threads — structuring multi-step work.