🔴 Advanced ⚙️ Type: Multi-Agent Simulation Engine 💸 Free & Open Source (AGPL-3.0) ⭐ 67,000+ GitHub Stars
What is MiroFish?
MiroFish is an open-source AI prediction engine that acts as a digital sandbox for scenario simulation. Think of it as “SimCity meets AI forecasting.” Traditional prediction models treat the world like a math equation, but the real world is driven by messy social dynamics—opinions shift, coalitions form, and a single viral post can change history. MiroFish actually simulates this.
You feed MiroFish a “reality seed”—like a news report, a policy draft, or a financial earnings call—and tell it what you want to predict. Using GraphRAG (Graph-based Retrieval-Augmented Generation), it extracts entities to build a knowledge graph. It then spawns hundreds of autonomous AI agents, giving each a unique personality, bias, and memory. These agents are unleashed into a simulated dual-platform environment (think Twitter and Reddit) powered by the OASIS engine.
The agents debate, post, react, and influence each other over multiple rounds. Finally, an AI “ReportAgent” analyzes the emergent behavior of the swarm and generates a comprehensive prediction report, complete with confidence signals and turning points.
Who is it for?
- PR & Marketing Strategists who want to upload a crisis response or product launch memo and “stress-test” how the public might react before actually publishing it.
- Financial Analysts injecting market signals to watch how simulated retail and institutional investors react to each other’s moves.
- Policymakers & Executives testing downstream impacts by uploading a draft policy to see how different stakeholder groups form alliances or push back.
- AI Automation Researchers studying multi-agent orchestration, persistent memory, and how emergent behavior arises in LLM swarms.
What makes it special?
- Emergent Prediction — The output isn’t hardcoded. The prediction arises naturally from the collective intelligence and social contagion of hundreds of agents interacting, arguing, and persuading one another.
- “God’s-Eye” Deep Interaction — After the simulation ends, you aren’t just handed a PDF. You can literally open a chat window and interview any individual agent in the simulated world to ask them why they changed their opinion or posted a specific comment.
- Persistent Agent Memory — Agents aren’t amnesiacs. They retain long-term memory of previous simulation rounds, allowing them to hold grudges, build trust, and evolve their stances over time based on the knowledge graph.
- Offline Community Forks — While the official repository uses cloud LLM APIs, the community has built massive forks (like
MiroFish-Offline) that swap the backend to use Neo4j and local Ollama models for 100% private, on-device simulation.
Requirements before you start
MiroFish orchestrates massive amounts of LLM calls across a full-stack environment. You will need:
- Node.js 18+ — Required to run the Vue-based frontend UI.
- Python 3.11 or 3.12 — Required for the backend simulation engine.
- uv Package Manager — The modern, blazing-fast Python package installer.
- An LLM API Key — MiroFish supports any OpenAI-compatible API format. Because running hundreds of agents is token-heavy, the developers strongly recommend using highly cost-efficient models (like Alibaba’s Qwen-Plus or Anthropic’s Claude 3.5 Haiku) rather than GPT-4o.
Step-by-step installation
Deploying the official MiroFish stack locally requires spinning up both the frontend and backend simultaneously.
Step 1 — Clone and Configure
Open your terminal and clone the repository. Then, create your environment variables file:
git clone https://github.com/666ghj/MiroFish.git
cd MiroFish
cp .env.example .envOpen the .env file in a text editor and paste your chosen LLM API key and Base URL (e.g., LLM_API_KEY=your_key and LLM_BASE_URL=https://api.openai.com/v1).
Step 2 — Install All Dependencies
MiroFish includes a convenient unified setup script that uses NPM to install both the frontend JavaScript packages and the backend Python virtual environment (via uv) automatically:
npm run setup:allStep 3 — Start the Simulation Engine
Once everything is installed, start the local development servers:
npm run devThis will boot up the Python backend and the Vue frontend. Open your browser to the provided localhost URL. You can now upload your first document, define your prediction requirement, and watch the agents spawn into existence!
💡 Pro-Tip: Preventing Rate Limits on Agent Swarms
If you are running a swarm of multiple agents in MiroFish that need to interact with external APIs or scrape live web environments, your single host IP is going to get heavily rate-limited or blocked.
For large simulations, it is highly recommended to assign different IP addresses to different agent groups. We use Proxy-Seller to grab a batch of dedicated IPv4 proxies to keep our agents running smoothly without getting banned. You can use code GLOBALAI15 for 15% off your order.
Common errors and fixes
| Error | What it means | How to fix it |
|---|---|---|
| Massive API Bills / Token Limits Exceeded | Simulating 100 agents talking to each other for 40 rounds generates a staggering amount of LLM prompt tokens. | Do not use GPT-4o for your first run. Start with a smaller simulation (e.g., 10 agents, 5 rounds) to understand the system. Use cheap, fast models like Qwen 2.5, Claude 3 Haiku, or Llama 3 for the individual agent brains. |
uv command not found during installation | The npm run setup:all script is trying to install Python dependencies, but you do not have the uv package manager installed on your OS. | Install uv globally on your system first. On macOS/Linux run: curl -LsSf https://astral.sh/uv/install.sh | sh. On Windows run: powershell -c "irm https://astral.sh/uv/install.ps1 | iex". |
| Graph Generation Fails (Chinese UI defaults) | The original upstream MiroFish was built heavily for the Chinese market and may default to specific regional API prompts or UI text. | If you want a native English experience, abandon the main repo and clone the nikmcfly/MiroFish-Offline fork instead, which translates the entire UI to English and swaps cloud services for local Neo4j graphs. |
Free vs Paid comparison
| Feature | MiroFish (Open Source Swarm) | Traditional Human Focus Groups / Polling |
|---|---|---|
| Cost and Speed | 🟢 Near instant; costs only API tokens ($10-$20) | 🔴 Weeks of planning; costs thousands of dollars |
| Dynamic Scenario Testing | ✅ Inject variables mid-simulation to see changes | ❌ Static; requires running a completely new poll |
| Data Privacy | 🟢 100% Private (Especially with offline forks) | ⚠️ Requires sharing sensitive PR drafts with third parties |
| Real-World Accuracy | ⚠️ Excellent for directional sentiment, not exact statistics | 🟢 Better for strict demographic sampling |
Bottom line: MiroFish represents the next frontier of applied AI. We are moving past single-prompt chatbots into the era of Swarm Intelligence, where the most valuable insights come from watching AIs talk to each other. If you are a strategist, marketer, or developer, running a MiroFish simulation on a current event is one of the most eye-opening technical experiences available today.
Alternatives — 3 similar tools
1. CAMEL-AI (OASIS Engine)
If you are a hardcore developer who wants to build your own social simulation from scratch without the MiroFish UI, you can go straight to the source. The OASIS engine (built by the CAMEL-AI team) is the underlying multi-agent framework that powers MiroFish’s simulated Twitter/Reddit interactions. It supports up to one million agents and 23 different social actions.
2. Lean Swarm
A cost-focused, lightweight multi-agent prediction engine designed to approximate MiroFish-class narrative forecasting. Lean Swarm uses aggressive batching and strict LLM routing guardrails to simulate scenarios at a fraction of the token cost, making it ideal for continuous, budget-friendly testing.
3. AutoGen (by Microsoft)
The industry standard for multi-agent conversational frameworks. While MiroFish is heavily optimized specifically for social media simulation and forecasting, AutoGen is a generalized framework where you can code AIs to act as programmers, reviewers, and planners to solve complex mathematical or coding workflows together.
🔗 github.com/microsoft/autogen
🚀 Want more free AI tools like this?
We find, test, and write setup guides for the best free and open-source AI tools — so you don’t have to dig through GitHub yourself.Browse Free AI Tools at globalaiforce.com/shop →
📸 Follow us for daily AI tool tips and tutorials: instagram.com/globalaiforce