mockcrowd 0.4.0

An AI population designer. mockcrowd designs crowds of AI personas whose traits connect the way real people's do. It scores real posts on traits such as budget sensitivity, trust and how much a problem hurts, measures how those traits move together, and designs each persona to fit. Every persona cites the real posts behind it.

Then put the population to work: they vote blind against a bland control, argue in a simulated Reddit thread, and tell you whether your idea has demand, who would pay, and why the rest would not.

It runs on your machine, on the AI you already have: Claude Code, Codex, Code Puppy, Ollama, or any OpenAI compatible API.

pip install mockcrowd
mockcrowd design "people who forget about their subscriptions" --pin vendor_trust=low -o crowd.json   # design a population
mockcrowd validate "An app that finds and cancels forgotten subscriptions" --price "\$4.99/month"             # test an idea on one

How personas are designed

Most persona tools invent people from a prompt, one trait at a time, so traits never relate to each other. mockcrowd measures the relations first.

1. Score real posts. Each post is scored from 0 to 1 on six core traits (budget sensitivity, tech savvy, status quo attachment, switching cost, vendor trust, pain urgency) and up to four traits the planner picks for your audience. Each score is marked stated (the post shows it) or inferred (the AI is estimating).
2. Measure the links. How the traits move together in each segment. Small segments are pulled toward the pooled posts, so thin evidence cannot invent structure.
3. Sample personas from the links. Each persona's trait profile is drawn conditional on its stance, and on any traits you pin. The links move the other traits with it.
4. Ground each one. The profile is matched to the three real posts nearest to it, and the AI writes the person to fit. Each persona cites those posts.

A real example: 40 personas for a subscription cancelling idea, built from 130 real posts. The strongest links in those posts were cancellation friction pain with pain urgency (+0.57), pain urgency with status quo attachment (-0.57) and cancellation friction pain with vendor trust (-0.51). Pinning a core trait such as vendor_trust=low shifts the traits linked to it, and the rest of the profile follows.

The report shows the strongest links and how closely the crowd reproduces them, next to a crowd that draws traits independently. mockcrowd personas <run-id> exports any run's personas with their traits and source posts.

Test an idea on the population

A real small run (20 personas, 1 discussion round, Claude, Hacker News and Bluesky voices): alone, 60% said they would try the idea free and 5% would pay. After the discussion, 35% would try it and nobody would pay. That is the kind of answer you want before you spend a month building.

For something nobody pays for, such as an open source feature, add --free: the crowd is asked whether they would use it, and the verdict compares interest with a bland control. To backtest on a real feature request, add --exclude github.com/owner/repo/issues/123 so the crowd never sees the issue it is scored against.

Install

pip install mockcrowd      # or: uv tool install mockcrowd
mockcrowd brains           # shows which AI it can use

Python 3.10 or newer. One small dependency (certifi). Once a day mockcrowd prints one line when a newer version is on PyPI, and never installs anything. Upgrade with pip install -U mockcrowd. Turn the check off with MOCKCROWD_NO_UPDATE_CHECK=1.

Pick the brain

mockcrowd uses the first one it finds, or the one you pass with --brain.

Claude has been run live end to end. The Codex, Code Puppy, Ollama and OpenAI adapters are tested against the flags and API each tool documents, but not yet in a live run; reports are welcome. Claude and Code Puppy run with tools off. Codex runs in its read only sandbox, which blocks writes but not reads, so prefer the others if your machine holds sensitive files.

--model is passed through exactly as you write it. A 500 persona run makes roughly 100 to 150 LLM calls, because one call steps a whole batch or thread of personas. OPENAI_API_KEY is only used with api.openai.com; other endpoints need MOCKCROWD_API_KEY.

Real voices

Each source that fails is listed in the report, and confidence drops when evidence is thin.

Use it from an AI agent

Skill. mockcrowd install-skill installs it for Claude Code (--dir <skills dir> for any agent that reads SKILL.md files). Then ask: "design 100 personas for people who forget subscriptions" or "validate my idea for a vinyl app at $3.99 a month". When a source is blocked, the agent can gather posts with its own web tools and pass them in.

MCP. Any MCP client (Claude Code, Cursor, Codex, Claude Desktop, your own agent) can use mockcrowd over stdio. It is listed in the official MCP Registry as io.github.phanisaimunipalli/mockcrowd.

pip install "mockcrowd[mcp]"
claude mcp add mockcrowd -- mockcrowd mcp

{"mcpServers": {"mockcrowd": {"command": "mockcrowd", "args": ["mcp"]}}}

To always run the newest release without installing: {"command": "uvx", "args": ["--python", "3.12", "mockcrowd[mcp]@latest", "mcp"]}.

Agent runs default to 60 personas and 1 round to keep them quick.

Commands

mockcrowd design "audience" [--agents 100] [--pin TRAIT=low|medium|high|0.8] [-o crowd.json]
                            [--voices file.jsonl] [--no-live] [--source reddit|hn|bluesky|github|appstore]
mockcrowd validate "idea" [--price P | --free] [--audience A] [--agents 500] [--rounds 2]
                          [--voices file.jsonl] [--no-live] [--source reddit|hn|bluesky|github|appstore]
                          [--exclude TEXT]
                          [--question "choice:first:Which feature first?:scan|alerts|wishlist"]
                          [--brain auto|claude|codex|code-puppy|ollama|openai] [--model M]
mockcrowd collect "idea" -o voices.jsonl   # only gather real posts
mockcrowd runs                             # list past runs
mockcrowd report <run-id> [--json]
mockcrowd personas <run-id> [-o file.json] # export a run's personas, traits and source posts
mockcrowd outcome <run-id> --demand high|medium|low --note "what really happened"
mockcrowd eval --suite quick|full|backtest [--gate]

Trait names for --pin are printed in the design output (dims). Runs are saved in ~/.mockcrowd/runs/<run-id>/ as report.md and run.json (every voice, persona, vote and comment). A design is printed, or written where you point -o; it is not saved as a run.

How a validation run works

1. Plan. The brain reads your idea and lists the segments (including people who would not buy), subreddits, search queries and audience specific traits.
2. Collect and label. Real posts from the sources above, each given a segment, relevance, pain, stance and trait scores. Irrelevant posts are dropped.
3. Design. The personas, as described above, in the segment shares and stance mix the real posts show.
4. Blind vote. Every persona answers alone: interest, would try free, would pay, biggest objection, plus your own typed questions. The real idea and a bland control appear side by side in random order.
5. Discuss. Threads of about 20 mixed personas, one action each per round on a ranked feed.
6. Final vote and report. Shares with 95% intervals, lift over control, shift after discussion, results by segment, objection themes, trait links and a confidence score.

Evals and continuous improvement

mockcrowd eval scores the simulator itself and appends to ~/.mockcrowd/evals/history.jsonl. With --gate it exits 1 when any metric falls more than 5 points below its best.

The backtest ships with 13 cases: six with record crowdfunding or user growth (for example Pebble Time, Exploding Kittens, Flow Hive) and seven well known flops (for example Juicero, Quibi, Fire Phone). Each case cites its source, and pitches are anonymized.

Your outcomes are the strongest signal. After you test or launch, run mockcrowd outcome <run-id> --demand .... The run becomes a backtest case, and future confidence scores include how well mockcrowd did on cases like yours.

Honest limits

• It is a simulation. Use it to rank ideas, find objections and choose what to test for real, not to forecast revenue.
• Personas reflect the people who post online, who are louder and more opinionated than most buyers. A post is not a person.
• Most trait scores are inferred by the AI, not stated in the post, so the measured links partly reflect the AI's own assumptions. Reports print the stated share. Links are correlations, not causes. Below 8 scored posts, traits are drawn independently and the report says so.
• Whether structured traits make verdicts more accurate is not yet measured.
• Backtest products are famous, so models may know how they ended. Watch the leakage metric.
• The verdict thresholds are starting points. The backtest reports how well they separate hits from flops on your brain.

Credits

Simulation design follows OASIS by CAMEL-AI (Apache 2.0). The idea of building a world from seed material and simulating it was inspired by MiroFish. No code from either project is included. See NOTICE.

License

Apache 2.0