Article8 min readUpdated
MiroFish: Simulate How People React to Your Idea
MiroFish is an open-source engine that simulates how a crowd of AI agents reacts to an idea. See what it needs, what it returns and its limits.
By Tithi Mondal, UI/UX Designer
Suppose you run a tiffin service in Durgapur and you want to launch a monthly subscription app. You have a launch message, a price and a strong feeling. Before you pay for a single screen, you want to know how people will talk about the idea.
MiroFish is an open-source project that tries to answer this kind of question with simulation. In one plain sentence: MiroFish builds a small artificial society of AI agents from your material and reports how those agents react. The agents react on simulated social platforms.
Checked in November 2026. Tools change quickly, so confirm details on the project's own page.
What is MiroFish and what problem does it address?
MiroFish is a multi-agent simulation engine for prediction. A multi-agent simulation means many separate AI characters act in the same environment, each with a profile and a memory. The project's README calls MiroFish "A Simple and Universal Swarm Intelligence Engine, Predicting Anything". Swarm intelligence is the idea that a group shows patterns that no single member shows alone.
The problem is simple to state. If you ask one chatbot about your idea, you get one voice. A real launch meets a crowd. People in a crowd influence each other. One doubtful comment can change the mood of a whole thread. MiroFish tries to imitate that crowd effect instead of giving one opinion.
The README describes the intended use as a rehearsal space. It says the engine takes seed information such as breaking news, policy drafts or financial signals and builds a parallel digital world. Its stated examples are a public opinion simulation and a simulated ending for a classic Chinese novel. Startup validation is not the main example in the README. Using MiroFish to simulate audience reaction to a product idea is my own reading of where the tool could fit.
One practical note: many copies of popular repositories exist. The repository under the account 666ghj is listed by GitHub as an original repository, not a fork.
What do you feed MiroFish, and what comes out?
You give MiroFish 2 things and you get 2 things back. According to the project's documentation, the inputs are seed material and a prediction request written in normal language. The outputs are a prediction report and an interactive simulated world.
| Part | What the README says | A founder's version |
|---|---|---|
| Seed material | Documents such as a data analysis report or a story | A one-page note on the customer, the problem, the offer, the price and the launch post |
| Prediction request | A question in natural language | "How do office workers in a tier-2 city react to this launch post in the first week?" |
| Report | A prediction report written by a ReportAgent | A summary of which reactions and objections appeared |
| Simulated world | You can chat with any agent and with the ReportAgent | You question a doubtful agent about the price |
How does MiroFish work, step by step?
MiroFish works in 5 stages, and the README names each stage. I have added a plain explanation to each name.
- Graph building. MiroFish reads the seed material and builds a knowledge graph. A knowledge graph is a map of people, organisations and topics, and of how they connect.
- Environment setup. MiroFish extracts the entities and relationships, generates personas, and configures the agents.
- Simulation. The agents act on 2 simulated platforms in parallel. The README says the agents' memory is updated as simulated time passes.
- Report generation. A ReportAgent uses a set of tools to study the finished simulation and writes the report.
- Deep interaction. You can chat with any agent in the simulated world, and you can question the ReportAgent.
The README credits the simulation engine to OASIS, an open-source social simulation project from the CAMEL-AI community. So MiroFish is best understood as a layer on top of that engine. MiroFish adds the reading of your documents, the persona generation, the report and the chat.
What do you need to run MiroFish?
MiroFish is a developer tool that you run yourself, so you need a technical person and paid model access. According to the project's documentation, the setup needs the following.
- Node.js for the frontend and Python for the backend. The README lists the supported versions.
- uv, which is a Python package manager.
- An API key for a language model service that follows the OpenAI SDK format. An API key is a password that lets software use a paid service. The README recommends the Qwen-plus model through Alibaba's Bailian platform.
- An API key for Zep Cloud, a memory service. The README says the free monthly quota is enough for simple use. Check the current plans.
- Either a source install with npm commands or a Docker install. Docker is a way to run packaged software without installing every part by hand.
After the install, MiroFish runs on your own computer and you open it in a browser. The repository states the licence as AGPL-3.0. If you plan to build a commercial product on top of MiroFish, read that licence first with someone who understands it.
The README also gives a clear warning about cost. It says token consumption is high and suggests trying simulations with fewer than 40 rounds first. Tokens are the units of text that model services charge for. Many agents talking for many rounds means many tokens.
How could a founder use MiroFish to validate a startup idea with AI overnight?
A founder with a developer friend could run one small simulation in an evening and read the report the next morning. The aim is to stress-test the launch message, not to predict sales. Here is the order I would suggest.
- Write the seed document. Keep it to one page. Include who the customer is, the problem, the offer, the price, the exact launch post, 3 objections you already expect, and what people use today.
- Write one prediction request. For the tiffin example: "How do office workers and students in Durgapur react to this subscription post? Which objections spread?"
- Start small. Follow the README advice and keep the number of rounds low. A small run costs less and finishes sooner.
- Read the report for patterns. Note the objections that repeat, the words agents use for your product, and the questions about price, trust and delivery.
- Chat with 3 agents. Pick one supporter, one doubter and one agent who stayed silent. Ask each agent what would change their mind.
- Change one thing and run again. Change only the price or only the message. Then compare the 2 reports.
The result of this evening is a list of questions and weak spots. For example: "Agents asked many times whether they can pause the subscription during Durga Puja holidays." That line is not a fact about your market. That line is a good question to ask real customers.
Take the list into real conversations. My guide to user interview questions for app ideas shows how to ask without leading the person. A simple landing page that converts with a real enquiry form then tells you whether strangers act.
What are the limits and risks of swarm intelligence prediction?
The main limit is that a simulated reaction is text generated by language models, not a response from real customers. Treat every MiroFish result as a rehearsal. Here are the limits I would expect.
- Simulation is not evidence. If 40 agents like your idea, zero real people have agreed to pay.
- Made-up details. A language model can produce confident statements that are not true. An agent may describe an experience that no real person had.
- Your seed shapes the world. The personas are generated from your material. If the seed document is hopeful and one-sided, the simulated world may be hopeful and one-sided too.
- Bias in the model. Language models learn from text written online. I would expect weaker results for people who write less online. Examples are first-time internet users in small towns and users who prefer a regional language.
- Cost. The README itself warns that token consumption is high. Set a spending limit with your model provider before the first run.
- Privacy. The setup uses outside services for the language model and for memory. Assume your seed material is sent to those services. Do not upload customer names, phone numbers or confidential financial details.
- The word "predicting". The project's tagline is ambitious. I did not see accuracy measurements in the README, so I would not treat a report as a forecast.
What do real users and a designer still have to do?
Real people must still confirm the problem, and a designer must still turn confirmed problems into a product. A simulation cannot do either job.
Real users show you behaviour. A person who gives a WhatsApp number on your enquiry form has done something. A person who explains how they solved the lunch problem last month has given you a fact. My guide on user research for startups covers a small, affordable way to collect these facts.
A designer then makes decisions from that evidence. If real customers worry about pausing a subscription, the pause control belongs on the home screen, not inside settings. If trust in the kitchen is the doubt, the first screen should show the cook and the kitchen. I have designed food ordering and marketplace apps, and decisions like these came from real constraints, not from guesses. Evidence also keeps the first version small, which I explain in my guide to MVP design and what to build first.
Once real people have answered your questions, put the findings into a design brief. I am happy to help you turn that brief into screens through my UI/UX design service.
Sources
Frequently asked questions
Is MiroFish free to use?
The MiroFish code is open source under the AGPL-3.0 licence shown in its repository. Running it still uses paid language model access, and the README warns that token consumption is high.
Can MiroFish predict whether my startup will succeed?
No. MiroFish produces simulated reactions written by language models. The report helps you find objections and unclear points, and real customers must still confirm demand.
Do I need to know coding to run MiroFish?
You need someone comfortable with Node.js, Python or Docker and with API keys. A non-technical founder should ask a developer to set it up.
Is it safe to upload my business plan to MiroFish?
The setup uses outside services for the language model and for memory, so assume your material is sent to them. Remove customer names, phone numbers and confidential financial details first.
Working on something like this?
Tell Tithi what you are planning. You get a clear scope, a fixed price and a timeline before any work begins. I reply to every enquiry within 24 hours.