Getting started

simulacra is a Bun project. Clone it to run the CLI, the examples and the GUI, or add @misakaikato/simulacra as a dependency to call the public API from your own code; the package ships the same simulacra binary.

Install

Requires Bun 1.3 or newer.

git clone https://github.com/misakaikato/simulacra.git
cd simulacra
bun install

As a dependency:

bun add @misakaikato/simulacra

Three commands

Run the echo-chamber example with the deterministic mock provider:

bun run simulacra run examples/echo_chamber/scenario.yaml --seed 7 --provider mock --out runs/echo

Audit the prisoner's dilemma example across persona format, framing, and memory representation:

bun run simulacra audit examples/prisoners_dilemma/audit.yaml --replications 5 --provider mock --out audits/pd

Open the GUI over the runs and audits you just produced:

bun run simulacra serve --data .

With a real model, set SIMULACRA_LLM_API_KEY and drop --provider mock. Any OpenAI-compatible endpoint works. DeepSeek is the default, with thinking disabled in the preset so structured answers fit small token budgets; mlx-lm and LM Studio presets are one flag away. Run bun run simulacra doctor --llm first to check structured-output support, concurrency, and cached-token reporting.

The prisoner's dilemma and echo chamber ship with recordings made against deepseek-v4-flash at the benchmark's size, so replaying them offline means matching that size: --llm-mode replay --ticks 5 for the prisoner's dilemma, and --ticks 3 with population.n 20 for the echo chamber (bun bench/llm.ts runs both). A prompt the recordings do not cover is a replay miss, reported as a failure rather than a silent live call. Use --llm-mode record to make your own at any size.

What a run produces

runs/echo/
  scenario.json      the effective scenario
  events.sqlite      every event, queryable with SQL
  log.jsonl          structured log with runId, tick, component
  checkpoints/<n>/   world snapshot, clock, executor and provider state
  result.json        metrics, integrity counts, cost

Inspect one agent's causal chain at a tick, from observation through prompt to decision and effects:

bun run simulacra inspect runs/echo --agent <id> --tick 3

Replay the effects to any tick and compare the world hash with the checkpoint:

bun run simulacra replay runs/echo --to-tick 10

Resume from a checkpoint. Intervention and questionnaire steps that come after the checkpoint are skipped on resume; run them from a fresh start.

bun run simulacra resume runs/echo/checkpoints/5 --ticks 5 --out runs/echo-resumed

Next

• Scenarios: every top-level field of scenario.yaml, with its type and default.
• Audits: the plan document, the perturbation-axis catalogue and how the report grades evidence.
• Plugins: actions, modules, providers, policies, metrics and adapters as one file plus a register call.
• CLI, HTTP API, MCP and GUI: the four entry points over one public API.
• Live report: an audit report generated when this site was built.