Shelly Shell for VS Code
The extension's internal name is shelly-shell, matching the Rust package.
It recognizes .shy files and Shelly shebangs, starts shelly --language-server,
and provides semantic highlighting, syntax diagnostics, hovers, and completions.
The server uses the same tokenizer, parser, and semantic classifications as the
REPL. Your VS Code theme chooses the colors.
Bracket matching, coloring, guides, and auto-closing run inside VS Code. A small
extension grammar identifies comments, quoted strings, and multiline strings so
brackets in that text are excluded. Interpolation braces stay inside their
string. This works while typing, before the server responds, and with semantic
highlighting disabled or the server unavailable.
Use VS Code's editor.bracketPairColorization.enabled and
editor.guides.bracketPairs settings to control bracket display. These replace
the extension's former shelly-shell.bracketColorization setting.
Requires Shelly 0.5.3 or later and VS Code 1.140 or later.
The extension does not bundle Shelly; an older server executable cannot provide
these language features.
On Windows, run it in a WSL workspace with Shelly installed inside WSL. Linux
and macOS use their native Shelly executable.
Build and install locally
Build Shelly from the repository root with cargo build --locked. Then:
cd extensions/vscode
npm ci
npm test
npm run package
code --install-extension shelly-shell.vsix
Configure the executable in VS Code settings:
{
"shelly-shell.serverPath": "/absolute/path/to/shelly/target/debug/shelly"
}
The default is shelly on PATH. Absolute paths, ~/ paths, and paths relative
to the first workspace folder are supported. The executable must support
--language-server; an older installed shell will not. After changing the path,
run Shelly: Restart Language Server. The server is launched directly, without
another shell. In WSL, SSH, or a container, install the extension in that remote
environment and configure a path available there.
In a WSL window, use Preferences: Open Remote Settings (JSON) for the Linux
executable path. A newly installed extension may need Developer: Reload Window
to refresh its settings schema. Shelly: Restart Language Server starts a new
process after changing the path or rebuilding the binary. The extension checks
CLI help for --language-server before connecting, so older binaries produce a
specific error. The Shelly output channel records the selected executable and
startup failures. A release built before server support must be updated manually
or replaced in this setting with the current debug binary.
Packaging uses Node.js 22 or later. See
publishing instructions
for preparing a Marketplace release.
npm test runs Shelly assertions against the real TextMate and Oniguruma token
engines used by VS Code. Coverage includes comment/string exclusion, escapes,
multiline strings, incomplete input, Unicode positions, and bracket configuration. Build the repository's debug Shelly binary first.
For development, open shelly-shell.code-workspace, build Shelly, and press F5.
The workspace launches an Extension Development Host using the debug binary.
The Shelly output channel reports startup failures. Set
shelly-shell.trace.server to messages or verbose for protocol tracing.
Language features
Highlighting includes lexical tokens, parser context, declarations, native types
and methods, and understood references within the current document. For example,
let is an argument in echo let, and references inside interpolated strings
are classified without evaluating them. Member interpolation such as ${p.name}
colors the root as a variable and the member as a property; nested getters retain
method highlighting. Dynamic accessors such as $p.$name and ${p.$name} are
variable references, including assignment targets and unknown names. Interpolation
braces stay outside structural bracket coloring. These forms require a Shelly
binary built with member interpolation and dynamic member support; rebuild it and
run Shelly: Restart Language Server after updating the shell.
Private storage declarations, pub fields, named Type::new factories, and enum
default constructors use the shared parser. Getter/setter properties highlight as
properties using their advertised type, including computed properties and chained
methods such as $account.balance.trim. Raw access $self.::balance uses the
backing field's type; $self.::$name and ${self.::$name} highlight the accessor
as a variable. Constructors have no implicit $self. A nullable factory result
is left uncertain during editing instead of assuming a valid struct. Constructor
visibility, property signatures, and return validity are enforced when Shelly
compiles or runs the program; editor diagnostics currently cover syntax only.
These changes require a Shelly executable built from the updated language sources.
Point shelly-shell.serverPath at that build and run Shelly: Restart Language
Server. Updating the extension alone does not update its server executable.
Invalid syntax gets diagnostics;
unfinished input gets hints. Clearing or closing a document clears its diagnostics.
Hover a type to see its public storage fields, accessible properties, and methods
visible from the current module. Function and method hovers show their declared
parameter and return types. Property hovers distinguish read-only, write-only,
and writable properties. External binaries found on the server's PATH use the
placeholder signature fn command($args: any...): any.
Completion supports local variables and parameters, types, functions, imported
namespaces, methods, properties, raw access, and named constructor arguments.
Private constructors remain visible to their defining module and its children;
private storage is offered only inside the owning type's methods. Type:: offers
constructors, methods, and enum variants; Type. describes the type object.
Open, unsaved dependency buffers take precedence over disk contents. Workspace
.shy file changes invalidate the declaration cache.
Imports are indexed using local-first lookup, module.shy and module/init.shy,
SHELLY_MODULE_PATH, and the separate SHELLY_STD_PATH lookup for std:: modules.
The standard prelude is indexed automatically. Conditions that require executing
code are left uncertain; their declarations are not advertised. Indexing is
bounded to 64 modules, 1 MiB per module, and 8 MiB of source in total.
The server reads declarations and executable metadata. It never executes profiles,
RC files, prelude code, imported module code, getters, or external binaries.
Navigation, formatting, and type checking remain follow-up work. Unknown names do
not produce speculative type errors. Source analysis covers up to 1 MiB and
640,000 parser reads per document, with a diagnostic when a limit is reached.
Analysis results are cached by document version; stale updates are ignored.