MarketMirror

Try it (Linux, macOS or WSL; needs Git, uv and Python 3.12):

git clone https://github.com/DarkWorldCoder/market-mirror.git && cd market-mirrorbash install.sh --configure      # installs the engine, then asks which model provider to use./mm start && ./mm cli quickstart --out scenarios/acme   # 9 questions; prepares a small simulated market, then stops for review

The last line already makes model calls on the provider you chose, so start with a small market. If you chose a Claude Code or Codex login, run ./mm gateway start claude (or codex) before it. Already in an MCP client? Add the server with claude mcp add market-mirror -- uvx marketmirror (any client: command uvx, args ["marketmirror"]), then ask your agent to run doctor and setup. Full quick start.

If MarketMirror saves you one bad launch, a ⭐ helps other people find it. To hear about new tests and releases, use Watch → Custom → Releases.

What is MarketMirror?

MarketMirror gives you a practice audience for your next marketing decision. Describe your product and the people you want to reach. It creates AI-generated people who can react to your ads, compare prices, ask questions, raise concerns, and respond to a sales pitch.

You get a report explaining what interested them, what put them off, what to change, and what to test with real customers next. You can also watch the simulation and explore the results in a dashboard.

For example: you are launching a fitness app. Should the ad lead with “15 minutes a day” or “less than one gym visit”? Should the free trial ask for a payment card? MarketMirror lets you rehearse those choices before a live campaign.

The buyers are simulated. Their responses are generated by AI, so use them to develop and compare ideas. Confirm promising findings with real customers and small live experiments.

Who is it for?

Meet the simulated buyers

A simulated buyer is an AI-generated character representing someone in your intended audience. The character has a background and practical reasons for accepting, questioning, or rejecting an offer.

You choose the groups you want to explore—for example, students, working parents, and young professionals in selected countries. MarketMirror creates different people within those groups and can ask them about their lives before showing them your marketing.

An illustrative buyer: a busy parent who wants short home workouts, uses a budget phone, and worries about surprise charges. They might like a low monthly price but reject a “free” trial that immediately asks for a payment card. Another buyer may care more about workout quality than price. These are invented examples, not findings from real customers.

In tests within the same run, buyers can remember earlier experiences. Someone who disliked an ad can carry that reaction into a later survey or pitch. Separate comparison scenarios keep their own histories.

Detailed characters help you explore different viewpoints. They do not make the generated answers representative of a real population.

What you can test

You can repeat a comparison to see whether its result changes between runs. You can also use different AI providers and inspect where they disagree. Both help reveal uncertainty within the simulation.

The process at a glance

[MarketMirror workflow: your product, simulated buyers, campaign tests, and the next experiment. Explore with AI and validate with real customers.]

1. Describe your product. Provide a brief, documents, or a website: what you sell, who it helps, what it costs, and what supports your claims. You can also bring linked public feedback or campaign exports.
2. Choose your audience. Describe the groups and locations you want to explore. MarketMirror creates the simulated people. Review their profiles before continuing.
3. Give them something to react to. Add your ads, messages, prices, emails, pitch, or website task. Choose the tests that answer your question.
4. Read the recommendation. Explore the responses, concerns, comparisons, and suggested actions in the report and dashboard.
5. Try a small real experiment. Use actual customer responses or campaign outcomes to check what held up. Import those outcomes for comparison when you have suitable data.

The written report puts one recommendation at the top:

These recommendations summarize simulation signals. A “go” does not guarantee sales.

What you get

Actual product screenshot. Fitloop is an invented example app; all displayed buyer responses and performance figures are simulated. The illustrated banner and workflow above are conceptual artwork.

• A decision and next actions: what to keep, what to change, and what to test with real people.
• Buyer responses: who was simulated, what they said, and their main concerns.
• Comparisons: differences between ads, messages, offers, audiences, and AI providers when those tests were run.
• A shareable report: a saved HTML dashboard that opens without a server, works offline, and includes tables behind its charts.
• Downloadable results: report and data exports in Markdown, JSON, CSV, and PDF.
• A live view: watch progress, buyer activity, and social posts as a run happens.

The full screenshot gallery and detailed explanations follow below.

The dashboard

Each run produces one self-contained HTML dashboard: no server, no external requests, light and dark themes, and phone layouts. A sidebar groups its sections into overview, buyers, tests, evidence and the simulation itself; every chart has a table behind it, and the report exports to Markdown, JSON, CSV and PDF. In runs with more than 500 agents, the agents table lists the 500 most active and says so; everyone is still in the people cards and the CSV downloads. The screenshots below come from the 3,000-person Fitloop market (people written by Claude, Codex and Gemini), except the study page (the offer study) and the live control room (the 1,000-person run). scripts/readme_screenshots.py regenerates them from any run's dashboard.html with your installed Chrome.

Fitloop, its audiences and its pilot figures are invented; every number in these screenshots is simulated, not observed campaign performance. Report generation checks numbers against the run's fact sheet and falls back to a data-only report if the model fails. Those checks establish consistency with saved outputs, not real-world accuracy. The report JSON includes a number_guard list of removed sentences (or study-report table cells), each with text and unknown_numbers, so you can inspect what the guard dropped. These entries are unverified model output, not report evidence; logs record only the removal count.

How it works

One command, market-test, runs the configured pipeline stages from a single config file. Individual tests can also run on their own. Everything a step produces is saved in the run folder, so a stopped run resumes where it stopped.

1. Understand the product

MarketMirror reads your brief, documents or website and writes a product profile: who it is for, the offer, the positioning, the proof, the competitors, and what is still unknown. Every later prompt reads this profile, so the simulated people react to your actual product rather than a vague idea of it.

Your documents also become a small knowledge graph (stored in local SQLite, searched with local embeddings, no extra service). Organisations and public figures in it can join the simulation as accounts that post.

Optionally, research collects what real people already say: Hacker News threads, country-specific App Store reviews, Reddit results and pages you supply, each with its link. Those quotes are shown to the people who write the simulated buyers, so the market starts from real wording.

2. Build the market

You describe the audiences in a small spec: "Students in India, 18-24, 500 people; parents in the Philippines, 30-45, 400 people", plus countries, cities and communities such as a WhatsApp running group or a subreddit. Then, for every person:

flowchart LR    S["Slot<br/>age · gender · city<br/>income · life stage"] --> P["Persona<br/>150-250 words"]    P --> G["Stereotype guard<br/>no two alike in job<br/>and city"]    G --> I["Life interview<br/>12 questions +<br/>first-person summary"]    I --> F["Follow-ups<br/>2 probes · 3 product<br/>questions · decision card"]

• Slots spread each audience evenly over ages, genders, cities (big and small), incomes and life stages, so you never get 500 copies of the same 24-year-old.
• The stereotype guard makes sure no two people in an audience share both a job and a city (it moves one to another city or varies the role, in code, with no model call) and flags any audience whose people came out too alike.
• The life interview asks what a researcher would: Where did you grow up? How is money this month, and what do you cut first? What phone do you use, and what is your data plan like? Tell me about a time you got scammed. Who do you ask before spending real money? What annoys you most in ads? The answers become a first-person summary in the person's own voice and language.
• The decision card is how this person buys: who they ask, how fast they decide, what triggers a yes, what stops them, their dealbreakers, the trust cues they look for, their monthly spare money, and where what they say differs from what they do.
• Communities give people somewhere to talk: each person joins a few of the groups you named, and they follow each other there.

One person from the 3,000-person run, exactly as the model wrote him (abridged):

The people keep a memory for the whole run: someone who hid your ad or ignored your email carries that into the survey and the pitch. With several model providers, each provider writes its own share of the people and plays them from start to finish (mixed markets).

3. Put them in the world

Ads in realistic feeds (the feed test). Each person scrolls a feed for each platform you test (Facebook, Instagram, Reddit, TikTok, LinkedIn, X): a handful of local organic posts with one of your ads placed where that platform puts its sponsored posts. When you test several ads, each person sees exactly one, assigned at random, so the comparison is a split test. For every post they report what they did: scrolled past, stopped and for how long, watched, reacted, commented, shared, saved, clicked or hid it, plus a one-line thought. Platform playbooks hold typical base rates (most people scroll past most ads), which keeps simulated people from being unrealistically positive. You get ads-manager numbers per ad and per audience (thumb-stop rate, CTR, what happened after the click), and with --seeds 3 a range instead of one number.

Social rounds. The people then live on Reddit- and X-like platforms for a few rounds, powered by the OASIS engine with its recommendation feed. Your brand posts and your launch calendar (a price drop on day 3, an influencer post on day 5) arrive in the round you schedule them, and you can push live news into a running simulation ("a competitor just cut its price"). People post, reply, like, follow and argue in their own voices. The dashboard's Social feed shows every post by round, audience and country, with the replies to your brand posts and their sentiment.

4. Ask them

The survey. Everyone answers in their own words: would they try it, how interested are they, do they trust it, would they recommend it. Free text is turned into 1-5 rating distributions with semantic similarity rating (SSR): each answer is compared with five anchor statements using local embeddings, with no extra model calls. Asked for a number directly, language models give narrow, unrealistic rating distributions; rating their own words gives distributions much closer to real survey panels, as the SSR paper reports. The survey can also:

• split-test your messages, with each person randomly shown one;
• ask four price questions and draw the acceptable price range and sweet spot (Van Westendorp);
• re-ask a sample "a simulated week later" and report how many gave the same verdict (test-retest);
• stop early once every audience's answer shares are within a margin you set.

The sales rehearsal. Your pitch goes to every buyer. They answer with their objection, your rebuttals answer back, and they decide again. You get the objections ranked, which rebuttals worked, and a lead score per person ("who to call first").

The analyst panel. Five analysts read the whole run independently and each recommends go, iterate or no-go. Their agreement is a check on the report, not a vote that decides it.

5. Decide

The decision card puts go, iterate or no-go at the top, with the signals behind it: the survey's purchase intent (go needs a mean of 3.75 on the 1-5 scale, iterate 3.1), the feed test's best ad, the analysts, the top objection. The report explains it in plain language: who was simulated, what they said, what stopped them, what to change, an action plan and the limits. Every number in it is checked against the run's fact sheet; if the writing model fails, a data-only report is produced instead.

It all lands in one HTML dashboard that opens without a server and works offline, in light and dark, on a phone. Every chart has a table behind it, and the report downloads as Markdown, JSON, CSV or PDF. A live control room shows a run while it happens: each stage, every person lighting up as they act, and what they post. See the dashboard.

6. Check against reality

Simulated numbers mean little until they are compared with real ones. Import your real ad results or survey answers and MarketMirror:

• backtests its predictions against your past ads;
• calibrates the simulated survey against real answers: overlap, per-audience trust, and a corrected conversion rate;
• forecasts clicks or sign-ups for a budget, using what it learned from those comparisons;
• suggests the next tests from your real ad export and the run.

That loop, from simulation to a small real test and back, is the point: the simulation narrows down what to test; reality decides.

Use cases

Each recipe starts from a prepared simulation (./mm cli quickstart, then market-test with "approve_spend": true). Ask your agent in plain words, or run the command yourself. Results land in the run folder and in the dashboard section named in the last column.

Start with the decision you need to make:

Simulated people remember what happened to them across tests in the same run: someone who hid your ad or unsubscribed from the email carries that into the survey and the pitch. Each study cell keeps its own memory, so scenarios never leak into each other. Set "memory_scope": "off" in a config to test every step on fresh people.

Feed-test previews cover Facebook, Instagram, Reddit, TikTok, LinkedIn, and X. Optional social rounds use the MiroFish/OASIS Twitter and Reddit environments. Search, organic, referral, and sales test families adapt the existing survey, inbox, and pitch engines; they do not reproduce those channels' production systems.

Example results: simulated market studies

These are outputs from documented local runs for Fitloop, an invented fitness app. They demonstrate the workflow and its limitations. They are not observed customer conversion rates or proof of predictive accuracy.

At a glance

[Simulated Fitloop trial-start responses: no card at USD 4.99, 4.1 percent; card required at USD 4.99, 0.2 percent; no card at USD 2.99, 6.7 percent. Whiskers show minimum and maximum across three seeds.]

Seed ranges describe simulation variation. The next step is a small randomized real experiment; the price cut did not establish a predictive win.

The 3,000-person mixed market

One Fitloop market of 3,000 requested people, a third each written and interviewed by Claude Sonnet, Codex (gpt-6-luna) and Gemini 3.8 Flash (gemini-3.8-flash-low). Six audiences in India, the Philippines and Kenya, and five communities: Bengaluru Fitness Buddies (WhatsApp), Working Moms & Dads India (Facebook), Fit Pinoy Community (Facebook), Nairobi Runners & Gym Rats (WhatsApp) and r/budgetfitness; each person joins at most 2. The offer as advertised: a 7-day free trial with no card, then USD 4.99 a month. As in the 1,000-person run, the brief and the landing page still ask for a card at sign-up, and the test is meant to catch that.

Decision: iterate (medium confidence). The survey alone says no-go (purchase intent 2.88 of 5, 0.7% would start the trial, n = 2,999), the feed test says iterate (best ad fb_parents, expected CTR 1.02%), and 5 of 5 simulated analysts say iterate. Fix first: trust ("looks like a scam"), doubt that it is really free, and an unclear product.

The feed test, five ads across 5,140 person-platform sessions:

The pitch made things worse, not better: after hearing the rebuttals, about a fifth of the people moved from "maybe" to "no" (pitch score 23 of 100). The report's fix: rewrite the trust and price rebuttals to show the exact charge after day 7, the cancel steps and the local price instead of arguing, which matches the analysts' themes.

Responses differed across the writer/answerer cohorts. Split by the provider that wrote each person:

[Simulated trial-start responses by buyer writer and answering provider]

The Gemini-written cohort, played by Claude, answered more like the Claude-written cohort than the Codex-written cohort. This suggests checking sensitivity to the answering model, but the cohorts contained different people and the writer/answerer combinations were not fully crossed. This run does not isolate a causal answering-model effect or prove it matters more than the writer. The rates describe these simulated cohorts; they are not forecasts of customer demand.

How the run went. The population took 2 h 57 min to prepare (with one restart), and the feed test 62 min through the three login gateways. The social rounds then ran into usage limits: four times Gemini's or Claude's login hit its limit during the rounds, and each hit started the four rounds over, usually after waiting hours for the reset. Then Gemini's login ran out of quota for about four days (Flash and Argon alike). So the rest of the run moved to an Anthropic API key: Claude Sonnet 5.5 played the Claude-written people and, as a stand-in (MM_PROVIDER_STANDIN=antigravity=claude), the Gemini-written ones; Codex kept playing its own people through its login. From there it ran without a pause: four rounds in 40 minutes, the survey of 2,999 with its retest in 23 minutes, the pitch to 2,999 people in 37 minutes, then the panel and the report. The API spend for that part is on the Anthropic console; MarketMirror did not meter the tokens inside the rounds, survey and pitch.

The population behind it:

• One requested person was not written because their calls failed. They are counted, not filled in.
• The 12 Codex people whose interview failed are kept at depth profile. 82 interviewed people have no decision card.
• Audiences: Students 642, Philippines young professionals 536, India young professionals 534, India parents 429, Philippines parents 429 and Kenya young professionals 429, each split evenly across the three providers. By country: India 1,284, the Philippines 1,125 and Kenya 590.
• The stereotype guard changed 20 people and found no audience with too little variety.
• With 7 actors from the knowledge graph and the 5 community accounts, the simulation has 3,011 agents, each with a profile.
• The feed test made 1,289 model calls (Gemini 442, Codex 440, Claude 407) with 19.9M input and 0.94M output tokens, and lost no session.

Which offer should Fitloop launch with?

A study ran three offers on the same 150 simulated buyers, three seeds each (9 cells, about 10 minutes per cell through the local Claude Code gateway). Each number is the mean across seeds, with the lowest and highest seed in brackets; the brackets show simulation variation only.

What the study concluded. Requiring a card was a clear loss in every seed: intent fell by 0.5, would-start fell by 3.9 points, "maybe" answers fell by 44.8 points, and scam worry rose by 33.6 points, all outside the seed spread. Dropping the price to USD 2.99 lifted would-click (+15.8 points) and trust (+0.47) beyond the spread, but its intent gain (+0.09) stayed inside it, so the price cut is not a clear winner even in simulation. It came out best in 2 of 3 seeds, and the study's summary marks its result as not supporting a predictive claim. The recommendation: keep the trial card-free, work on trust (proof, a named company, a clear "no card needed" line), and run a small randomized real test of USD 2.99 against USD 4.99. The full write-up is generated as study_report.md next to study.html in the study folder.

The 1,000-person run: what 1,008 simulated buyers said

Offer: 7-day free trial without a card, then USD 4.99 a month, shown to young professionals, parents and students in India, the Philippines and Kenya.

What it concluded: iterate (medium confidence). The signals differ: the survey alone points to no-go (n = 1,001), the feed test to iterate (best creative fb_parents, expected CTR 1.58%), and all five simulated analysts to iterate. The decision written at the end of the run, before the analyst panel was added, was no-go. The idea interests people (three in four said maybe), but trust blocks them. The report also caught a concrete flaw: the ad promises "no card", while the landing page form asks for a card number, expiry and CVV, and simulated people dropped off at that step. The next step it recommends is to remove the card step, add proof from real users in each country, and retest. These are simulated people; treat every rate as a direction until a real experiment confirms it.

Preparation, active simulation turns, surveys, email/feed reactions, pitches, and reports can all use model calls. Repeated seeds multiply work. Local gateways report upstream usage when available and label estimates; subscription use does not imply a measured monetary cost. Measure a small run before choosing a large cohort. First-time embedding setup may download model assets even when inference runs locally.

Measured runs

These are local Fitloop measurements, not speed guarantees. Model, hardware, activity settings, concurrency, and provider limits affect runtime. Every rate in this section is simulated.

The 1,000-person run's active time breaks down as feed test 10m 17s (434 calls, 1,296,106 input and 375,768 output tokens), four social rounds 18m 28s (1,159 actions), survey and retest 20m 29s, report 1m 26s; the analyst panel failed during that run (all five analysts; fixed afterwards) and was run again later. Its wall-clock time was much longer: the Claude Code session limit paused it for 4h 12m mid-survey, it was resumed by hand the next morning, and the four social rounds were run again, so the active times above count only the final pass. API providers apply their own rate limits and quotas.

Preparing the people is measured separately, through the three login gateways. "Writing the people" is the persona planner alone (personas, interviews and follow-ups); "upload to ready" adds the knowledge graph, agent profiles and simulation config. At full depth the decision card comes from the follow-up call, so that column is also the number followed up.

The 60- and 3,000-person runs used Sonnet, gpt-6-luna and gemini-3.8-flash-low. The 150-person run used Sonnet, Codex's default model and gemini-3.8-flash-medium; its 24 interviews are 4 per audience. It predates the even per-audience split (each audience was split 20 + 5 between two providers, hence 45 / 55 / 50); current runs split every audience evenly across all providers.

The 3,000-person times are not a clean single pass. At 14:34, after 1,865 of 3,000 people, the backend was restarted to apply a lane fix (hung calls had cut the Gemini lane from 10 to 2; now only a rate limit halves a lane). The new prepare task replayed 1,043 finished answers from the population cache and wrote the rest; that second part alone took 1h 54m 39s. After the people were written, the 3,011 agent profiles took about 7.5 minutes and the simulation config about 9.5 minutes.

Quick start

Requires Git, Bash, Python 3, and uv. The installer provisions the Python 3.12 environment. Use Linux, macOS, or WSL; native Windows has not been validated.

git clone https://github.com/DarkWorldCoder/market-mirror.gitcd market-mirrorbash install.sh./mm configure

Choose your model provider, then start the backend and create your first scenario:

./mm provider check./mm start./mm cli quickstart --out scenarios/acme

The wizard asks about your product, buyers, channels, budget, and test size. It writes editable inputs, prepares the simulated people, and stops for review before running the remaining tests. Preparation itself uses model calls. Start with a small cohort. provider check discovers models without running inference; it does not test model quality or tool support.

Inspect the generated files and profiles. To continue, retain the returned simulation_id, set "approve_spend": true in scenarios/acme/market_test.json, and run:

./mm cli market-test scenarios/acme/market_test.json./mm live --run-dir mirofish_runs/acme

The live viewer runs at 127.0.0.1:5050, and its control room at 127.0.0.1:5050/live shows every stage, every simulated person lighting up as they act, what they post, and the progress log, updated every two seconds. Use the actual run directory printed by the pipeline if its name differs. The saved dashboard.html also opens directly without a server. To generate templates without preparing people, use ./mm cli quickstart --no-run.

Test your product URL

Install the optional browser support, then use a prepared simulation's ID:

uv sync --project backend --extra browser --python 3.12backend/.venv/bin/python -m playwright install chromium./mm cli website-test --simulation "$SIMULATION_ID" \  --url https://your-product.example/products/shoes --goal add_to_cart \  --task "Evaluate these shoes and decide whether to add a suitable pair to your cart." \  --limit 3 --steps 12

Restart the backend after installing the browser extra. Replace the URL with your site. Browser control supports search and keyboard actions, product options, hover menus, same-site tabs and frames, open shadow DOM, and bounded recovery when the page changes. Add --record-video for a recording or --headed to watch on a desktop with a graphical session. Agents may interact with the actual cart; signup submission requires explicitly supplied test data and opt-in. No orders or payments are supported. Named DOM checks verify outcomes independently of what an agent claims. Without them, completion stays unverified. See real website testing for outcome checks, signup setup, browser limits, and the evidence report.

Browser runs use compact model observations while retaining full local evidence. Set call, input-token, and elapsed-time limits; repeated actions on unchanged pages are detected separately from buyer departures. Reports show available cache usage, model time, and cost basis. See browser context and run limits.

Choose your model

A login gateway uses the subscription you already have, with its usage limits. API providers bill usage separately and apply their own rate limits and quotas. Model choice, gateway settings, usage-limit pauses, prompt caching with a Claude API key, the settings page and API costs for 3,000 people are in providers, mixed markets and large runs.

The default knowledge graph uses local SQLite and local embeddings; no Zep account is required. Model downloads and public-source research require network access. Hosted providers and CLI gateways receive model prompts through the selected provider. Model usage remains subject to that account's limits and charges.

Several models in one market

One market can be played by several providers at once, for example Claude, Codex and Gemini. Each provider writes an equal share of every audience, interviews its own people, plays them in the feeds and social rounds, and answers for them in the survey and pitch, so one model speaks for a person from start to finish. The dashboard then asks "Do the models agree?": it splits the results by provider and checks whether their would-convert ranges overlap and whether they name the same top objection and best message. Agreement is a robustness check on the simulation, not evidence about real buyers.

LLM_POOL=claude_code:sonnet,codex:gpt-6-luna,antigravity:gemini-3.8-flash-lowLLM_POOL_STRICT=true          # rounds and tests stay on each person's own provider

Each provider gets its own lane of calls in flight, so a slow one never holds up a fast one, and a provider whose account runs out can move to an API key or be stood in for by another provider mid-run. The full setup (gateways on separate ports, tokens, lanes, depth settings for thousands of people) is in providers, mixed markets and large runs.

Connect your agent

Use MarketMirror from Codex, Claude Code, Cursor, Gemini, or another client supporting its MCP transport. Install and configure the engine first using the quick start above.

Codex plugin

From the repository root:

codex plugin marketplace add "$PWD"codex plugin add market-mirror@market-mirror-local

Claude Code plugin

claude plugin marketplace add "$PWD"claude plugin install market-mirror@market-mirror

The plugin bundles the main workflow plus focused research, planning, testing, and evidence-review Agent Skills. They share one canonical source. Client plugin support and configuration locations vary; see the plugin guide.

Gemini CLI extension

gemini extensions install https://github.com/DarkWorldCoder/market-mirror

The extension adds the MarketMirror MCP server and a short GEMINI.md guide. Install the engine with the quick start above, or ask Gemini to run setup.

Any compatible MCP client

The quickest way is the PyPI package (needs uv); it is also listed in the official MCP Registry as io.github.DarkWorldCoder/market-mirror:

{ "mcpServers": { "market-mirror": { "command": "uvx", "args": ["marketmirror"] } } }

Then ask your agent to run doctor, and setup if the engine is not installed yet. To use a checkout you already have instead, print configuration for your client without overwriting its settings:

./mm agent-config --client generic# Also supports: codex, claude, cursor, gemini

The output contains an absolute server path and engine location. Copy the entry into your client's MCP configuration and restart the client. The stdio server can also be launched with ./mm mcp.

For authenticated loopback HTTP MCP:

python3 plugin/skills/market-mirror/scripts/mcp_server.py \  --http --port 5061 --token-file /absolute/path/to/private-token

Create a private token file containing a random bearer token of at least 24 characters. Connect to http://127.0.0.1:5061/mcp using that token. This transport is intended for local agents, not a hosted remote service.

Try this in your agent:

Use MarketMirror to analyze our product and campaign performance. Bring in ad and analytics data from tools you have authorized access to, or use the exports I provide. Research cited customer feedback, survey a small simulated audience, and compare two ads or offers. Test our product URL with synthetic visitors, show the evidence and missing inputs, and recommend the next real experiment.

Core tools: doctor, provider_setup, understand, ads_import, ideas, website_test, research, actuals_import, campaign_plan, run_test, study, job_status, holdout_backtest, predict, and results. Long jobs return status, logs, and result paths. Poll job_status before treating a job as complete.

Example workflow

flowchart LR    A[Product brief] --> B[Product profile]    C[Cited public feedback] --> D[Campaign plan]    J[Connected ad data or exports] --> D    B --> D    D --> E[Surveys, campaign tests and website journeys]    E --> F[Compare scenarios]    F --> G[Next real experiment]    G --> H[Import observed results]    H --> I[Backtest and calibration]    I --> D

After quickstart creates scenarios/acme/, replace its example content with your product material:

./mm cli understand --docs scenarios/acme/brief.md --name Acme \  --out scenarios/acme/product_profile.json
./mm cli research --query "home workout app" --country in \  --out scenarios/acme/research
./mm cli campaign-plan --profile scenarios/acme/product_profile.json \  --research scenarios/acme/research/voices.json \  --goal "trial signup" --budget 500 --currency USD \  --channels search organic paid_social email sales referral \  --out scenarios/acme/campaign_plan.json

The plan contains test_specs, cited evidence, assumptions, and unknowns. Channel budgets start as equal draft allocations. Review the claims and allocations, save a selected spec as experiment.json, and test it on a prepared simulation:

# Set this to the ID returned by your preparation step.SIMULATION_ID=sim_replace_me./mm cli test --simulation "$SIMULATION_ID" --spec @experiment.json./mm cli study --spec study.json

experiment.json and study.json are your reviewed input files; input examples and ./mm cli study --help describe their contracts. Study cells reuse completed work; rerun the same specification to resume. Each independent comparison should begin from the same initial state and matched scenario seeds.

Import actual outcomes when available. This example expects an export with Day, Country, Views, and Clicks columns:

./mm cli actuals-import exports/campaign.csv --source-type ads \  --map date=Day market=Country impressions=Views clicks=Clicks \  --out scenarios/acme/actuals.json
./mm cli holdout-backtest --pairs experiments_with_train_and_holdout.json \  --out scenarios/acme/holdout_backtest.json

The importer retains source, date, market, and quality labels and returns row-level validation errors. Backtests require explicitly paired simulated and real outcomes with declared training/holdout splits; the imported export alone is not a ready-made holdout dataset.

./mm cli profiles --simulation "$SIMULATION_ID" --brief./mm cli feedtest --simulation "$SIMULATION_ID" --creatives @creatives.json --seeds 3./mm cli survey --simulation "$SIMULATION_ID" --offer "Acme trial" \  --goal "start a trial" --messages @messages.txt --split --pricing USD./mm cli emailtest --simulation "$SIMULATION_ID" --emails @emails.json./mm cli pitch --simulation "$SIMULATION_ID" --script @pitch.md --rebuttals @rebuttals.md./mm cli report --simulation "$SIMULATION_ID" --run-dir mirofish_runs/acme

What it adds to OASIS and MiroFish

MarketMirror is built on MiroFish, which runs on OASIS. OASIS gives a realistic social platform (feeds, posts, follows and a recommendation system) where language-model agents act. MiroFish adds a knowledge graph and a prediction report on top. MarketMirror turns them into a market test that ends in a decision:

MarketMirror adds audience planning, marketing experiments, and decision reports to that foundation:

Evidence and simulation limits

• Generated interviews remain synthetic. Detailed biographies and BDE profiles do not turn invented people into customer evidence.
• Behavior controls are assumptions. Attention, fatigue, social proof, and landing friction include hand-set priors that need validation for the intended market.
• Seed variation measures simulation variation. It is not a predictive confidence interval. Repeated agreement and synthetic test–retest consistency do not establish agreement with humans.
• Backtests answer specific questions. The existing no-persona comparator is the mean real outcome in the training set. Beating it alone does not establish general predictive reliability or replace a matched generic-reader LLM comparison.
• Simulated feelings are not emotions. People report how each ad, page, email and pitch made them feel, and their mood fades over simulated time; by default this only observes. Letting feelings steer behaviour (--emotions on) uses assumed effect sizes until the bench gate passes (emotion research). Every run carries an A-D evidence grade, and stated yeses are shown next to what is left after fixed say-do rules.
• Calibration depends on coverage and assumptions. Uncalibrated predictions omit intervals and success probabilities. Validate absolute rates, rankings, and subgroup findings separately on untouched real experiments.

bench scores the simulated answers against open human data next to simpler comparators: real Upworthy headline tests, and real people's buy-at-this-price answers from Twin-2K-500 (MarketMirror-Bench). No results are published yet.

Read the human-behavior research guide for the papers, inspected code gaps, and proposed memory/state architecture. It distinguishes implemented controls from future work and experimentally supported results.

Frequently asked questions

Are these real buyers or people I can contact?

They are AI-generated characters inside the simulation. Their names, stories, responses, and lead scores describe those characters. They are not a contact list of real prospects.

Will MarketMirror run my ads or send emails?

It simulates ads, inbox reactions, and sales conversations. It does not publish ads, send outreach, or change your ad account.

Can buyers use my actual website?

Yes, with optional browser support. Synthetic visitors can inspect real pages and attempt tasks such as finding a product or adding it to a cart. Reports include screenshots and action records. Explicit page checks are needed to verify task completion. Orders and payments are not supported; see website testing for supported actions and signup requirements.

Do I need to write code?

You can request tests in plain language through a connected AI assistant. Installing MarketMirror, choosing a model, and connecting that assistant require technical setup. The command-line tools are also available for direct use.

Is it free?

MarketMirror's source code is available under AGPL-3.0. Running it may consume paid AI usage, subscription allowances, or local computing resources. Audience size, interview depth, tests, and repeats affect the work required. Measured runs give examples, not cost or speed guarantees.

Can I bring real research and campaign data?

Yes. You can supply product documents, linked feedback, and campaign exports. intake turns your own call transcripts, reviews, NPS verbatims and CRM notes into grounded personas that quote your customers word for word. Contact details are removed on your machine first (formats). MarketMirror can also collect supported public feedback with source links. Comparing simulations with actual outcomes requires suitable paired data; importing an ad export alone does not create a complete validation study.

What do the technical terms mean?

Other integrations

The Docker services mount uploads, scenarios, and run outputs from the host. The host's loopback login gateway is not directly reachable from those containers; use a provider reachable from the container or run the CLI gateway workflow on the host.

Development

cd backenduv sync --python 3.12uv run --no-sync python -m pytest tests claude_cli/tests -q

Tests mock model calls and do not need a live model key. CI also checks generated API documentation. Backend services live in backend/app/, the CLI and report renderer in backend/claude_cli/, agent tools in plugin/, and the Python SDK in sdk/.

Documentation

Support the project

If MarketMirror was useful, ⭐ star the repo so other people find it, and tell us what you tested. Every issue gets an answer.

Credits and license

MarketMirror builds on MiroFish and OASIS, adding audience planning, marketing tests, and decision reports to their simulation foundation. It is released under AGPL-3.0.

The dashboard embeds Apache ECharts; see third-party notices. The original MiroFish README is preserved. The banner and workflow illustrations were AI-generated; their generation prompts are included.