LSP Server

Shuck ships with a first-party Language Server Protocol server in the main CLI. Start it with shuck server and point your editor at that command over stdio.

That gives editor diagnostics from the current in-memory buffer instead of rerunning shuck check from scratch on every save.

Current scope

Shuck advertises a capability only after its request handler is implemented. The scope still varies by feature: some requests analyze only the active document, while workspace symbols and call hierarchy maintain bounded indexes across files.

Editor formatting uses the same parser-backed formatter as shuck format. Once shuck server is attached, use your editor's normal LSP format command or format-on-save integration.

Planned or deferred

• Language-server support for embedded shell regions, such as scripts inside GitHub Actions YAML, needs a separate position-remapping design.

Not currently planned

Shuck does not currently advertise semantic tokens, inlay hints, signature help, or notebook documents. These are not permanent prohibitions, but there is no accepted implementation design for them today.

Workspace pulls are enabled by default. Disable them through initialization options if an editor should only request diagnostics for open documents:

{
  "shuck": {
    "server": {
      "workspaceDiagnostics": {
        "enabled": false
      }
    }
  }
}

Shuck does not scan a workspace at startup. Each request performs a cancellable bounded discovery with defaults of 1,000 files, 10,000 visited entries, and 32 MiB of source text. Embedded host documents remain excluded until their diagnostic position mapping is available. Dynamic configuration can change the limits or disable subsequent workspace pulls.

This page is the user-facing support contract. The repository's design specs record the scope and decisions of individual implementation stages, so an older spec may describe a feature as a non-goal that a later spec subsequently added. If an advertised feature fails within the scope above, please file a bug. If the requested behavior is listed as deferred or unsupported, file a feature request instead.

Before you start

Make sure shuck is installed and available on your PATH:

shuck --version
shuck server

If shuck server starts successfully, your editor only needs to launch that command over stdio.

Shuck also resolves .shuck.toml or shuck.toml from the workspace and layers any LSP-provided Shuck settings on top when the client supports them.

Neovim

Neovim 0.11+ can use the built-in LSP client directly through vim.lsp:

vim.lsp.config("shuck", {
  cmd = { "shuck", "server" },
  filetypes = { "sh", "bash", "zsh", "ksh" },
  root_markers = { ".shuck.toml", "shuck.toml", ".git" },
})
 
vim.lsp.enable("shuck")

If your setup normalizes shell buffers to sh, leaving only sh in filetypes is fine too.

Vim

With vim-lsp, register Shuck in your .vimrc:

if executable('shuck')
    augroup shuck_lsp
        au!
        au User lsp_setup call lsp#register_server({
            \ 'name': 'shuck',
            \ 'cmd': {server_info->['shuck', 'server']},
            \ 'allowlist': ['sh'],
            \ })
    augroup END
endif

Most Vim setups detect shell scripts as sh. If yours uses dedicated bash, zsh, or ksh filetypes, add them to the allowlist as well.

Emacs

Eglot can launch shuck server for shell buffers by extending eglot-server-programs:

(with-eval-after-load 'eglot
  (add-to-list 'eglot-server-programs
               '(sh-mode . ("shuck" "server"))))

Then open a shell script and run M-x eglot.

If you use additional shell major modes, add them to the same entry or register a second one for those modes.

Zed

Zed currently routes language servers through extensions rather than letting you point a language directly at an arbitrary stdio command from settings alone. The practical route today is a small dev extension that launches shuck server for Shell Script buffers.

In extension.toml, register a shell language server:

id = "shuck"
name = "Shuck"
version = "0.0.1"
schema_version = 1
 
[language_servers.shuck]
name = "Shuck"
languages = ["Shell Script"]
 
[language_servers.shuck.language_ids]
"Shell Script" = "shellscript"

Then implement language_server_command in the extension's Rust entrypoint, following the Zed language extension docs:

fn language_server_command(
    &mut self,
    _language_server_id: &zed::LanguageServerId,
    _worktree: &zed::Worktree,
) -> Result<zed::Command> {
    Ok(zed::Command {
        command: "shuck".into(),
        args: vec!["server".into()],
        env: Default::default(),
    })
}

Once the extension is installed, prefer it for shell files in your Zed settings:

{
  "languages": {
    "Shell Script": {
      "language_servers": ["shuck", "..."]
    }
  }
}

Related docs

For project-wide lint configuration, see Configuration and Settings Reference.