Simulate anything, for $1 & less than 10 min — Universal Swarm Intelligence Engine
Drop in anything — a press release, a news headline, a policy draft, a question you can't answer, a historical what-if — and MiroShark spawns hundreds of agents that react to it hour by hour. Posting, arguing, trading, changing their minds.
- You bring a scenario. MiroShark builds the world around it.
- Hundreds of grounded agents. Twitter, Reddit, and a prediction market. Hour by hour.
- Chat with any of them. Drop breaking news mid-run. Fork the timeline.
- Get a report on what happened, citing actual posts and trades.
The recommended path: one OpenRouter key + the ./miroshark launcher. First simulation in ~10 min, ~$1 (Cheap preset) to ~$3.50 (Best preset).
Prereqs — Python 3.11+, Node 18+, Neo4j, and an OpenRouter key.
Install Neo4j — the launcher starts it for you:
- macOS —
brew install neo4j - Linux —
sudo apt install neo4j(or your distro's equivalent) - Windows — install Neo4j Desktop (native, GUI — start the DB there, then run the launcher from WSL2 or Git Bash), or run the whole stack inside WSL2 and follow the Linux steps
- Zero-install — create a free Neo4j Aura cloud instance and point
NEO4J_URI/NEO4J_PASSWORDat it in.env
Then:
git clone https://github.com/aaronjmars/MiroShark.git && cd MiroShark
cp .env.example .env
# Open .env and paste your OpenRouter key into the Best or Cheap preset block
./mirosharkThe launcher checks dependencies, starts Neo4j, installs frontend + backend, and serves :3000 + :5001. Ctrl+C stops everything. Open http://localhost:3000 and drop in a document.
Other paths — one-click Railway / Render deploy, Docker + Ollama, manual Ollama, Claude Code CLI — all in docs/INSTALL.md.
| Feature | What it does |
|---|---|
| Smart Setup | Drop in a doc → three auto-generated Bull / Bear / Neutral scenarios in ~2s |
| What's Trending | Pick a live news item from RSS feeds; pre-fills the scenario in one click |
| Just Ask | Type a question with no document — MiroShark researches and writes the seed briefing |
| Counterfactual Branching | Fork a running simulation with an injected event ("what if the CEO resigns in round 24?") |
| Director Mode | Inject breaking news into the current timeline without forking |
| Preset Templates | 6 benchmarked scenarios: crypto launch, corporate crisis, political debate, product announcement, campus controversy, historical what-if |
| Live Oracle Data | Opt-in grounded seeds from the FeedOracle MCP (484 tools) |
| Per-Agent MCP Tools | Personas can invoke real MCP tools (web search, APIs) during simulation |
| Embed & Publish | Public/private toggle + embed URLs for sharing finished runs |
| Social Share Card | 1200×630 PNG that auto-unfurls scenario, status, quality, and belief split on Twitter/X, Discord, Slack, LinkedIn |
| Public Gallery | /explore browses every published simulation as a card grid — preview the share card, consensus split, and quality health; click to open or one-click fork |
| Article Generation | Substack-style write-up of what happened, grounded in actual posts and trades |
| Interaction Network | Force-directed agent-to-agent graph with echo-chamber metrics |
| Demographics | Archetype clustering (analyst / influencer / retail / observer…) |
| Quality Diagnostics | Health score per run — engagement, coherence, diversity, variance |
| History Database | Search, clone, export, or delete any past simulation |
| Trace Interview | See the full reasoning chain behind an agent's reply, not just the reply |
| Push Notifications | Web-push alerts when long-running graph / sim / report jobs finish |
Each feature is documented in docs/FEATURES.md.
- PR crisis testing — simulate public reaction to a press release before publishing
- Market reaction — feed financial news and observe simulated trader + investor sentiment
- Advertisement — test a campaign, headline, or pitch against a simulated audience before spending
- Policy analysis — test draft regulations against a simulated public
- Life decision — frame a personal decision (job move, relocation, launch timing) as a scenario and watch diverse personas argue it out
- What-if history — rewrite a historical event and see how a population of personas re-narrates the aftermath
- Creative experiments — feed a novel with a lost ending; agents write a narratively consistent conclusion
 |  |
 |  |
 |  |
 |
 |
| Install | Every deployment path: cloud, Docker, Ollama, Claude Code |
| Configuration | Env vars, model routing, feature flags |
| Models | Cheap vs Best presets, local Ollama models, benchmark findings |
| Architecture | Simulation engine, memory pipeline, graph retrieval |
| Features | Deep dive on every feature in the table above |
| HTTP API | Every endpoint, grouped by concern |
| CLI | miroshark-cli reference |
| MCP | Claude Desktop integration + report agent tools |
| Observability | Debug panel, event stream, logging |
| Contributing | Tests and development |
AGPL-3.0. See LICENSE.
Support the project: 0xd7bc6a05a56655fb2052f742b012d1dfd66e1ba3