--- slug: "simulacra" source_type: "readme" source_url: "https://cdn.jsdelivr.net/gh/mturac/simulacra@main/README.md" repo: "https://github.com/mturac/simulacra" source_file: "README.md" branch: "main" ---

Simulacra

Your code reviewed by ghost personas before it ships.

Before/After • Install • The Ghosts • Skill Scorer • How It Works • Benchmarks

Stars License Agents

--- ## Before / After **Without Simulacra** — you ship this: ```typescript 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 ```bash 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 ```bash cp -r skills/simulacra ~/.config/gemini/skills/ # gemini cp -r skills/simulacra ~/.opencode/skills/ # opencode ``` ### Vercel skills.sh ```bash 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): | Ghost | Perspective | Hunts For | |-------|-------------|-----------| | 👤 **The Adversary** | User who breaks things | Race conditions, double-submit, replay attacks, back-button abuse | | 🏢 **Enterprise Edge** | Complex business customer | Multi-currency, tax exemptions, B2B rules, locale, permissions | | 🐵 **Chaos Monkey** | Infrastructure bad day | Timeouts, partial failures, OOM, connection drops, network partitions | | 🧑‍💻 **Junior Dev** *(+request)* | Future maintainer | Readability, magic numbers, implicit knowledge, missing docs | | 📈 **The Scaler** *(+request)* | 1000x traffic | N+1 queries, unbounded loops, missing pagination, memory growth | | 🔒 **The Auditor** *(+request)* | Security & compliance | Injection, auth bypass, data exposure, sensitive logging | | ⏰ **Time Traveler** *(+request)* | 6 months from now | Dependency rot, API deprecation, schema drift, tech debt | 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: | Score | Verdict | |-------|---------| | 80-100 | 🟢 **SHIP IT** | | 60-79 | 🟡 **REWORK** | | 40-59 | 🟠 **MAJOR REWORK** | | 0-39 | 🔴 **SCRAP** | 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: | Metric | Result | |--------|--------| | True positives (real bugs found) | 68/82 (83%) | | False positives (fabricated bugs) | 3/82 (3.7%) | | Unique bugs (not caught by linters) | 41/68 (60%) | | Average ghosts needed to find all bugs | 2.4 | | Bugs found by Adversary ghost only | 23 | | Bugs found by Enterprise ghost only | 12 | | Bugs found by Chaos ghost only | 15 | *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 [![Star History Chart](https://api.star-history.com/svg?repos=mturac/simulacra&type=Date)](https://star-history.com/#mturac/simulacra&Date) --- ## Related - [hermes-supercode-skills](https://github.com/mturac/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](https://github.com/mturac/simulacra/blob/HEAD/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](https://github.com/mturac/simulacra/tree/HEAD/LICENSE). ---

Built by Mehmet Turac — because production shouldn't be where you find your bugs.