A language server that provides IDE features for Cap'n Proto schema files, including go-to-definition and automatic recompilation.

Install the latest release binary:

curl -fsSL https://raw.githubusercontent.com/trickstar0301/capnp-ls/main/install.sh | sh

Or with wget:

wget -qO- https://raw.githubusercontent.com/trickstar0301/capnp-ls/main/install.sh | sh

By default, the installer downloads the capnp-v1 binary into $HOME/.local/bin. Override the release version, install directory, or linked Cap'n Proto channel with environment variables:

curl -fsSL https://raw.githubusercontent.com/trickstar0301/capnp-ls/main/install.sh \
  | CAPNP_LS_VERSION=v0.0.6 \
    CAPNP_LS_INSTALL_DIR="$HOME/.local/bin" \
    CAPNP_LS_CAPNP_VERSION=v2 \
    sh

The installer verifies the release asset against its .sha256 file before placing the executable on your PATH.

The Claude Code and Copilot plugins do not bundle the language server binary. Install capnp-ls first, then enable a plugin that starts:

{
  "command": "capnp-ls",
  "args": ["--stdio"]
}

Plugin marketplace definitions are maintained separately from this repository so one marketplace can host all trickstar0301 plugins.

• Supported OS: Linux, macOS arm64
• CMake
• Cap'n Proto C++ source tree
• A C++17-capable compiler for Cap'n Proto v1
• A C++23-capable compiler and standard library for Cap'n Proto v2

Build the language server against a Cap'n Proto C++ source checkout:

cmake -B build -DCAPNP_SOURCE_DIR=/path/to/capnproto/c++ .
cmake --build build

When building against Cap'n Proto v2, pass C++23 explicitly:

cmake -B build -DCMAKE_CXX_STANDARD=23 -DCAPNP_SOURCE_DIR=/path/to/capnproto/c++ .
cmake --build build

The linked compiler backend builds and links Cap'n Proto from the selected source tree. To support another Cap'n Proto version, build the same capnp-ls source with CAPNP_SOURCE_DIR pointing at that version's C++ source tree.

Supported Cap'n Proto source channels:

• v1 (built and tested against v1.4.0)
• v2

The executable for the language server is located at build/capnp-ls.

The language server reads .capnp-ls.json from the workspace root. Use importPaths for project-specific schema import directories and logLevel to set workspace logging. Supported log levels are error, warning, and info; the default is warning.

{
  "logLevel": "warning",
  "importPaths": [
    "path/to/schema/imports"
  ]
}

Release artifacts are versioned by the Cap'n Proto compatibility channel. Each artifact is published with a matching .sha256 file. The capnp-v1 artifacts are built and tested against Cap'n Proto v1.4.0. The capnp-v2 artifacts are built and tested against the Cap'n Proto v2 branch.

Linux x86_64 artifacts are built by CI:

• capnp-ls-linux-x86_64-capnp-v1
• capnp-ls-linux-x86_64-capnp-v2

macOS arm64 artifacts are built locally by a maintainer and uploaded manually to the GitHub release:

• capnp-ls-macos-arm64-capnp-v1
• capnp-ls-macos-arm64-capnp-v2

To build a macOS arm64 release artifact locally:

scripts/build-macos-arm64-release.sh v1 /path/to/capnproto-v1.4.0/c++
gh release upload \
  v0.0.6 \
  dist/capnp-ls-macos-arm64-capnp-v1 \
  dist/capnp-ls-macos-arm64-capnp-v1.sha256 \
  --clobber

Project-specific schema settings live in .capnp-ls.json at the workspace root. Commit this file with your schemas so every editor and agent uses the same Cap'n Proto import paths and log level:

{
  "logLevel": "warning",
  "importPaths": [
    "schemas/common",
    "vendor/capnp"
  ]
}

Fields:

• importPaths: An array of import paths for Cap'n Proto schemas.
  • Relative paths are resolved from the workspace root.
  • When multiple import paths are provided, they are searched in the specified order, similar to how the Cap'n Proto compiler operates.
• logLevel: The workspace log level for the language server.
  • Supported values are error, warning, and info.
  • The default is warning.

Clients should initialize the language server with either workspaceFolders or rootUri so capnp-ls can locate the workspace root. For Neovim and similar clients, use .capnp-ls.json or .git as the root marker.

When the client sends watched-file notifications for .capnp-ls.json, the server reloads the config without a restart. Invalid JSON keeps the last valid configuration; deleting .capnp-ls.json clears project import paths and restores the default warning log level.

LSP clients may still pass initialization options explicitly. When initializationOptions.capnp.importPaths is present, it takes precedence over .capnp-ls.json:

{
  "initializationOptions": {
    "capnp": {
      "importPaths": [
        "path/to/schema/imports"
      ]
    }
  }
}

For clients that support project-level LSP configuration, the equivalent initialization options are:

{
  "capnp": {
    "importPaths": [
      "schemas/common",
      "vendor/capnp"
    ]
  }
}

• Enables navigation to the definition of types, enums, and other symbols in Cap'n Proto schema files.

• Suggests the next field, method, or enumerant ordinal when typing @ inside a struct, interface, or enum body, based on the unsaved editor buffer.
• Members of union and group blocks are numbered within the enclosing struct's ordinal space, matching the Cap'n Proto schema language.
• Suggests declaration keywords (struct, interface, enum, const, using, annotation, and union where valid) when typing the first word of a statement.

• Automatically recompiles schemas when files are saved.

• Limited support for single workspace folders.

• Formatting feature

The samples directory contains a complete VSCode extension that demonstrates how to use this language server. For details about the extension, see samples/README.md.

1. Build the language server (see above)
2. Set up the extension:

   cd samples
   pnpm install
   pnpm compile

3. Launch the extension in debug mode:
   • Run "Launch Client" from the Run/Debug view

You can customize the sample workspace by modifying the second argument in the launch configuration's args array:

"args": [
    "--extensionDevelopmentPath=${workspaceRoot}/samples",
    "/absolute/path/to/your/workspace"  // Change this path
]