Say you’re launching an app next Friday. You’ve got five friends who agreed to test it, and all five will tell you it looks great. That’s useless data. Everybody who has shipped something knows this, and almost nobody has a fix for it.
MiroFish is an open source repo that goes after a version of this problem. You give it real material, like a news article or a product announcement, and it builds a fake social world out of it. Thousands of AI agents live in that world, each with its own personality, memory and way of reacting, and they argue with each other while you watch. The repo sits at 75.8k stars and 11.6k forks right now, which is a lot of attention for a prediction tool.
Quick disclosure before going further. I went through the README and the research behind its engine, and I did not run a full simulation myself. So this is a read of what the tool says it does and where I think it fits, not a review after weeks of use. When I’m guessing, I’ll say I’m guessing.
What MiroFish actually does
The README describes five steps. First you upload seed material and describe, in plain language, what you want predicted. The examples they give are a data analysis report or even a novel. Then the tool builds a knowledge graph from that material (they call it GraphRAG construction) and pulls out the people, groups and relationships inside it. Those become the characters. Next it writes a persona for each one and injects the agent settings, and the simulation runs on two platforms in parallel while the agents’ memories update as time passes. At the end a ReportAgent writes the prediction report, and you can chat with any agent in the simulated world, or with the report agent itself.
There’s also a “God’s-eye view” in the README. It means you can change something in the middle of a run, like a new rumor or a policy change, and watch how the crowd reacts. For launch testing this is the feature I care about most.
The simulation engine underneath is OASIS, built by the CAMEL-AI team. Its paper went on arXiv in November 2024, with authors from Shanghai AI Laboratory and several universities, and it simulates X-style and Reddit-style platforms with LLM agents. It claims to scale up to one million agents. According to CAMEL-AI’s own write-up, a recommendation system decides what each agent sees, the same way a real feed does, and not every agent is active at the same moment. That matters more than it sounds. Two agents with the same personality can react differently just because one of them saw a post and the other didn’t.
MiroFish also says it received support and incubation from Shanda Group. The README doesn’t name the two platforms it simulates, so I’m assuming they’re the X-like and Reddit-like ones from OASIS.
Where I got stuck: configuring the people
The thing I most wanted to know was whether I can set up different kinds of users on purpose. A skeptical developer here, a price-sensitive student there.
From the README, characters aren’t typed in by hand. They come out of your seed material. If your document mentions a student, a shop owner, a regulator and a journalist, the graph picks them up and the persona step turns them into agents. I spent a good while looking for a place in the README where you edit each persona yourself, and I couldn’t find one. It may be inside the frontend, and I can’t tell from reading. Check that before you plan a whole test around it.
Which is why the seed document matters more than any setting. Treat it as your configuration file. Write a paragraph on each group you care about: what they earn, what phone they use, what they already pay for, what annoys them about apps like yours. The more concrete the paragraph, the more specific the agents should be. If the document only says “users”, I’d expect generic users back.
There’s a lower level too. OASIS itself starts from an agent profile file, and its docs have a section on generating users, so if the MiroFish interface gives less control than you want, the engine underneath probably gives more. I haven’t tried that route.
How I’d use it for an app launch
Here’s a made-up example, so don’t read it as a case study. A small team in Pune is launching a budgeting app with a Rs 199 monthly plan. They put four things in the seed folder: the launch post, the pricing page text, a handful of reviews of two competitor apps, and a page describing their target groups. Then they ask one question in plain language. How will people react to the price in the first two weeks, and which complaint spreads fastest?
They run it once and read the report. Then they run it again with one change. In the first rerun a competitor makes their app free. In the second, a user posts about a sync bug and it starts getting shared. The same crowd reacts to different events, so the team can compare the runs side by side and see which groups move and which don’t.
And when the report says one group got angry, they can open a chat with one of the angry agents and ask why. I think this interview step is the most useful part, because with a normal survey you can’t go back to 400 anonymous respondents and ask a follow-up.
The README’s own examples aren’t about apps. One uses a public opinion report on Wuhan University, produced by another tool from the same author called BettaFish, and asks MiroFish to predict how the discussion would go. The other takes the first 80 chapters of Dream of the Red Chamber, hundreds of thousands of words, and simulates the lost ending. (Side note, since I got curious: many scholars think the last 40 chapters in the printed version were added by a later editor, Gao E, so a simulated ending is an odd but fun thing to compare against.) The README also lists financial prediction and political news examples as “coming soon”. They still say that today.
Beyond launches, the same setup should work for rehearsing a PR crisis, which the README pitches directly as testing public relations at zero risk. It should also work for checking how a policy draft lands with different groups, trying different wordings of a changelog, or guessing what questions will flood your support inbox after a price change. These are my extensions of the idea. The authors don’t promise them.
It isn’t a UI tester. The agents react to text on simulated social platforms, they don’t tap through your onboarding screens. If your question is whether people can find the checkout button, you still need real humans with a real phone. MiroFish is for what people say about the app, not how they use it.
Is it better than asking real people?
Short answer, it’s a good addition and a bad replacement. I’d say 70/30 in favour of using it, with a lot of conditions.
The good side is easy to list. It’s fast, you can rerun it with one thing changed, you get a wide spread of viewpoints without recruiting anybody, and you can ask follow-up questions. The OASIS paper also reports that bigger agent groups gave more diverse and more helpful opinions, so there’s some support for using more agents and not fewer.
The bad side is in the same paper. When the researchers compared their agents to human data, the agents followed the crowd more than humans did. That’s herd behavior. So a simulated crowd may settle on one opinion faster than a real crowd would, and a result like “everybody loved the price” or “everybody hated it” deserves suspicion. I’d care more about which specific complaints show up and less about the overall mood.
Then there’s the persona problem. An LLM’s idea of a price-sensitive student is probably a cliché of one, and real students surprise you. Anyone who says this is just a toy is wrong, I think. Anyone who says it replaces research is more wrong.
Actually, I’m being a bit unfair to surveys. Good researchers do call people back for follow-ups, it just takes weeks and money. The simulation gives you that loop in an afternoon. That’s the real advantage, and it’s a different thing from being accurate.
Setup, cost, and what I’d check first
I opened repo first and checked the folder list: backend, frontend, a Dockerfile, a docker-compose file, an .env.example. Normal stuff. You need Node.js 18 or newer, Python 3.11 or 3.12 (not newer, according to the README), and the uv package manager. Check your Python version first, it will take one minute only. I’d guess a lot of people on a fresh laptop with a newer Python will trip here, but that’s my guess and not something the README says.
Then you copy .env.example to .env and fill in two things. One is an LLM API. Any provider that works with the OpenAI SDK format is fine, and the README suggests Alibaba’s qwen-plus through the Bailian platform. The other is a Zep Cloud key, which handles agent memory, and the README says the free monthly quota is enough for simple use. After that, npm run setup:all installs everything and npm run dev starts it, with the frontend on port 3000 and the backend on 5001. There's a Docker route as well, docker compose up -d.
Cost is the real friction. The README itself warns that consumption is high and tells you to try fewer than 40 rounds first. I’d take that seriously. Every agent in every round is an LLM call, so more agents and more rounds multiply the bill. Start with a small crowd, one question and under 40 rounds, and scale up only after you’ve seen what the output looks like.
Two more things. The license is AGPL-3.0, so if you want to offer a product built on this to other people over a network, read what that requires first. I’m not a lawyer. And the repo shows 56 open issues and 69 open pull requests today, so it’s moving fast and not everything will be polished. I didn’t go through them, so I can’t say which ones would hit you during setup. (Near the bottom of the README there’s also a hiring note asking for resumes and a QQ group QR code. No idea how that affects the issue backlog.)
If I were starting tomorrow, I’d take a launch post I had already written and make two versions of the price line. Same seed material, same question, under 40 rounds each. Then I’d see which complaints show up in one version and not the other. After that I’d show both versions to three real people and compare. If the simulation and the people disagree, I’d believe the people.