circleci-yaml-lsp

CircleCI YAML LSP for Claude Code

A Claude Code plugin that wires up CircleCI's official circleci-yaml-language-server as a language server, so Claude gets real CircleCI config diagnostics — undefined job references, invalid/deprecated keys, unused jobs, orb problems, and more — directly in your editing loop on .circleci/config.yml.

It is zero-setup: the plugin downloads the right prebuilt server binary for your platform on first use (no Go toolchain required) and verifies it before running.

Scope: this is a CircleCI config language server, not a general-purpose YAML server. It only understands CircleCI's schema, so the plugin deliberately limits it to CircleCI config files (see Scope & limitations). For everyday YAML, use a general YAML server such as Red Hat's yaml-language-server.

---

Requirements

• Claude Code with plugin LSP support — v2.1.50 or newer recommended.
• Node.js on PATH — used to scope analysis to CircleCI config files. Claude Code installed via npm already has it. Without Node the plugin fails closed (see CIRCLECI_YAML_LSP_SCOPE).
• curl or wget, and network access on first run (to download the server binary).
• macOS or Linux (x86-64 or arm64). Windows works via WSL/Git Bash — see Windows.

Install

/plugin marketplace add rogerwintercircleci/circleci-yaml-lsp-for-claude
/plugin install circleci-yaml-lsp@circleci-lsp
/reload-plugins

That's it. The first time you edit a .circleci/config.yml, the plugin downloads the pinned CircleCI language-server binary (~13–20 MB, once per version) into a cache and starts validating.

Usage

Open a project that has a .circleci/config.yml and work as usual. Diagnostics surface when Claude edits the file (the server is push-based; a plain read does not trigger validation — make a trivial edit to force a check). The very first edit also downloads and starts the server (a few seconds), so diagnostics may land a moment later or on your next edit; once the server is warm, subsequent edits are instant. Claude sees the same diagnostics your editor would:

✘ [Line 12:7] Cannot find declaration for job "nonexistent-job"
⚠ [Line 4:3]  Job is unused

Beyond diagnostics, the server also provides go-to-definition / find-references across jobs, executors, commands and orbs, autocompletion, document symbols, and quick-fix code actions — Claude can use these through its LSP tooling.

How it works

Claude Code routes files to a language server purely by file extension, and the CircleCI server treats every document it receives as a CircleCI config. A naïve .yml → yaml mapping would therefore make it mis-validate every unrelated YAML file (docker-compose, Kubernetes, GitHub Actions, Helm …). To avoid that, the plugin ships a tiny launcher and a stdio proxy:

1. bin/circleci-yaml-lsp (launcher) detects your OS/arch, downloads the pinned server binary from CircleCI's GitHub Releases into a persistent cache, verifies its SHA-256 and byte size, and starts it.
2. bin/lsp-proxy.mjs (Node) sits between Claude Code and the server and only forwards document-sync messages for files that look like CircleCI configs — config-named *.yml/*.yaml under a .circleci/ directory. Everything else is left untouched, so unrelated YAML is never analyzed.

See docs/DESIGN.md for the full architecture and rationale.

Environment variables

All are optional. Set them in the environment Claude Code runs in (e.g. your shell profile).

Variable	Purpose
CIRCLECI_YAML_LSP_BINARY	Absolute path to a server binary to use instead of downloading. Use this for offline/air-gapped machines, corporate proxies, Windows, or a self-built binary.
CIRCLECI_YAML_LSP_NODE	Path to a node executable for the scoping proxy, if node isn't on PATH.
CIRCLECI_YAML_LSP_SCOPE	Set to off to disable scoping and validate all .yml/.yaml as CircleCI config (only useful if your repo is CircleCI-only).
CIRCLECI_YAML_LSP_SCOPE_PATTERN	Case-insensitive regex (matched against the file URI) overriding which files are in scope. Default matches config-named YAML under .circleci/.
CIRCLECI_YAML_LSP_TOKEN	A CircleCI API token. Enables resolution of private orbs, contexts, and self-hosted runners.
CIRCLECI_YAML_LSP_SELF_HOSTED_URL	Base URL of your CircleCI Server (self-hosted) installation.
CIRCLECI_YAML_LSP_DEBUG	Path to a file; logs proxy ⇄ server traffic for troubleshooting.

Example (offline / pre-provisioned binary):

export CIRCLECI_YAML_LSP_BINARY="$HOME/bin/linux-amd64-lsp"