MiroFish

MiroFish describes itself as a simple and universal swarm intelligence engine, and the honest way to read that is as a scenario generator rather than an oracle. You give it a news story or an event, it creates a crowd of agent personas with different roles, and it shows you the chain reactions that might follow. The project went public in November 2025 under AGPL-3.0 and by late September 2026 had passed 75,000 stars, which makes it one of the most popular open-source multi-agent projects and also a good illustration of why star counts and maturity are different things. The useful framing, and one that Chinese commentators reached quickly, is that MiroFish supplements stakeholders, second-order effects, and counter-intuitive paths instead of predicting the future.

Key Features

• Persona swarms: Many agents take on distinct roles, so the output reflects conflicting interests rather than one averaged opinion.
• Event-driven input: Hand it a news item or an event description and it generates the scenario space around it.
• Chain-reaction mapping: The value is in the second and third-order effects that a single analyst tends to skip.
• Python implementation: The engine is Python, which keeps it hackable for teams who want to modify the personas or the evaluation loop.
• Local-first forks: Community projects such as nikmcfly/MiroFish-Offline and tt-a1i/MiroFish-local replace the paid graph backend with Neo4j and Ollama, so you can run the whole thing on your own hardware.
• Multiple surfaces: Beyond the repository, there is a CLI fork and a hosted site at mirofish.ai.

Use Cases

Who Should Use This Tool?

• Analysts who already have a forecast: The engine is most useful as a stress test that surfaces objections and dependencies your first answer missed.
• Researchers evaluating multi-agent methods: The codebase is a concrete implementation of persona-based simulation to study or extend.
• Teams doing scenario planning: Model how different stakeholder groups might respond before committing to a plan.

Problems It Solves

1. Single-viewpoint analysis: One model, one answer. A swarm of roles surfaces the interests that a single narrative flattens.
2. Missing second-order effects: The interesting consequences of an event are rarely the first-order ones, and these are what the simulation is built to surface.
3. Expensive simulation tooling: Because it is open source and runs on local infrastructure for many forks, cost is not the barrier it is with enterprise simulation suites.

Pricing

The engine is free and open source under AGPL-3.0, and the repository's own hosted endpoint runs at mirofish.ai. The realistic cost is the tokens and compute the swarm consumes, which scales with the number of personas and the length of the simulation, plus whatever graph or vector store you attach. Community forks that swap in Neo4j and Ollama exist specifically to keep that bill low, and the AGPL license matters if you plan to run a modified version as a network service.

Advantages & Unique Selling Points

Compared to Competitors:

1. Swarm rather than single-shot: Asking 30 personas is a different operation from asking one model 30 times, and the disagreements are the product.
2. Hackable substrate: Python plus a documented fork ecosystem beats a closed simulation product when your method is the thing you are testing.
3. Offline path: The offline and local forks mean the workflow does not depend on a third-party graph service.

What Makes It Stand Out:

• The framing as a scenario generator rather than a prediction engine is accurate and useful.
• The active fork ecosystem shows the community is adapting it to constrained environments.
• AGPL-3.0 is a real constraint, but it also signals that improvements stay open.

User Reviews

The most useful review of MiroFish came from a Chinese tech commentator who argued it should be defined as a scenario generator rather than a prediction tool, and that its output quality depends entirely on role design, initial information, and evaluation method. That matches the codebase: the engine is a framework, and the rigour is yours to supply. The second common reaction is scale scepticism. A swarm produces plausible narratives easily and ground truth rarely, so teams that use it for planning should treat the output as a hypothesis list to investigate, not a result to report.

Getting Started

Quick Start Guide

1. Read the repository first: The README and the offline fork documentation tell you which components are paid and which are replaceable.
2. Pick your deployment: Use the hosted endpoint to try it, or start from a local fork if your data cannot leave your network.
3. Define the cast deliberately: Write personas with conflicting interests and specific information access, not ten copies of a generic analyst.
4. Run a small simulation: Start with a handful of personas on a familiar event so you can calibrate your own judgement about the output.
5. Review, then investigate: Convert the generated scenarios into a checklist of things to verify, then verify them.

Integration

• Neo4j and other graph stores, per the offline fork's architecture.
• Ollama and local model runtimes for the local variants.
• Your own evaluation scripts; the project publishes the engine, not a scoring authority.
• Agent frameworks, if you want personas to be executed by a different runtime.

Frequently Asked Questions

Does MiroFish predict the future?

No, and the project is better described as a scenario generator. It supplements stakeholders, second-order effects, and counter-intuitive paths, but the output quality depends on role design, input information, and how you evaluate it.

Is it free?

The engine is AGPL-3.0 and free to use. Your costs are the tokens and compute the simulation consumes, plus any paid backend components if you use the hosted configuration.

Can I run it entirely offline?

Community forks such as nikmcfly/MiroFish-Offline and tt-a1i/MiroFish-local replace the paid graph layer with Neo4j and Ollama, which is the usual route for private data.

Does the license matter if I use it internally?

AGPL-3.0 is relevant mainly if you offer a modified version as a network service. Internal use is the common case, but check with your legal team before shipping it as a product.

What is the biggest limitation?

Verification. Generating plausible scenarios is easy; establishing which ones are true requires work outside the tool.

Alternatives

If MiroFish is not the right fit, consider these alternatives:

• Jeff: A local decision model when you need one calibrated answer per option instead of a scenario swarm.
• Buzz: When the goal is collaboration with agents rather than simulation by agents.
• Dots: OpenAI's always-on agents for work that has a concrete deliverable.
• LangGraph: Better when you want to define an explicit agent graph with your own orchestration semantics.

Tips & Best Practices

1. Design conflict into the cast: Personas that agree with each other produce a summary; personas that disagree produce scenarios.
2. Fix the input, then vary roles: Change one variable at a time or you will not know what caused the output to shift.
3. Budget tokens before you scale personas: Cost grows with the swarm, and the first run is rarely the one you keep.
4. Treat output as hypotheses: Anything worth reporting from a simulation is worth verifying outside it.

Conclusion

MiroFish is a strong implementation of an idea that is easy to oversell: simulate many viewpoints and you will see consequences that a single analyst misses. Its popularity is real, its framing as a scenario generator is honest, and its fork ecosystem makes it usable in environments where data cannot leave the building. Bring your own evaluation method, plan to verify the interesting scenarios, and it earns its place in a planning workflow.