lean-beam
ejgallego/lean-beam
Claude/Codex skill and local workflow layer for efficient interaction with Lean 4 and Monte-Carlo Tree Search.
Instalação
npx convez-ai ejgallego/lean-beam1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
README
A tradução para o português deste README ainda está na fila.
Lean Beam
Lean Beam provides a Claude/Codex skill and local workflow layer for efficient interaction with
Lean 4. Under the hood, it combines a Lean 4 LSP server extension, the $/lean/runAt request for
cheap speculative execution, and a thin local broker that exposes a more idiomatic CLI and agent
surface over Lean's LSP and Beam-specific extensions.
Lean Beam is aimed at agent-heavy workflows such as proof repair,
porting from other systems to Lean, proof-search experimentation
including Monte Carlo Tree Search (MCTS), and autoformalization. For
agents making many edits to Lean files, Lean Beam can provide
asymptotic savings over repeating lake build after every change; see
the cost model and workflow details.
Lean Beam started as a personal internal project and is now published for public use. It is not an official Lean FRO product, the code remains experimental, and you should use it at your own risk.
Feedback is welcome; feel free to open issues or let us know what you think on Zulip.
Install
Run the installer from the repo root:
./scripts/install-beam.sh
The default installer is interactive: it asks which supported Lean toolchains, agent skills, and
MCP client registrations to set up. It then shows a compact write summary and asks once for the Beam
runtime/wrapper install area, selected skill locations, and selected MCP config locations. For
non-interactive scripts, pass --dont-ask; this only skips prompts for requested Beam-owned
install/config paths and does not allow replacing unrelated user files.
That installs:
lean-beam,lean-beam-search, andlean-beam-mcpinto~/.local/bin- an immutable runtime under
BEAM_INSTALL_ROOT, default~/.local/share/beam - a prebuilt bundle for the repo-pinned supported Lean toolchain
Use --codex, --claude, or --all-skills to install the bundled agent skills:
./scripts/install-beam.sh --codex
./scripts/install-beam.sh --claude
./scripts/install-beam.sh --all-skills
Use --codex-mcp, --claude-mcp, or --all-mcp to register the installed lean-beam-mcp server
with Codex and/or Claude Code:
./scripts/install-beam.sh --codex-mcp
./scripts/install-beam.sh --claude-mcp
./scripts/install-beam.sh --all-mcp
Use --toolchain <toolchain> or --all-supported to prebuild additional validated Lean bundles:
./scripts/install-beam.sh --toolchain leanprover/lean4:v4.31.0
./scripts/install-beam.sh --all-supported
MCP Setup
The installer includes the experimental stdio MCP server as lean-beam-mcp. It can register the
server automatically for Codex, Claude Code, or both:
./scripts/install-beam.sh --codex-mcp
./scripts/install-beam.sh --claude-mcp
./scripts/install-beam.sh --all-mcp
To register an existing install manually, use an absolute path so the client can launch the server
even if ~/.local/bin is not on its PATH:
codex mcp add lean-beam -- "$HOME/.local/bin/lean-beam-mcp"
claude mcp add --scope user lean-beam -- "$HOME/.local/bin/lean-beam-mcp"
MCP clients that support workspace roots can use that command as-is; Lean Beam discovers the project
root through roots/list. If a client does not provide roots, initialize one absolute Lean/Lake
project root per MCP server session with the lean_init_workspace tool before calling Lean tools:
{"root":"/path/to/lean/project"}
The normal call omits mode. Advanced clients can use mode: "verify" to check the active root or
mode: "reset" to explicitly switch roots and invalidate handles; see
docs/STATUS.md.
Direct developer runs and single-project MCP registrations may still pass an explicit project root:
codex mcp add lean-beam -- "$HOME/.local/bin/lean-beam-mcp" --root /path/to/lean/project
claude mcp add --scope user lean-beam -- "$HOME/.local/bin/lean-beam-mcp" --root /path/to/lean/project
The --root startup flag accepts absolute paths and paths relative to the server's current working
directory. The lean_init_workspace tool intentionally accepts only absolute paths so clients do not
accidentally bind a session to a root interpreted from the server process cwd.
The wrapper resolves the matching installed beam-cli, Lean command, and runAt plugin for each
project. Direct developer runs of .lake/build/bin/lean-beam-mcp may still pass --lean-cmd and
--lean-plugin explicitly.
To verify the MCP path from a Lean project without writing JSON-RPC by hand, run:
lean-beam-mcp --root /path/to/lean/project --self-check MyPkg/Sub/Module.lean
The self-check starts a child MCP server, supplies the root through MCP roots/list, calls
lean_sync on the file, and shuts the child server down.
Supported Toolchains
Lean Beam only serves Lean toolchains listed in supported-lean-toolchains.
Inspect the validated allowlist with:
lean-beam supported-toolchains
The current repo allowlist is:
leanprover/lean4:v4.31.0
leanprover/lean4:v4.30.0
leanprover/lean4:v4.29.0
leanprover/lean4:v4.28.0
If you are unsure which runtime bundle is active or why a toolchain is rejected, use:
lean-beam doctor
Agent-Facing Surface
For most agent-oriented workflows, the practical entry point is lean-beam together with the
workflow guidance in skills/lean-beam/SKILL.md.
Common Lean commands:
lean-beam ensure
lean-beam ensure --hold
lean-beam hover "Foo.lean" 10 2
lean-beam goals-prev "Foo.lean" 10 2
lean-beam run-at "Foo.lean" 10 2 "exact trivial"
lean-beam deps "Foo.lean"
lean-beam sync "MyPkg/Sub/Module.lean"
lean-beam refresh "MyPkg/Sub/Module.lean"
lean-beam save "MyPkg/Sub/Module.lean"
Read those commands like this:
lean-beam run-attries speculative Lean text without editing the filelean-beam ensure --holdis for PID-isolated command runners that need one foreground process to keep a newly-started daemon alive across separate wrapper callslean-beam depsreports the broker's direct workspace dependency view for a pathlean-beam syncis the explicit on-disk edit barrier after a real saved editlean-beam refreshislean-beam closepluslean-beam synclean-beam savecheckpoints one synced workspace module; it does not validate downstream importers
Multiline and handle-oriented wrapper ergonomics:
# for multiline probe text, prefer stdin
printf 'example : True := by\n trivial\n' | lean-beam run-at "Foo.lean" 10 2 --stdin
# for exact continuation, prefer a handle file
lean-beam run-at-handle "Foo.lean" 10 2 "constructor"
lean-beam run-with "Foo.lean" --handle-file handle.json "exact trivial"
Read those flags like this:
--stdinis the normal multiline path for speculative Lean text--handle-file <path>is the normal handle path for exact continuation and release- MCP workspace reset invalidates handles minted by the old runtime; discard saved handle files after
lean_init_workspacewithmode: "reset" - deeper shell-oriented variants and debugging knobs live in skills/lean-beam/SKILL.md and the linked reference docs
When lean-beam sync fails with syncBarrierIncomplete, the JSON error may include
error.data.staleDirectDeps, error.data.saveDeps, and error.data.recoveryPlan to suggest a
cheap direct-import recovery path before falling back to lake build.
Detailed Lean workflow guidance lives in skills/lean-beam/SKILL.md. The narrower Rocq surface lives in skills/rocq-beam/SKILL.md.
Which Layer To Use
- Use
lean-beamplus the installed skills if you want the practical agent workflow that integrates with Codex or Claude out of the box - Use the Beam broker if you want one long-lived local process per project root while keeping a narrower local protocol than raw LSP
- Use the Lean LSP extension directly if you already own the LSP session and want the smallest typed surface, or if you want to build custom agents doing MCTS or other advanced setups
The public request and response types live in RunAt/Protocol.lean. The Lean plugin implementation lives in RunAt/Plugin.lean.
How The Code Is Organized
RunAt: Lean LSP server plugin providing the$/lean/runAtrequest for speculative execution at arbitrary document pointsBeam: local broker, daemon/client pair, and CLI wrappers exposing a narrower agent-facing surface over LSP and Beam-specific extensionsskills: installed Claude/Codex workflow guidance built aroundlean-beam- Rocq support: a narrow auxiliary goal-probe surface through the same
lean-beamwrapper, useful when porting from Rocq to Lean tests: scenario-DSL coverage for LSP-level behavior, concurrent stress coverage, broker and wrapper regression suites, and install/runtime validation
Local Build And Test (for development)
Build:
lake build
Core tests:
bash tests/test.sh
Broker and wrapper suites:
bash tests/test-broker-fast.sh
bash tests/test-broker-slow.sh
bash tests/test-broker-rocq.sh
bash tests/test-broker.sh
bash scripts/lint-shell.sh
GitHub Actions currently validates the main CI job set from .github/workflows/ci.yml on both Ubuntu and macOS.
More detail on test coverage and gaps lives in docs/TESTING.md.
Documentation Map
- docs/STATUS.md: current scope, limitations, and direction
- skills/lean-beam/SKILL.md: Lean workflow contract
- skills/rocq-beam/SKILL.md: auxiliary Rocq workflow surface
- CONTRIBUTING.md: commit, PR, and contributor workflow guidance
- docs/DEVELOPMENT.md: AI-first maintainer workflow and harness guidance
- docs/TESTING.md: test coverage and gaps
- docs/experimental.md: unstable experimental surfaces
- AGENTS.md: repo-specific agent instructions
License
Apache-2.0. See LICENSE.