Back to search
zsh-lexicon
MCP serverGitHub
Structured zsh reference: typed TS library and JSON lexicon, plus a VS Code extension and CLI/MCP server built on it
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
Checked today
Badge for your README
Markdown
[](/listings/carlwr--zsh-lexicon)HTML
<a href="/listings/carlwr--zsh-lexicon"><img src="/api/listings/carlwr--zsh-lexicon/badge.svg" alt="findsafeskills safety rating" /></a>Install
i
What was scanned
The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.
README.md · README · 37 lines
- # zsh-lexicon
- > **Status: pre-release.** Published alphas exist to exercise CI and release workflows, not for use: they may not work, and their docs and links may be stale. The first non-alpha release has not yet been cut.
- A structured zsh reference — a typed TS library and its JSON lexicon, parsed from the zsh manual — plus the tools built on it: a VS Code extension, a CLI and MCP server, a browser search SPA.
- ## Packages
- | Package | Purpose | Lives in | Distribution |
- |---|---|---|---|
- | `@carlwr/zsh-lexicon` | Structured zsh reference: typed `Lexicon`, closed `DocCategory` taxonomy, `resolve`/`renderRecord`. Parsed from upstream zsh-5.9 Yodl source. | `packages/zsh-lexicon/` | npm, JSON release assets |
- | `zshref` | Rust crate: the single-file executable `zshref` CLI (JSON on stdout) and the `zshref-mcp` Model Context Protocol server over stdio for MCP-aware clients (Claude Code, Claude Desktop, Cursor, VS Code MCP, Zed, …). Offline; no Node, Python, or zsh runtime dependency. | `crates/zshref/` | crates.io, npm, GitHub release binaries; Homebrew planned |
- | `better-zsh` | VS Code extension: hovers, completions, semantic tokens, diagnostics. | `packages/vscode-better-zsh/` | VS Code Marketplace, Open VSX |
- | `zsh-lexicon-web` | Browser SPA: local semantic search over the same reference — embeddings computed in the browser; index built from `zsh-lexicon` at build time. | `packages/zsh-lexicon-web/` | static site: <https://carlwr.github.io/zsh-lexicon/> |
- Pick the package that matches your runtime; all wrap the same static zsh reference.
- ## Architecture in one paragraph
- Two layers, two adapters. `zsh-lexicon` (the knowledge layer) releases the reference as JSON; the Rust crate bakes it in at build time and owns the tool set (`zsh_docs`, `zsh_search`, `zsh_list`: name, JSON-Schema input and output, brief + long description, pure `(lexicon, input) → output` implementation). Each adapter — CLI, MCP — is thin transport glue over those definitions. The VS Code extension and the web SPA consume `zsh-lexicon` directly — the extension for its editor features, the SPA at build time for its search index.
- No shell execution, no subprocess, no network, no filesystem, no environment reads in the tool layer — structurally enforced by a scope-fence test. This is a product feature, not just policy.
- ## Status and roadmap
- - Pre-release alphas are cut from this monorepo for CI/infra exercise.
- - A first non-alpha release bundle is planned; no date committed.
- ## Contributing
- - `docs/design.md` — architectural rationale
- - `AGENTS.md` — contributor conventions, testing, packaging, code style
- - `SECURITY.md` — security reporting
- ## License
- MIT. See `LICENSE`. Upstream zsh documentation notices: `THIRD_PARTY_NOTICES.md`.
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.