AI agents

Quantum Forge ships machine-readable docs and a headless path, so a coding agent can scaffold, run, and verify a quantum game without a browser. This page is for the agent and for whoever is configuring it.

Where the docs live

• /llms.txt on this site: the whole API in one flat file. Point an agent at https://docs.quantum.dev/llms.txt.
• node_modules/quantum-forge/QUANTUM_FORGE.md in any project that installed the core package: gates, entanglement patterns, measurement, rendering, input, and performance, with examples throughout. Available offline once npm install has run.

Claude Code skill

Pass --claude-skill at scaffold time and the CLI copies QUANTUM_FORGE.md into .claude/skills/quantum-forge/SKILL.md, giving you /quantum-forge in Claude Code.

There is no post-hoc install command yet. To add the skill to an existing project, copy the file yourself:

mkdir -p .claude/skills/quantum-forge
cp node_modules/quantum-forge/QUANTUM_FORGE.md .claude/skills/quantum-forge/SKILL.md

Non-interactive scaffold

Pass every flag and the CLI never prompts:

npx -y quantum-forge-engine init my-game \
  --template starter --platforms web --edition qutrit --no-claude-skill

From quantum-forge-engine 1.3.0 the starter also writes CLAUDE.md and AGENTS.md into the project.

Verifying quantum code headlessly

The WASM loader resolves its artifacts from a URL path by default, which works under Vite but not under bare Node. Call setWasmBasePath() with an absolute filesystem path first, then ensureLoaded(). This works the same in a Node script and in a vitest file.

// check-quantum.ts, run with: npx tsx check-quantum.ts
import { resolve } from "node:path";
import {
  setWasmBasePath,
  ensureLoaded,
  QuantumPropertyManager,
} from "quantum-forge/quantum";

setWasmBasePath(resolve(process.cwd(), "node_modules/quantum-forge/dist"));
await ensureLoaded();

const qpm = new QuantumPropertyManager({ dimension: 2 });
const m = qpm.getModule();

const a = qpm.acquireProperty();  // |0⟩
const b = qpm.acquireProperty();  // |0⟩
m.cycle(a);                       // a → |1⟩
m.i_swap(a, b, 0.5);              // (|10⟩ + i|01⟩)/√2, anti-correlated

const [va, vb] = m.measure_properties([a, b]);
console.log(va, vb);              // always 1 0 or 0 1

qpm.releaseProperty(a, va);
qpm.releaseProperty(b, vb);

Gotchas

Things an agent gets wrong on the first attempt, in roughly the order it hits them.

The CLI lives in the engine package. Use npx quantum-forge-engine init. From core 2.7.0 npx quantum-forge init works as well, because the core package hands off to the engine; on older core releases it fails with "could not determine executable to run".

Imports split across two packages. quantum-forge owns /quantum, /logging, and /vite-plugin. Everything else (/engine, /rendering, /input, /events, /collision, /audio, and the rest) comes from quantum-forge-engine.

Gate names are snake_case and go through getModule(). It's measure_properties([props]), i_swap, inverse_hadamard, phase_rotate. There is no measureProperties or iSwap. probabilities() takes an array too, even for one property.

i_swap requires a fraction. It's a positional argument, not an option. inverse_hadamard and swap take no fraction at all. For gates that do accept one, omitting it calls the discrete gate, which is a different operation from passing 1.0.

Dimension is capped at 3. Shipped builds are Qutrit (dimensions 2 to 3, 12 qudits) or Qubit (dimension 2 only, 20 qubits). Asking for dimension 7 throws.

Engine subclasses must implement getHelpers() and reset(), and getState() returns Readonly<TState>. Never assign into state. Spread it into setState.

QuantumRecorder has no getLog(). Use getOperationLog(), or the array returned by stopRecording().