simulacra

Before / After

Without Simulacra — you ship this:

function applyDiscount(cart) {
  if (cart.total >= 500) {
    cart.items.forEach(item => item.price *= 0.8);
  }
  return cart;
}

"Looks fine. Ship it." ✅

With Simulacra — three ghosts find three bugs:

👤 Reckless Rick (The Adversary): "Your forEach mutates prices in place. I hit Back twice — 630 TL cart drops to 322 TL. Your company eats the 308 TL difference."

🔥 IDEMPOTENCY — 🔴 Critical

👤 Corporate Claire (Enterprise Edge): "I'm paying in EUR. cart.total = 200 fails the >= 500 check. My 7000 TRY order gets no discount. I'm switching vendors."

🔥 BUSINESS-LOGIC — 🟠 High

👤 OOM Reaper (Chaos Monkey): "Memory spike at item 7 of 14. Half the cart is discounted, half isn't. No rollback. The corruption persists to your database."

🔥 PARTIAL-FAILURE — 🔴 Critical

Three bugs. Zero lines of test code. Before the PR even opens.

Install

Claude Code (official plugin)

/plugin marketplace add mturac/simulacra
/plugin install simulacra@simulacra
/plugin install skill-scorer@simulacra

Codex CLI

cp -r skills/simulacra ~/.codex/skills/
cp -r skills/skill-scorer ~/.codex/skills/

Cursor / Windsurf / Roo

Copy skills/simulacra/SKILL.md to your project's .cursor/skills/ (or equivalent) directory.

Gemini CLI / OpenCode / GitHub Copilot CLI

cp -r skills/simulacra ~/.config/gemini/skills/   # gemini
cp -r skills/simulacra ~/.opencode/skills/         # opencode

Vercel skills.sh

npx skills add mturac/simulacra

Manual (any agent)

Copy the skills/ folder to your agent's skill directory. The skills are pure markdown — no dependencies, no build step, no runtime.

The Ghosts

Every code review spawns 3 ghost personas by default (up to 7 on request):

Each ghost produces:

• Chaos Timeline — step-by-step simulation with realistic timestamps
• Structured Testimony — what they did, what broke, evidence from your code
• Bug Report — category, severity, affected line, fix suggestion
• JSON Output — machine-readable for CI pipelines and issue trackers

Skill Scorer

Bonus skill included. Rate any SKILL.md on a 0-100 scale.

> Score this skill: [paste any SKILL.md]

10 dimensions. Weighted composite. SHIP / REWORK / SCRAP verdict:

Calibrated against Anthropic's own skill-creator rubric. Average skill scores 45-55.

How It Works

┌──────────────┐
│  Your Code   │
└──────┬───────┘
       │
       ▼
┌──────────────┐     ┌─────────────────────────┐
│ Complexity   │────▶│ Trivial? → One-line      │
│ Gate         │     │ "Low risk" + stop        │
└──────┬───────┘     └─────────────────────────┘
       │ Non-trivial
       ▼
┌──────────────┐
│ Butterfly    │  6 checks: idempotency, mutation,
│ Effect Scan  │  transactions, races, cache, biz logic
└──────┬───────┘
       │
       ▼
┌──────────────┐
│ Ghost        │  3-7 personas spawned
│ Personas     │  Each with unique failure perspective
└──────┬───────┘
       │
       ▼
┌──────────────┐
│ Structured   │  Timeline + Testimony + Bug Report
│ Simulation   │  per ghost (mandatory slots)
└──────┬───────┘
       │
       ▼
┌──────────────┐
│ Resolution   │  Tier 1: Quick Fix
│ Tiers        │  Tier 2: Robust Architecture
│              │  Tier 3: Generated Test Suite
└──────┬───────┘
       │
       ▼
┌──────────────┐
│ JSON Output  │  Machine-readable bug report
│ + Summary    │  for CI/CD and issue trackers
└──────────────┘

Benchmarks

Simulacra v2 tested against 25 common code snippets with known bugs:

Methodology: 25 TypeScript/Python snippets with seeded bugs (idempotency, race, partial-failure, business-logic). Each run 3x. Scored against known bug list.

Philosophy

Bugs are characters, not warnings. Static analyzers give you lint errors. Simulacra gives you stories. A story about Rick hitting the back button three times is more memorable — and more actionable — than "potential mutation detected."

Silence is better than noise. If a ghost can't find a real bug, it says so. No fabricated issues to seem thorough. The complexity gate ensures trivial code doesn't get forced theater.

Structured output is a first-class citizen. Every simulation produces JSON alongside the narrative. Your CI pipeline can consume it. Your issue tracker can import it. The ghosts are entertaining but the data is what ships.

Star History

Related

• hermes-supercode-skills — Claude Code skills for security auditing (security-sentinel), deep debugging (quantum-debugger), and API review (api-sculptor) — complement Simulacra's ghost persona reviews

Contributing

See CONTRIBUTING.md. The easiest way to contribute:

• Add a new ghost persona
• Add a demo analysis in skills/simulacra/demo/
• Score an interesting SKILL.md and add the scorecard to skills/skill-scorer/examples/

License

MIT — see LICENSE.