README.md
May 12, 2026 · View on GitHub
MiroShark
English
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.
What it does
- 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.
Quick start
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 + Grok-4.1 Fast.
./miroshark
The 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.
Interface language
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.
Features
| 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 |
| Shareable Scenario Links | Drop a ?scenario=...&url=... URL into a tweet or blog post — readers land on the New Sim form already pre-filled. ?template=<slug> auto-launches one of the preset templates. The un-run-scenario counterpart to "Fork this scenario" on /watch and /share |
| 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 |
| Custom Wonderwall Endpoint | Point the simulation loop at any OpenAI-compatible endpoint (self-hosted vLLM, Modal, fine-tunes…) without affecting Default/Smart/NER. Set WONDERWALL_BASE_URL + WONDERWALL_API_KEY |
| 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 |
| Animated Belief Replay | 1200×630 GIF — one frame per round, belief bars sliding to each round's distribution. Discord and Slack auto-play GIFs from the direct URL |
| Transcript Export | Per-round agent posts + stance labels as Markdown (YAML front matter for Notion / Obsidian / Substack) or structured JSON (for SDKs and LLM-as-judge pipelines) |
| Trajectory Export | One row per round as RFC 4180 CSV or JSONL — pandas.read_csv("…/trajectory.csv") lands ready for Pandas / Excel / Tableau / R / Observable. Same ±0.2 stance threshold as every other surface |
| Tweet Thread Export | GET /api/simulation/<id>/thread.txt — auto-formatted X / Twitter thread, intro tweet + one tweet per belief inflection point + close tweet (with watch + share URLs). Each tweet ≤280 chars; copy individual tweets or the whole thread. Pairs with the share card / replay GIF / transcript / trajectory / watch page as the sixth share format |
| Live Watch Page | /watch/<sim_id> — minimal full-viewport broadcast page with a vanilla-JS poller that refreshes the belief bar, round counter, and progress bar every 15 s while the simulation runs. Auto-unfurls as a 1200×630 image card when tweeted; the "tweet a sim mid-run" format alongside the finished-result share card |
| 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 |
| Gallery Search & Filter | Keyword search + bullish/neutral/bearish + excellent/good/fair/poor + sort by date/rounds/agents/trending on /explore and /verified. trending ranks by cumulative share-surface serves so the most-distributed sims float to the top. URL-encoded so ?q=aave&consensus=bearish is bookmarkable. Same ±0.2 stance threshold as every other surface |
| Verified Predictions | Annotate any public sim with the real-world outcome (called it / partial / called wrong + URL). /verified is the dedicated hall of calls that landed |
| RSS / Atom Feeds | /api/feed.atom + /api/feed.rss — every newly published simulation lands in Feedly / Readwise / Inoreader / NetNewsWire / Obsidian RSS without anyone curating it. ?verified=1 for the verified-only stream |
| 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 |
| Completion Webhook | POST a JSON summary the moment a sim finishes — wires Slack, Discord, Zapier, Make, n8n, or any custom endpoint with one URL field |
| Webhook Signature Verification | Optional WEBHOOK_SECRET HMAC-signs every dispatched payload with an X-MiroShark-Signature: sha256=<hex> header. Recipients verify in three lines of stdlib hmac — same scheme Stripe and GitHub use. Empty secret = no header, fully backward compatible |
| Webhook Delivery Log | Per-sim webhook-log.jsonl records every dispatch attempt (status code, latency, error). Inspect from the EmbedDialog and re-fire any failed delivery with a "Retry" button — closes the operational blindspot every Zapier / n8n integration eventually hits |
| Surface Usage Analytics | GET /api/simulation/<id>/surface-stats — per-share-surface request counters (share card / replay GIF / transcript / trajectory / thread / watch page / Atom / RSS / reproduce.json / lineage / notebook.ipynb) with a synthetic total. Inbound observability for the distribution loop the webhook log tracks on the outbound side |
| Reproducibility Config | GET /api/simulation/<id>/reproduce.json — citation primitive for the share surfaces. A v1-schema JSON blob carrying every parameter another operator needs to re-run the same simulation: scenario, agent count, total rounds, platform toggles, time-config knobs, director events, and fork / counterfactual lineage. Identical exports of a finished sim are bytewise-identical, so the file hash is a stable citation key |
| Jupyter Notebook Export | GET /api/simulation/<id>/notebook.ipynb — analysis-ready companion to the reproducibility config. The trajectory CSV is embedded directly inside the notebook so it runs air-gapped; cells scaffold imports, the belief-evolution line chart, the final-consensus bar chart, and a quality summary DataFrame. Opens in JupyterLab, VS Code, or Google Colab in one click. Bytewise-stable, same citation-hash property as reproduce.json |
| Lineage Navigator | GET /api/simulation/<id>/lineage — turn the parent_simulation_id pointer into a navigable graph. Surfaces the parent a sim was forked / branched from plus every public child whose parent points back at it. Trace the intellectual ancestry of a result without remembering each child sim id |
Each feature is documented in docs/FEATURES.md.
Use cases
- 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
Screenshots
 |  |
 |  |
 |  |
 |
 |
Documentation
| 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 |
| Observability | Debug panel, event stream, logging |
| Contributing | Tests and development |
中文
一切皆可模拟,只需 $1、不到 10 分钟 — 通用群体智能引擎 投入任何素材 — 新闻稿、头条、政策草案、一个无解的问题、一段历史假设 — MiroShark 都会派出数百个智能体,每小时一轮地做出反应:发帖、辩论、交易、改变想法。
它做什么
- 你提供一个情景,MiroShark 围绕它构建世界。
- 数百个有据可依的智能体在 Twitter、Reddit 与预测市场上每小时一轮地反应。
- 与任意智能体对话。在运行中投入突发新闻。派生出反事实分支。
- 生成一份引用真实发帖与交易的复盘报告。
快速开始
推荐路径:一个 OpenRouter 密钥 + ./miroshark 启动器。首次模拟约 10 分钟、约 $1。
前置条件 — Python 3.11+、Node 18+、Neo4j,以及 OpenRouter 密钥。
安装 Neo4j(启动器会自动启动它):
- macOS —
brew install neo4j - Linux —
sudo apt install neo4j(或所在发行版对应的命令) - Windows — 安装 Neo4j Desktop (原生 GUI,先在其中启动数据库,然后通过 WSL2 或 Git Bash 运行启动器),或在 WSL2 内运行整套环境并按 Linux 步骤操作
- 零安装 — 创建免费的 Neo4j Aura 云实例,在
.env中将NEO4J_URI/NEO4J_PASSWORD指向它
然后:
git clone https://github.com/aaronjmars/MiroShark.git && cd MiroShark
cp .env.example .env
# 将你的 OpenRouter 密钥粘贴到 LLM_API_KEY / SMART_API_KEY /
# NER_API_KEY / OPENAI_API_KEY / EMBEDDING_API_KEY 五个字段
# (同一个密钥,粘 5 处)。默认组合是 Mimo V2 Flash + Grok-4.1 Fast。
./miroshark
启动器会检查依赖、启动 Neo4j、安装前后端,并在 :3000 + :5001 提供服务。Ctrl+C 停止。打开 http://localhost:3000 投入文档即可。
界面语言 — 启动后,在导航栏右上角点击「中 / EN」按钮即可切换中英文。语言选择会保存在浏览器中,下次访问时自动应用。模板画廊与公开模拟列表的卡片标题/描述也会随之切换。
其他部署路径 — 一键 Railway / Render、Docker + Ollama、手动 Ollama、Claude Code CLI — 详见 docs/INSTALL.zh-CN.md。
主要功能
| 功能 | 说明 |
|---|---|
| 智能配置 | 投入文档 → 约 2 秒生成三套自动情景(看涨/看跌/中立) |
| 热门追踪 | 从 RSS 中挑选实时新闻,一键预填情景 |
| 直接提问 | 不用文档,直接打字提问 — MiroShark 自行调研并撰写种子简报 |
| 可分享情景链接 | 在推文或博客文章中放入 ?scenario=...&url=... 链接 — 读者一打开就会看到已预填的「新建模拟」表单。?template=<slug> 可自动启动任一预设模板。这是 /watch 与 /share 上「派生此情景」的「未运行情景」对应版本 |
| 反事实分支 | 在运行中的模拟里派生分支并注入事件(「如果 24 轮时 CEO 辞职会怎样?」) |
| 导演模式 | 在当前时间线中投入突发新闻,无需派生分支 |
| 预设模板 | 6 套基准情景:加密代币发布、企业危机、政治辩论、产品发布、校园风波、历史假设 |
| 现实预言机 | 可选地从 FeedOracle MCP 中拉取实时数据(484 个工具) |
| 每个智能体的 MCP 工具 | 人设可在模拟过程中调用真实 MCP 工具(网页搜索、API 等) |
| 自定义 Wonderwall 端点 | 将模拟主循环指向任意 OpenAI 兼容端点(自部署 vLLM、Modal、微调模型……),不影响 Default/Smart/NER。设置 WONDERWALL_BASE_URL + `WONDERWALL_API_KEY$ |
| 嵌入与发布 | 公开/私有切换 + 嵌入 \text{URL},便于分享已完成的运行 |
| 社交分享卡片 | 1200 \times 630 \text{PNG},自动展开情景、状态、质量与信念分布,适配 \text{Twitter}/\text{X}、\text{Discord}、\text{Slack}、\text{LinkedIn} |
| 信念回放动图 | 1200 \times 630 \text{GIF},每轮一帧,信念条动态滑向各轮分布。\text{Discord} 与 \text{Slack} 在直接 \text{URL} 上自动播放 |
| 转录导出 | 每轮智能体发帖与立场标签,导出为 \text{Markdown}(\text{YAML} 头,适配 \text{Notion} / \text{Obsidian} / \text{Substack})或结构化 \text{JSON}(适配 \text{SDK} 与 \text{LLM} 评审管线) |
| 推文串导出 | $GET /api/simulation/ |
| 公开图库 | /explore 以卡片网格浏览所有公开模拟 — 预览分享卡、共识分布与质量指标;一键打开或派生 |
| 图库搜索与筛选 | 在 /explore 与 /verified 上提供关键词搜索 + 看涨/中立/看跌 + 优秀/良好/一般/较差 + 按日期/轮次/智能体/热门排序。trending 按累计分享面服务次数排序,让被分发最广的模拟浮于顶部。URL 编码后 ?q=aave&consensus=bearish 可作为书签分享。与其他所有表面共享同一 ±0.2 立场阈值 |
| 已验证预言 | 为公开模拟标注真实结果(命中 / 部分 / 失误 + 链接)。/verified 是命中预言专属展厅 |
| RSS / Atom 订阅源 | /api/feed.atom + /api/feed.rss — 每个新发布的模拟无需任何整理就会进入 Feedly / Readwise / Inoreader / NetNewsWire / Obsidian RSS。?verified=1 只看已验证内容 |
| 文章生成 | Substack 风格的复盘文章,基于真实发帖与交易数据 |
| 互动网络 | 力导向智能体关系图,带回声室指标 |
| 人口分布 | 原型聚类(分析师 / 影响者 / 散户 / 旁观者……) |
| 质量诊断 | 单次运行的健康评分 — 参与度、连贯性、多样性、方差 |
| 历史数据库 | 搜索、克隆、导出或删除任一过往模拟 |
| 轨迹访谈 | 查看智能体回复背后的完整推理链,而不止是回复本身 |
| 推送通知 | 长耗时图谱 / 模拟 / 报告任务完成时的浏览器推送提醒 |
| 完成 Webhook | 模拟一结束即 POST 一份 JSON 摘要 — 一个 URL 字段即可连通 Slack、Discord、Zapier、Make、n8n 或任意自定义端点 |
| Webhook 签名验证 | 可选的 WEBHOOK_SECRET 会用 HMAC 对每次投递的载荷签名,并通过 X-MiroShark-Signature: sha256=<hex> 头部送出。消费方用三行 stdlib hmac 即可校验 — Stripe 和 GitHub 用的就是这一套。留空即无签名头部,完全向后兼容 |
| Webhook 投递日志 | 每个模拟在 webhook-log.jsonl 记录每次投递尝试(HTTP 状态码、延迟、错误)。可在 EmbedDialog 中查看,并通过「重试」按钮重发任何失败的投递 — 弥补每个 Zapier / n8n 集成最终都会遇到的运维盲点 |
| 分发统计(分享面使用分析) | GET /api/simulation/<id>/surface-stats — 每个分享面的请求计数器(分享卡 / 回放 GIF / 转录 / 轨迹 / 推文串 / 观看页 / Atom / RSS / reproduce.json / /lineage),以及合成的 total。Webhook 日志在出站侧跟踪分发回路,本面则负责入站可观测性 |
| 可复现配置导出 | GET /api/simulation/<id>/reproduce.json — 分享面背后的引用基元。v1-schema 的 JSON 文档,携带另一位研究者复现同一次模拟所需的全部参数:情景、智能体数、轮次、平台切换、时序配置、导演事件、派生 / 反事实谱系。已完成模拟的多次导出在字节级别完全一致 — 文件哈希可作为稳定的引用键 |
| 谱系导航 | GET /api/simulation/<id>/lineage — 将 parent_simulation_id 指针转化为可导航的图。展示该模拟派生 / 分支自的父模拟,以及每一个把父级指回此模拟的公开子模拟。无需记住每个子模拟 ID,即可追踪一项结果的思想脉络 |
每项功能详见 docs/FEATURES.zh-CN.md。
应用场景
- 公关危机演练 — 在新闻稿发布前模拟舆论反应
- 市场反应 — 喂入财经新闻,观察模拟交易者与投资者情绪
- 广告测试 — 在投放前用模拟受众检验文案、标题或卖点
- 政策分析 — 用模拟公众检验法规草案
- 人生抉择 — 把个人决定(换工作、搬家、上线时机)作为情景,看多元人设辩论
- 历史假设 — 改写一段历史事件,看一群人设如何重写后续叙事
- 创意实验 — 喂入失去结尾的小说,智能体续写出叙事自洽的结局
文档
| 安装 | 全部部署路径:云端、Docker、Ollama、Claude Code |
| 配置 | 环境变量、模型路由、特性开关 |
| 模型 | 云端预设、本地 Ollama 模型、基准发现 |
| 架构 | 模拟引擎、记忆管线、图谱检索 |
| 功能 | 上述功能表的深入解析 |
| HTTP API | 全部端点,按关注点分组 — 含 /api/docs 交互式 Swagger UI 与 /api/openapi.yaml 规范 |
| CLI | miroshark-cli 参考 |
| MCP | Claude Desktop / Cursor / Windsurf / Continue 集成 + 报告智能体工具(可在「设置 → AI 集成」中获取自动生成的片段) |
| Webhook | 完成 Webhook 载荷、头部、投递语义、Slack/Discord/Zapier/n8n 食谱 |
| 可观测性 | 调试面板、事件流、日志 |
| 贡献 | 测试与开发 |
License · 许可证
AGPL-3.0. See LICENSE. AGPL-3.0,详见 LICENSE。
Support the project · 支持本项目:0xd7bc6a05a56655fb2052f742b012d1dfd66e1ba3