Skip to content
specular-orgPublic

About

Specular: An agentic tool for finding deep bugs in system code using TLA+

Resources

Contributing

Stars

698 stars

Watchers

10 watching

Forks

Repository files navigation

specular

Scaling formal specs for autonomous bug finding

arXiv: 2607.25333 CI License: Apache 2.0

Specula is now Specular. To update an existing install, follow Switching from Specula.

Specular (formerly Specula) finds deep bugs in concurrent and distributed system code. It 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. Specular has been used to find deep bugs in many open-source projects.

We maintain a list of bugs found by Specular. We would love to hear about your experience using Specula and the bugs you found. Contact us!

Browse the case-study archive for reports, models, and reproduction evidence. The case-studies submodule pins the archive and its system and run indexes for this checkout.

Prerequisites

  • Python 3.10+ with pip
  • uv
  • Java 21+ with Maven
  • GitHub CLI gh
  • Supported agents (Claude Code, Codex, Copilot CLI, OpenCode, or Pi). Please contribute adapters for new agents.
  • Coding agent. (Specular uses coding agents to read code, infer invariants, and reason about counterexamples.)
  • Machine: We recommend at least 32 GB of RAM and 100 GB of free disk space; more RAM is preferable. See the Usage Guide.

Windows: run Specular inside WSL2. Native Windows (outside WSL2) is not supported yet.

Recommended Coding Agents

We recommend using the following coding agents, which we actively test:

  • Claude Code with Claude Opus 5.5 or Fable 5.2
  • Codex with GPT-6-Astra or GPT-6.1-Sol

Other strong coding agents may work, but we do not test them regularly during our development. We recently tested Claude Code with the latest GLM, Kimi, and DeepSeek models (see Usage Guide).

For the latest OpenAI and Anthropic models, apply for Trusted Access through OpenAI and Anthropic, respectively. Without the required access, providers may block bug-reproduction requests during confirmation. If you cannot obtain access, use hybrid configuration to select another agent or model for that phase.

Setup

git clone https://github.com/specular-org/Specular.git && cd Specular
uv tool install -e .   # installs the `specular` command
specular setup          # installs the agent skills and MCP tools, builds the bundled tools
Manual Setup

You need to set up the Specular Agent Skills and MCP with your coding agent.

  • Symlink the Specular skills directory to the one read by your coding agent, e.g., ~/.claude/skills or .claude/skills for Claude Code, ~/.codex/skills or .agents/skills for Codex, and .github/skills for Copilot CLI.
  • Add the trace_debugger, spec_analyzer, and inv_checking_tool MCP tools to your agent config. Please build the CFA tool with Maven before adding spec_analyzer.
# for trace debugger MCP
cd tools/trace_debugger
python3 -m venv .venv
. .venv/bin/activate
pip install -r requirements.txt
cd ../..  # return to the Specular repository root

# for Claude Code
claude mcp add --transport stdio --scope project \
    tracedebugger \
    --env "SPECULAR_ROOT=$PWD" -- \
    "$PWD/tools/trace_debugger/.venv/bin/python" \
    "$PWD/tools/trace_debugger/mcp_server.py"

# for Codex
codex mcp add tracedebugger \
	--env "SPECULAR_ROOT=$PWD" -- \
	"$PWD/tools/trace_debugger/.venv/bin/python" \
	"$PWD/tools/trace_debugger/mcp_server.py"

# for GitHub Copilot CLI 1.0.21+
copilot mcp add tracedebugger \
    --env "SPECULAR_ROOT=$PWD" -- \
    "$PWD/tools/trace_debugger/.venv/bin/python" \
    "$PWD/tools/trace_debugger/mcp_server.py"

Automatic MCP configuration is skipped for older Copilot CLI versions; upgrade to the latest version to enable it.

Auto Mode

specular run mysys \
  --artifact=/path/to/repo \
  --guidance=/absolute/path/to/mysys-guidance.md

The mysys-guidance.md is optional but recommended. It is a configuration file that guides Specular to focus on target modules and scenarios, with consistent modeling scope across runs. We provide a template and an example.

Outputs are stored in runs/<run-id>. After a run, start with runs/latest/pipeline-summary.md.

Add --keep-original to leave the source checkout untouched. Specular runs the same agents against a full private copy and writes a reviewable source diff to runs/<run-id>/mysys/changes.patch. Ignored build output is omitted, while binary and trace contents remain in the private source instead of being inlined. Specular does not apply the diff to the original checkout.

The detailed usage and configurations can be found in the Usage Guide.

Continuous Verification

Initialize a persistent model and harness, then check later source changes incrementally:

specular run --ci-init --ci-dir=/work/mysys-ci \
  --artifact=/path/to/repo --guidance=/path/to/mysys-guidance.md mysys
specular run --incremental --ci-dir=/work/mysys-ci

Keep the CI directory outside the source checkout. See Add Specular to CI for setup, results, and the GitHub Actions workflow. Existing TLA+ models and verification assets can be imported with Bring Your Own Model.

Interactive Mode

Open your coding agent in the Specular directory. The workflow is a sequence of skills, each producing input for the next:

code-analysis → spec-generation → harness-generation → validation-workflow → bug-confirmation

(Codex uses $code-analysis, $spec-generation, etc. after choosing y in specular setup, or $specular-codex:code-analysis, $specular-codex:spec-generation, etc. in plugin mode.)

To start, tell the agent your target and invoke the first skill:

This project is a Go implementation of Tendermint BFT consensus (cometbft/cometbft).
The reference algorithm is the Tendermint paper (arXiv:1807.04938). Run /code-analysis.

Each skill produces output files (e.g., modeling-brief.md, base.tla, traces) in .specular-output that the next skill will consume. When one skill completes, invoke the next. You can also run any skill independently, e.g., validation-workflow on an existing spec.

Changelog

See CHANGELOG.md for release history and notable changes.

Who uses Specular?

Specular is used by researchers and engineers at organizations including:

Google      Microsoft      AmazonAmazon      NVIDIANVIDIA      Oracle      HuaweiHuawei

Alibaba GroupAlibaba Group      UberUber      Ant GroupAnt Group      MongoDBMongoDB      DatadogDatadog      Cloudera

Shopee      Milvus      Apache OzoneApache Ozone      Apache RatisApache Ratis      Asterinas      SREGym

University of Illinois Urbana-ChampaignUniversity of Illinois Urbana-Champaign      UC BerkeleyUC Berkeley      Purdue UniversityPurdue University      New York UniversityNew York University      University of VirginiaUniversity of Virginia

Acknowledgement

We are grateful to the generous support from:

  • TLA+ Foundation
  • OpenAI
  • Anthropic (AI for Science Program)
  • Qingrong Chen

License

Apache License 2.0.

About

Specular: An agentic tool for finding deep bugs in system code using TLA+

Resources

Contributing

Stars

698 stars

Watchers

10 watching

Forks

Releases

Packages

Contributors

Languages