<div align="center"> <img src="docs/images/marketmirror-loop.svg" width="100%" alt="MarketMirror: rehearse your launch on simulated buyers before you spend a cent. In one loop, a Fitloop ad is tested on six simulated buyers in Pune, Nairobi, Manila, Austin, Taipei and Milan. They stop, scroll past, click, save or hide it, two of them argue about the free trial, the survey shows 31% yes, 46% maybe and 23% no, and the verdict is iterate: say no card needed in line one. Illustration with simulated numbers." />

MarketMirror: AI Market Research & Marketing Simulation

Try your ads, prices, and sales pitch with simulated buyers before spending on a real campaign.

English · 简体中文

Open source and built for AI agents. Interviewed LLM buyer personas scroll simulated ad feeds, argue in an OASIS social simulation, answer a survey and hear your sales pitch. Ask in plain words ("test these three ads on young parents in India") from Claude Code, Codex, Gemini CLI, Cursor or any MCP client, and get a go / iterate / no-go report in one offline HTML dashboard. Self-hosted: only the model calls (to the provider you choose) and optional public research leave your computer.

Built on MiroFish and CAMEL-AI's OASIS · listed in the official MCP Registry as io.github.DarkWorldCoder/market-mirror

Open the live demo: the full dashboard from a 2,999-buyer simulated run, in your browser, no install. (Fitloop is an invented app; every number is simulated.)

</div>

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

git clone https://github.com/DarkWorldCoder/market-mirror.git && cd market-mirror
bash 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.

<div align="center">

<a href="https://cdn.jsdelivr.net/gh/DarkWorldCoder/market-mirror@main/docs/video/marketmirror-launch.mp4"><img src="docs/images/launch-video-poster.png" alt="Play the 60-second MarketMirror launch film" width="80%" /></a>

_{▶ <a href="https://cdn.jsdelivr.net/gh/DarkWorldCoder/market-mirror@main/docs/video/marketmirror-launch.mp4">Watch the 60-second launch film</a> (with captions) · <a href="https://cdn.jsdelivr.net/gh/DarkWorldCoder/market-mirror@main/docs/video/marketmirror-launch-vertical.mp4">vertical 9:16 cut</a> · made with HyperFrames from <a href="launch-video/">launch-video/</a>}

Meet the buyers · What you can test · Screenshots · How it works · Example results · Evidence and limits · Get started · Documentation

</div>

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?

| If you are… | Use MarketMirror to… | |---|---| | A founder or small business owner | Explore how different people might understand your product, price, or launch offer. | | A marketer or agency | Compare ads, headlines, emails, and audiences before choosing a live test. | | A sales team | Practice a pitch, discover likely concerns, and try clearer answers. | | A product or research team | Explore buying decisions and website journeys, then plan customer research. | | A developer or AI agent builder | Run the same workflows through commands, an API, a Python library, or connected AI assistants. |

Meet the simulated buyers

<img src="docs/images/marketmirror-buyers.svg" width="100%" alt="Meet the simulated buyers: Yash Malhotra, 42, an app-cab owner-driver in Pune and one simulated person from the 3,000-person run, answers his life interview (Realme 9 Pro on Jio prepaid at 349 rupees, lost 6,000 rupees to a crypto course, asks his wife, his mother and a stall partner before buying). His persona fills in, then his decision card: says yes to a free trial, cheap price, family plan and a Hindi coach; walks away from a card needed upfront, hidden charges and over-promising ads; trusts 4+ star reviews, clear prices and family opinion; says he would exercise in waiting time but long shifts make it unlikely. The stereotype guard checks that no two people in an audience share a job and a city, and the next buyers appear." />

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.

| What a buyer can have | Why it matters in a test | |---|---| | A background | Age, location, work, and life stage provide context for their response. | | A budget and priorities | An offer may interest them but still compete with more urgent expenses. | | A phone and internet connection | A heavy page or video may be inconvenient on their device or data plan. | | People they consult | A partner, family member, or community may influence a purchase. | | Trust concerns | Hidden fees, unclear claims, or a previous bad experience may make them hesitate. | | A buying decision card | A summary records what could persuade them, what could stop them, and who else matters. |

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.

<a id="key-features"></a>

What you can test

<img src="docs/images/marketmirror-tests.svg" width="100%" alt="What you can test, ticked off one by one along a path: ads in simulated Facebook, Instagram, Reddit, TikTok, LinkedIn or X feeds; headlines and messages; price and offer; the conversation around a launch; emails in simulated inboxes, with none sent; a sales pitch; your real website; which audience to study first; the next test to run; and simulated versus real results. Repeat a comparison or swap providers to see how much a result moves." />

| Your question | What MarketMirror does | What you can learn from the simulation | |---|---|---| | Which ad gets attention? | Places your ads among ordinary posts in simulated Facebook, Instagram, Reddit, TikTok, LinkedIn, or X feeds. | Which ads buyers stop at, ignore, click, comment on, or hide. | | Which headline or message is clearer? | Shows different versions to different buyers and asks for their reactions. | Which wording draws interest and which creates confusion. | | Does the price or offer feel right? | Asks price questions and compares offers or pricing tiers. | Where price becomes a concern and which terms need explaining. | | What might happen around a launch? | Lets buyers post, reply, and react in a simulated social conversation with scheduled brand posts and events. | Questions, objections, and themes that emerge in the discussion. | | Will an email interest them? | Tests subject lines, email content, or a sequence in simulated inboxes. | Generated opening, reading, and response choices. No emails are sent. | | How does our sales pitch land? | Presents the pitch, collects concerns, tries your answers, and asks again. | Which concerns persist and whether your response helps or makes things worse. | | Where does our website lose people? | Sends simulated visitors through a real website and records their actions. | Where they hesitate, leave, or complete a checked task such as adding to cart. | | Which audience should we investigate first? | Compares responses across the groups and countries you selected. | Differences worth following up with real customer research. | | What should we test next? | Uses the run and, when supplied, real campaign exports to suggest follow-up experiments. | A practical starting point for the next live test. | | Do the simulations match our results? | Compares paired simulated and observed outcomes. | How well the simulation held up on those experiments and where it needs adjustment. |

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

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 befo