[{"data":1,"prerenderedAt":4},["ShallowReactive",2],{"readme:specula":3},"\u003Cp align=\"center\">\n  \u003Cpicture>\n    \u003Csource media=\"(prefers-color-scheme: dark)\" srcset=\"pics\u002Flogo.png\">\u003C\u002Fsource>\n    \u003Cimg alt=\"specula\" src=\"https:\u002F\u002Fraw.githubusercontent.com\u002Fspecula-org\u002Fspecula\u002FHEAD\u002Fpics\u002Flogo.png\" width=\"40%\" \u002F>\n  \u003C\u002Fpicture>\n\u003C\u002Fp>\u003Ch2>\nScaling formal specs for autonomous bug finding\n\u003C\u002Fh2>\u003Cp align=\"center\">\n  \u003Ca href=\"https:\u002F\u002Farxiv.org\u002Fabs\u002F2607.25333\" rel=\"nofollow ugc noopener\">\n    \u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FarXiv-2607.25333-b31b1b.svg\" alt=\"arXiv: 2607.25333\" \u002F>\n  \u003C\u002Fa>\n  \u003Ca href=\"https:\u002F\u002Fgithub.com\u002Fspecula-org\u002FSpecula\u002Factions\u002Fworkflows\u002Fci.yml\" rel=\"nofollow ugc noopener\">\n    \u003Cimg src=\"https:\u002F\u002Fgithub.com\u002Fspecula-org\u002FSpecula\u002Factions\u002Fworkflows\u002Fci.yml\u002Fbadge.svg?branch=main\" alt=\"CI\" \u002F>\n  \u003C\u002Fa>\n  \u003Ca href=\"https:\u002F\u002Fgithub.com\u002Fspecula-org\u002FSpecula\u002Fblob\u002Fmain\u002FLICENSE\" rel=\"nofollow ugc noopener\">\n    \u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fbadge\u002Flicense-Apache--2.0-blue.svg\" alt=\"License: Apache 2.0\" \u002F>\n  \u003C\u002Fa>\n\u003C\u002Fp>\u003Cp>Specula finds deep bugs in concurrent and distributed system code. \nIt uses coding agents to write TLA+ specs of the target system, including invariants that capture the system's correctness properties and formal models that describe the system implementation. It then model-checks the specs and reproduces violations at the code level. Specula has been used to find deep bugs in many open-source projects. For more details, see our \u003Ca href=\"https:\u002F\u002Farxiv.org\u002Fabs\u002F2607.25333\" rel=\"nofollow ugc noopener\">paper\u003C\u002Fa>.\u003C\u002Fp>\n\u003Cp>We maintain \u003Ca href=\"https:\u002F\u002Fdocs.google.com\u002Fspreadsheets\u002Fd\u002F1AVXdKjNfD4952hZqyB-_wTdrzeTw0SD73f3F0zWJ0as\" rel=\"nofollow ugc noopener\">a list of bugs found by Specula\u003C\u002Fa>. We would love to hear about the bugs you find using Specula.\u003C\u002Fp>\n\u003Ch2>Prerequisites\u003C\u002Fh2>\n\u003Cul>\n\u003Cli>Python 3.10+ with pip\u003C\u002Fli>\n\u003Cli>\u003Ca href=\"https:\u002F\u002Fdocs.astral.sh\u002Fuv\u002F\" rel=\"nofollow ugc noopener\">uv\u003C\u002Fa>\u003C\u002Fli>\n\u003Cli>Java 21+ with Maven\u003C\u002Fli>\n\u003Cli>GitHub CLI \u003Ccode>gh\u003C\u002Fcode>\u003C\u002Fli>\n\u003Cli>Supported agents (Claude Code, Codex, Copilot CLI, OpenCode, or Pi). Please contribute \u003Ca href=\"https:\u002F\u002Fgithub.com\u002Fspecula-org\u002Fspecula\u002Fblob\u002FHEAD\u002Fscripts\u002Flaunch\u002Fadapters\" rel=\"nofollow ugc noopener\">adapters\u003C\u002Fa> for new agents.\u003C\u002Fli>\n\u003Cli>Coding agent. (Specula uses coding agents to read code, infer invariants, and reason about counterexamples.)\u003C\u002Fli>\n\u003Cli>\u003Cstrong>Machine:\u003C\u002Fstrong> We recommend at least 32 GB of RAM and 100 GB of free disk space; more RAM is preferable. See the \u003Ca href=\"https:\u002F\u002Fgithub.com\u002Fspecula-org\u002Fspecula\u002Fblob\u002FHEAD\u002Fdocs\u002FUsage.md\" rel=\"nofollow ugc noopener\">Usage Guide\u003C\u002Fa>.\u003C\u002Fli>\n\u003C\u002Ful>\n\u003Cblockquote>\n\u003Cp>\u003Cstrong>Windows:\u003C\u002Fstrong> run Specula inside \u003Ca href=\"https:\u002F\u002Flearn.microsoft.com\u002Fwindows\u002Fwsl\u002Finstall\" rel=\"nofollow ugc noopener\">WSL2\u003C\u002Fa>. Native Windows (outside WSL2) is not supported yet.\u003C\u002Fp>\n\u003C\u002Fblockquote>\n\u003Ch2>Recommended Coding Agents\u003C\u002Fh2>\n\u003Cp>We recommend using the following coding agents, which we actively test:\u003C\u002Fp>\n\u003Cul>\n\u003Cli>Claude Code with Claude Opus 4.8 or Fable\u003C\u002Fli>\n\u003Cli>Codex with GPT-5.5 or GPT-5.6-Sol\u003C\u002Fli>\n\u003C\u002Ful>\n\u003Cp>Other strong coding agents may work, but we do not test them regularly during our development. We recently tested Claude Code with GLM-5.2, Kimi 2.7, and DeepSeek V4 (see \u003Ca href=\"https:\u002F\u002Fgithub.com\u002Fspecula-org\u002Fspecula\u002Fblob\u002FHEAD\u002Fdocs\u002FUsage.md\" rel=\"nofollow ugc noopener\">Usage Guide\u003C\u002Fa>).\u003C\u002Fp>\n\u003Cp>\u003Cstrong>For GPT-5.6-Sol and Fable\u003C\u002Fstrong>, apply for Trusted Access through \u003Ca href=\"https:\u002F\u002Fchatgpt.com\u002Fcyber\" rel=\"nofollow ugc noopener\">OpenAI\u003C\u002Fa> and \u003Ca href=\"https:\u002F\u002Fportal.anthropic.com\u002Fprograms\u002Fcvp\" rel=\"nofollow ugc noopener\">Anthropic\u003C\u002Fa>, respectively. Without the required access, providers may block bug-reproduction requests during confirmation. If you cannot obtain access, use \u003Ca href=\"https:\u002F\u002Fgithub.com\u002Fspecula-org\u002Fspecula\u002Fblob\u002FHEAD\u002Fdocs\u002FUsage.md#hybrid-agent-configuration\" rel=\"nofollow ugc noopener\">hybrid configuration\u003C\u002Fa> to select another agent or model for that phase.\u003C\u002Fp>\n\u003Ch2>Setup\u003C\u002Fh2>\n\u003Cpre>\u003Ccode class=\"language-bash\">git clone https:\u002F\u002Fgithub.com\u002Fspecula-org\u002FSpecula.git && cd Specula\nuv tool install -e .   # installs the `specula` command\nspecula setup          # installs the agent skills and MCP tools, builds the bundled tools\n\u003C\u002Fcode>\u003C\u002Fpre>\n\u003Cdetails>\n\u003Csummary>Manual Setup\u003C\u002Fsummary>\u003Cp>You need to set up the Specula Agent Skills and MCP with your coding agent.\u003C\u002Fp>\n\u003Cul>\n\u003Cli>Symlink \u003Ca href=\"https:\u002F\u002Fgithub.com\u002Fspecula-org\u002FSpecula\u002Ftree\u002Fmain\u002Fskills\" rel=\"nofollow ugc noopener\">the Specula \u003Ccode>skills\u003C\u002Fcode> directory\u003C\u002Fa> to the one read by your coding agent, e.g., \u003Ccode>~\u002F.claude\u002Fskills\u003C\u002Fcode> or \u003Ccode>.claude\u002Fskills\u003C\u002Fcode> for Claude Code, \u003Ccode>~\u002F.codex\u002Fskills\u003C\u002Fcode> or \u003Ccode>.agents\u002Fskills\u003C\u002Fcode> for Codex, and \u003Ccode>.github\u002Fskills\u003C\u002Fcode> for Copilot CLI.\u003C\u002Fli>\n\u003Cli>Add the \u003Ccode>trace_debugger\u003C\u002Fcode>, \u003Ccode>spec_analyzer\u003C\u002Fcode>, and \u003Ccode>inv_checking_tool\u003C\u002Fcode> \u003Ca href=\"https:\u002F\u002Fgithub.com\u002Fspecula-org\u002FSpecula\u002Ftree\u002Fmain\u002Ftools\u002F\" rel=\"nofollow ugc noopener\">MCP tools\u003C\u002Fa> to your agent config. Please \u003Ca href=\"https:\u002F\u002Fgithub.com\u002Fspecula-org\u002Fspecula\u002Fblob\u002FHEAD\u002Ftools\u002Fcfa\" rel=\"nofollow ugc noopener\">build the CFA tool\u003C\u002Fa> with Maven before adding \u003Ccode>spec_analyzer\u003C\u002Fcode>.\u003C\u002Fli>\n\u003C\u002Ful>\n\u003Cpre>\u003Ccode class=\"language-bash\"># for trace debugger MCP\ncd tools\u002Ftrace_debugger\npython3 -m venv .venv\n. .venv\u002Fbin\u002Factivate\npip install -r requirements.txt\ncd ..\u002F..  # return to the Specula reposit\n\u003C\u002Fcode>\u003C\u002Fpre>\n\u003C\u002Fdetails>",1785888997311]