convez.ai
Skill
ejgallego

lean-beam

ejgallego/lean-beam

Ver no GitHub
BomPluginScore · de 0 a 100

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-beam

1 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

Estrelas
56
Forks
8
Acompanhando
1
Saúde
71%
Último commit
há 2 dias
Versão
—
Issues abertas
39
Contribuidores
1

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, and lean-beam-mcp into ~/.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-at tries speculative Lean text without editing the file
  • lean-beam ensure --hold is for PID-isolated command runners that need one foreground process to keep a newly-started daemon alive across separate wrapper calls
  • lean-beam deps reports the broker's direct workspace dependency view for a path
  • lean-beam sync is the explicit on-disk edit barrier after a real saved edit
  • lean-beam refresh is lean-beam close plus lean-beam sync
  • lean-beam save checkpoints 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:

  • --stdin is 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_workspace with mode: "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-beam plus 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/runAt request for speculative execution at arbitrary document points
  • Beam: local broker, daemon/client pair, and CLI wrappers exposing a narrower agent-facing surface over LSP and Beam-specific extensions
  • skills: installed Claude/Codex workflow guidance built around lean-beam
  • Rocq support: a narrow auxiliary goal-probe surface through the same lean-beam wrapper, 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

License

Apache-2.0. See LICENSE.

Ver o original no GitHub

Bom para

Relacionados