Free file · from the reel

Test your business idea before you spend a cent

A guide to MiroFish: an open-source tool that builds a whole society of AI personas who debate your idea and give you a report before you launch.

① What is it?

82K+stars on GitHub
Freeopen source
Hundredsof AI personas

You give it your idea, a news story or an ad, and it builds a "small world" of hundreds of personas, each with its own age, opinions and memory. They debate your idea on platforms like X and Reddit: some like it, some attack it, some spread the word. At the end a "report agent" writes you a full report.

The tool on GitHub ↗ See the demo ↗

② How does it work?

  1. Upload the material: a description of your idea, a news story, an ad or a file, and write your question in plain words.
  2. It builds a map: it pulls out the people, organisations and relationships from the material.
  3. It creates the personas: each with a background, a way of thinking and a memory.
  4. The simulation: they debate, post and reply to each other on two platforms at once.
  5. The report: who agreed, who objected, the strongest objection, and how the conversation spread. Afterwards you can ask any persona: why did you say no?

③ Install

The easy way: let Claude Code install it for you

Open Claude Code and paste this:

Install MiroFish from https://github.com/666ghj/MiroFish and run it on my computer. Follow the README steps, set up the config file and ask me for any keys it needs, then open http://localhost:3000 for me.

Or yourself from the terminal

You need: Node.js 18+, Python 3.11 or 3.12, and uv.

Install commands
git clone https://github.com/666ghj/MiroFish.git
cd MiroFish
cp .env.example .env
npm run setup:all
npm run dev

The keys (in the .env file)

Two keys: one for any OpenAI-compatible model, and one from Zep for memory (it has a free monthly tier).

Example .env file
LLM_API_KEY=your-llm-key
LLM_BASE_URL=https://api.openai.com/v1
LLM_MODEL_NAME=gpt-4o-mini
ZEP_API_KEY=your-zep-key
Free Zep key ↗

Then open http://localhost:3000 in your browser.

④ Test your idea: ready examples

The clearer your question (who your audience is, where, and at what price), the more accurate the report. Copy an example and adapt it:

I want to open a specialty coffee shop in a residential neighbourhood in Riyadh, at 18 riyals a cup. How will the residents react? Who would buy, who would object, and why?
I run an online abaya store and want to raise prices by 20%. How will my current customers react on social media?
I want to launch a $299 online course on marketing with AI. What is the objection most likely to kill sales?
Here is my new ad (paste the text). How will X users react to it? Which line will draw attacks?
💡 Start small: keep your first test under 40 simulation rounds. The tool uses a lot of your model key, and a small test gives you a feel for it at low cost.

⑤ Before you rely on it

⚖️ A rehearsal, not a crystal ball: the tool shows you likely reactions and the strongest objections, not a guaranteed success rate. Use it to catch mistakes early, then test with real customers before you spend.
💳 Cost: the tool itself is free, but every simulation uses credit from your AI key.
📄 License: AGPL-3.0. Using it for yourself is fine, but if you build a service on it that you sell to people, you must publish your code.

📚 We have more than 20 other free guides

More free guides? Tap here ↗
✦ Nadr Community

Want to learn more?

In Nadr Community we teach Claude, content creation and ads step by step, across 5 tracks we keep improving (lessons are in Arabic):

Mastering ClaudeDesign with AIMaking ads and videosMarketing with AIAutomation and a customer-service agent
Join Nadr Community →skool.com/nadrai
✓ Copied