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.
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
# Paste your OpenRouter key into the LLM_API_KEY / SMART_API_KEY /
# NER_API_KEY / OPENAI_API_KEY / EMBEDDING_API_KEY slots (same key,
# 5 places). Default lineup is Mimo V2 Flash + Gemini 3 Flash.
./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.
After launching, click the 中 / EN toggle in the top-right of the navbar to switch between English and Chinese. Your choice is persisted in the browser, and the public gallery card titles + descriptions follow the active locale.
- 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
A few of the highlights:
| Feature | What it does |
|---|---|
| Smart Setup | Drop in a doc → three auto-generated Bull / Bear / Neutral scenarios in ~2s |
| 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 ("CEO resigns in round 24?") |
| Director Mode | Inject breaking news into the current timeline without forking |
| Per-Agent MCP Tools | Personas invoke real MCP tools (web search, APIs) during simulation |
| Article Generation | Substack-style write-up of what happened, grounded in actual posts and trades |
| Public Gallery & Verified Predictions | Browse and fork every published sim at /explore; track the calls that landed at /verified |
| Share everywhere | Social cards, replay GIFs, tweet threads, RSS / Atom, embeds, and Slack / Discord / Telegram / webhook notifications |
…and 40+ more — share surfaces, exports, integrations, observability, and on-chain citation. See the full feature list and deep dives in docs/FEATURES.md.
| Install | Every deployment path: cloud, Docker, Ollama, Claude Code |
| Configuration | Env vars, model routing, feature flags |
| Models | Cloud preset, 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 — plus interactive Swagger UI at /api/docs and a spec at /api/openapi.yaml |
| CLI | miroshark-cli reference |
| MCP | Claude Desktop / Cursor / Windsurf / Continue integration + report agent tools (auto-generated snippets in Settings → AI Integration) |
| Webhooks | Completion webhook payload, headers, delivery semantics, Slack/Discord/Zapier/n8n recipes |
| DKG citation | OriginTrail DKG anchoring — UAL + Merkle root + on-chain citation key for any finished sim |
| WaybackClaw archive | WaybackClaw submission — snapshot id + IPFS CID + Nostr event id for any finished sim |
| Observability | Debug panel, event stream, logging |
| Ecosystem | Projects, agents, and products built on top of MiroShark |
| Contributing | Tests and development |
AGPL-3.0. See LICENSE.
Support the project: 0xd7bc6a05a56655fb2052f742b012d1dfd66e1ba3