rocq-lsp is a Language Server for the Rocq Prover. It provides a single server that implements:

• the LSP protocol, with custom extensions
• the petanque protocol, designed for low-latency interaction with Rocq, idel for AI and software engineering applications
• the MCP protocol (upcoming), an open protocol that standardizes how applications provide context to LLMs

☕ Try it online ☕: https://github.dev/ejgallego/hello-rocq

Key features of rocq-lsp are: continuous, incremental document checking, real-time interruptions and limits, programmable error recovery, literate Markdown and LaTeX document support, multiple workspaces, positional goals, information panel, performance data, completion, jump to definition, extensible command-line compiler, a plugin system, and more.

rocq-lsp is built on Flèche, a new document checking engine for formal documents based on our previous work on SerAPI and jsCoq.

Designed for interactive use and web-native environments, Flèche is extensible and supports advanced tooling integration and capabilities beyond standard Rocq.

See the User Manual and the General Documentation Index for more details.

This repository also includes the rocq-lsp Visual Studio Code editor extension for the Rocq Proof Assistant, and a few other components. See our contributing guide for more information. Support for Emacs, Vim and Neovim is also available in their own projects.

Quick Install:

• 🐧 Linux / 🍎 macOs / 🪟 Windows:

$ opam install coq-lsp && code --install-extension ejgallego.coq-lsp

• 🦄 Emacs:

 (use-package rocq-mode
    :vc (:url "https://codeberg.org/jpoiret/rocq-mode.el.git"
         :rev :newest)
    :mode "\\.v\\'"
    :hook
    (rocq-mode . rocq-follow-viewport-mode)
    (rocq-mode . rocq-auto-goals-at-point-mode))

• 🪟 Windows: (alternative method)

  Download the Rocq Platform installer

• 🎁 Features
  • ⏩ Incremental Compilation and Continuous Document Checking
  • 👁 On-demand, Follow The Viewport Document Checking
  • 🧠 Smart, Cache-Aware Error Recovery
  • 🥅 Whole-Document Goal Display
  • 🗒️ Markdown Support
  • 👥 Document Outline
  • 🐝 Document Hover
  • 📁 Multiple Workspaces
  • 💾 .vo file saving
  • ⏱️ Detailed Timing and Memory Statistics
  • 🔧 Client-Side Configuration Options
  • 🖵 Extensible, Machine-friendly Command Line Compiler
  • ♻️ Reusability, Standards, Modularity
  • 🌐 Web Native!
  • 🔎 A Platform for Research!
• 🛠️ Installation
  • 🏘️ Supported Rocq (and Coq) Versions
  • 🏓 Server
  • 🫐 Visual Studio Code
  • 🦄 Emacs
  • ✅ Vim
  • 🩱 Neovim
  • 🐍 Python
• ⇨ rocq-lsp users and extensions
• 🗣️ Discussion Channel
• ☎ Weekly Calls
• ❓FAQ
• ⁉️ Troubleshooting and Known Problems
  • 📂 Working With Multiple Files
• 📔 Planned Features
• 📕 Protocol Documentation
• 🤸 Contributing and Extending the System
• 🥷 Team
  • 🕰️ Past Contributors
• ©️ Licensing Information
• 👏 Acknowledgments

Edit your file, and rocq-lsp will try to re-check only what is necessary, continuously. No more dreaded Ctrl-C Ctrl-N! Rechecking tries to be smart, and will ignore whitespace changes.

In a future release, rocq-lsp will save its document cache to disk, so you can restart your proof session where you left it at the last time.

Incremental support is undergoing refinement, if rocq-lsp rechecks when it should not, please file a bug!

rocq-lsp does also support on-demand checking. Two modes are available: follow the cursor, or follow the viewport; the modes can be toggled using the Language Status Item in Code's bottom right corner:

rocq-lsp won't stop checking on errors, but supports (and encourages) working with proof documents that are only partially working. Error recovery integrates with the incremental cache, and does recognize proof structure.

You can edit without fear inside a Proof. ... Qed., the rest of the document won't be rechecked; you can leave bullets and focused goals unfinished, and rocq-lsp will automatically admit them for you.

If a lemma is not completed, rocq-lsp will admit it automatically. No more Admitted / Qed churn!

rocq-lsp will follow the cursor movement and show underlying goals and messages; as well as information about what goals you have given up, shelves, pending obligations, open bullets and their goals.

Goal display behavior is configurable in case you'd like to trigger goal display more conservatively.

Open a markdown file with a .mv extension, or a TeX file ending in .lv or .v.tex, then rocq-lsp will check the code parts that are enclosed into rocq language blocks! rocq-lsp places human-friendly documents at the core of its design ideas.

Moreover, you can use the usual Visual Studio Code Markdown or LaTeX preview facilities to render your markdown documents nicely!

rocq-lsp supports document outline and code folding, allowing you to jump directly to definitions in the document. Many of the Rocq vernacular commands like Definition, Theorem, Lemma, etc. will be recognized as document symbols which you can navigate to or see the outline of.

Hovering over a Rocq identifier will show its type.

Hover is also used to get debug information, which can be enabled in the preferences panel.

rocq-lsp supports projects with multiple _RocqProject (or _CoqProject) files, use the "Add folder to Workspace" feature of Visual Studio code or the LSP Workspace Folders extension to use this in your project.

rocq-lsp can save a .vo file of the current document as soon as it the checking has been completed, using the command Coq LSP: Save file to .vo.

You can configure rocq-lsp in settings to do this every time you save your .vo file, but this can be costly so we ship it disabled by default.

Hover over any Rocq sentence, rocq-lsp will display detailed memory and timing statistics.

rocq-lsp is configurable, and tries to adapt to your own workflow. What to do when a proof doesn't check, admit or ignore? You decide!

See the rocq-lsp extension configuration in VSCode for options available.

rocq-lsp includes the fcc "Flèche Coq Compiler" which allows the access to almost all the features of Flèche / rocq-lsp without the need to spawn a fully-fledged LSP client.

fcc has been designed to be machine-friendly and extensible, so you can easily add your pre/post processing passes, for example to analyze or serialize parts of Rocq files.

Thanks to Flèche, we provide some APIs on top of it that allow advanced use cases with Rocq. In particular, we provide direct, low-overhead access to Rocq's proof engine using petanque.

The incremental document checking library of rocq-lsp has been designed to be reusable by other projects written in OCaml and with needs for document validation UI, as well as by other Rocq projects such as jsCoq.

Moreover, we are strongly based on standards, aiming for the least possible extensions.

rocq-lsp has been designed from the ground up to fully run inside your web browser seamlessly; our sister project, jsCoq has been already been ported to rocq-lsp, and future releases will use it by default.

rocq-lsp provides an exciting new array of opportunities for jsCoq, lifting some limitations we inherited from Rocq's lack of web native support.

A key rocq-lsp goal is to serve as central platform for researchers in Human-Computer-Interaction, Machine Learning, and Software Engineering willing to interact with Rocq.

Towards this goal, rocq-lsp extends and is in the process of replacing Coq SerAPI, which has been used by many to that purpose.

If you are a SerAPI user, please see our preliminary migrating from SerAPI document.

In order to use rocq-lsp you'll need to install both rocq-lsp and a suitable LSP client that understands rocq-lsp extensions. The recommended client is the Visual Studio Code Extension, but we aim to fully support other clients officially and will do so once their authors consider them ready.

rocq-lsp supports Rocq 9.1, Rocq 9.0, Coq 8.20, and Rocq's master branch. Code for each Rocq version can be found in the corresponding branch. We support OCaml 4.14, 5.3, and 5.4.

We recommended using Rocq 9.1 or master version. For other Rocq versions, we recommend users to install the custom Rocq tree as detailed in Rocq Upstream Bugs.

Note that this section covers user installs, if you would like to contribute to rocq-lsp and build a development version, please check our contributing guide

• opam (OSX/Linux):

  opam install coq-lsp
  

• Nix:

  • In nixpkgs: coqPackages.coq-lsp
  • The rocq-lsp server is automatically put in scope when running nix-shell in a project using the Rocq Nix Toolbox (added to the toolbox Oct 10th 2023).
  • An example of a flake that uses rocq-lsp in a development environment is here https://github.com/HoTT/Coq-HoTT/blob/master/flake.nix .

• Windows: Experimental Windows installers based on the Rocq Platform are available at https://www.irif.fr/~gallego/coq-lsp/

  This provides a Windows native binary that can be executed from VSCode normally. As of today a bit of configuration is still needed:

  • In VSCode, set the Coq-lsp: Path to:
    • C:\Coq-Platform~8.20-lsp\bin\coq-lsp.exe
  • In VSCode, set the Coq-lsp: Args to:
    • --coqlib=C:\Coq-Platform~8.20-lsp\lib\coq\
    • --coqcorelib=C:\Coq-Platform~8.20-lsp\lib\coq-core\
    • --ocamlpath=C:\Coq-Platform~8.20-lsp\lib\
  • Replace C:\Coq-Platform~8.20-lsp\ by the path you have installed Rocq above as needed
  • Note that the installers are unsigned (for now), so you'll have to click on "More info" then "Run anyway" inside the "Windows Protected your PC" dialog
  • Also note that the installers are work in progress, and may change often.

• Do it yourself! Compilation from sources

• Official Marketplace: https://marketplace.visualstudio.com/items?itemName=ejgallego.coq-lsp
• Open VSX: https://open-vsx.org/extension/ejgallego/coq-lsp

The official Rocq Emacs mode is https://codeberg.org/jpoiret/rocq-mode.el , maintained by Josselin Poiret with contributions by Arthur Azevedo de Amorim.

• Experimental CoqTail support by Wolf Honore: whonore/Coqtail#323

  See it in action https://asciinema.org/a/mvzqHOHfmWB2rvwEIKFjuaRIu

• Experimental client by Jaehwang Jung: https://github.com/tomtomjhj/coq-lsp.nvim

• Interact programmatically with Rocq files by using the Coqpyt by Pedro Carrott and Nuno Saavedra.

• rocq-lsp-client by Yoshihiro Imai/Proof Ninja.

The below projects are using rocq-lsp, we recommend you try them!

• Coqpyt, a Python client for rocq-lsp
• CoqPilot uses Large Language Models to generate multiple potential proofs and then uses rocq-lsp to typecheck them.
• jsCoq: use Coq from your browser
• Pytanque: a Python library implementing RL Environments
• ViZX: A Visualizer for the ZX Calculus.
• The Waterproof vscode extension helps students learn how to write mathematical proofs.
• Yade: Support for the YADE diagram editor in VSCode.

rocq-lsp discussion channel it at Rocq's Zulip, don't hesitate to stop by; both users and developers are welcome.

We hold (almost) weekly video conference calls, see the Call Schedule Page for more information. Everyone is most welcome!

See our list of frequently-asked questions.

Unfortunately Rocq releases contain bugs that affect rocq-lsp. We strongly recommend that if you are installing via opam, you use the following branches that have some fixes backported:

• For 9.1: No known critical problems
• For 9.0: No known critical problems
• For 8.20: No known critical problems
• For 8.19: opam pin add coq-core https://github.com/ejgallego/coq.git#v8.19+lsp
• For 8.18: opam pin add coq-core https://github.com/ejgallego/coq.git#v8.18+lsp
• For 8.17: opam pin add coq-core https://github.com/ejgallego/coq.git#v8.17+lsp

• Current rendering code can be slow with complex goals and messages, if that's the case, please open an issue and set the option Coq LSP > Method to Print Coq Terms to 0 as a workaround.
• rocq-lsp can fail to interrupt Coq in some cases, such as Qed or type class search. If that's the case, please open an issue, we have a experimental branch that solves this problem that you can try.
• If you install coq-lsp/VSCode simultaneously with the VSRocq Visual Studio Code extension, Visual Studio Code gets confused and neither of them may work. rocq-lsp will warn about that. You can disable the VSRocq extension as a workaround.
• _RocqProject file parsing library will often exit 1 on bad _RocqProject files! There is little rocq-lsp can do here, until upstream fixes this.

• Some problems can be resolved by restarting coq-lsp, in Visual Studio Code, Ctrl+Shift+P will give you access to the coq-lsp.restart command. You can also start / stop the server from the status bar.
• In VSCode, the "Output" window will have a "Coq LSP Server Events" channel which should contain some important information; the content of this channel is controlled by the Coq LSP > Trace: Server option.

See planned features and contribution ideas for a list of things we'd like to happen.

rocq-lsp mostly implements the LSP Standard, plus some extensions specific to Rocq.

Check the rocq-lsp protocol documentation for more details.

Contributions are very welcome! Feel free to chat with the dev team in Zulip for any question, or just go ahead and hack.

We have a contributing guide, which includes a description of the organization of the codebase, developer workflow, and more.

Here is a list of project ideas that could be of help in case you are looking for contribution ideas, tho we are convinced that the best ideas will arise from using rocq-lsp in your own Rocq projects.

Both Flèche and rocq-lsp have a preliminary plugin system. The VSCode extension also exports and API so other extensions use its functionality to query and interact with Rocq documents.

• Ali Caglayan (co-coordinator)
• Emilio J. Gallego Arias (Inria Paris, co-coordinator)
• Shachar Itzhaky (Technion)

• Vincent Laporte (Inria)
• Ramkumar Ramachandra (Inria Paris)

The license for this project is LGPL 2.1 (or GPL 3+ as stated in the LGPL 2.1).

• This server forked from our previous LSP implementation for the Lambdapi proof assistant, written by Emilio J. Gallego Arias, Frédéric Blanqui, Rodolphe Lepigre, and others; the initial port to Rocq was done by Emilio J. Gallego Arias and Vicent Laporte.

• serlib, tests, and goal processing components (among others) come from SerAPI, and are under the same license. SerAPI was developed by Emilio J. Gallego Arias, Karl Palmskog, and Clément Pit-Claudel.

• Javascript support, and server-side package management were developed in the jsCoq project, by Shachar Itzhaky and Emilio J. Gallego Arias.

• Syntax files in editor/code are partially derived from VSCoq by Christian J. Bell, distributed under the terms of the MIT license (see ./editor/code/License-vscoq.text).

Work on this server has been made possible thanks to many discussions, inspirations, and sharing of ideas from colleagues. In particular, we'd like to thank Rudi Grinberg, Andrey Mokhov, Clément Pit-Claudel, and Makarius Wenzel for their help and advice. Gaëtan Gilbert contributed many key and challenging Rocq patches essential to rocq-lsp; we also thank Guillaume Munch-Maccagnoni for his memprof-limits library, which is essential to make rocq-lsp on the real world, as well for many advice w.r.t. OCaml.

rocq-lsp includes several components and tests from SerAPI, including serlib, goal display code, etc... Thanks to Karl Palmskog and all the SerAPI contributors.

As noted above, the original implementation was based on the Lambdapi LSP server, thanks Frédéric Blanqui, Rodolphe Lepigre and all Lambdapi contributors.