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:
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.
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"