KO | EN

GitLite

Minimalist Open Source Repository Search Engine

gitlite — search

#developer-tools #typescript #dsh #dsh-plugin #ai-agent #codex #ai-agents #deepseek-harness #claude-code #cli #react #mcp

simulacra

★ 58 Open GitHub ↗

Ghost personas review your code before it ships. Find edge cases, race conditions, and business logic bugs before production.

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

<h1 align="center">Simulacra</h1>

Your code reviewed by ghost personas before it ships.

<a href="#before--after">Before/After</a> •
 <a href="#install">Install</a> •
 <a href="#the-ghosts">The Ghosts</a> •
 <a href="#skill-scorer">Skill Scorer</a> •
 <a href="#how-it-works">How It Works</a> •
 <a href="#benchmarks">Benchmarks</a>

---

## 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](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](LICENSE).

---

Built by <a href="https://github.com/mturac">Mehmet Turac</a> — because production shouldn't be where you find your bugs.

simulacra

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README