Install and run

Get from a fresh checkout to a locally running Spell program. Java and Clojure are runtime prerequisites; Node is used only to build this documentation site.

Prerequisites

• Java 11 or newer
• Clojure CLI
• A provider credential for model-backed runs, or the built-in test provider for a smoke test

On macOS:

brew install clojure/tools/clojure

Clone the repository:

git clone https://github.com/lukejoconnor/spell.git
cd spell

No application build step is required. bin/spell invokes the Clojure CLI entry point.

Verify the checkout

These commands make no model API call:

bin/spell -h
bin/spell -t "Return a short greeting"

The test provider verifies Java, Clojure dependencies, argument parsing, and evaluator wiring.

Run a model-backed task

The CLI default uses GPT-6 Astra through codex-tc, with medium reasoning. It reads local Codex authentication from ~/.codex/auth.json; sign in with Codex before running:

bin/spell "Inspect the examples directory and suggest one program to run."

Select another configured provider with -m; run bin/spell -h for the options in your checkout.

Try an example

bin/spell -e hello-world
bin/spell -e coin-flip
bin/spell -e twenty-questions -d 40

Example	What it demonstrates
Hello world	A minimal self-call
Coin flip	Recursion and a programmatic stopping condition
Twenty questions	A multi-agent game loop
Telephone	Sequential agent relay
Auction	Parallel agent fan-out
Chat	Interactive agent communication
MCP everything	A local MCP integration

The examples index lists every bundled program and command.

Preview this documentation locally

Node is documentation tooling only; it is not a Spell runtime dependency.

npm ci
npm run docs:dev       # development server
npm run docs:build     # production build
npm run docs:preview   # serve the production build

The development and preview commands print the local URL. npm run docs:check also checks conflict markers and the production build.

Next

Read How Spell works to understand why a completion is a program, or go to capabilities to choose what an agent can do.