Skip to content
Back to search

zsh-lexicon

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
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/carlwr--zsh-lexicon/badge.svg)](/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
  1. # zsh-lexicon
  2. > **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.
  3. 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.
  4. ## Packages
  5. | Package | Purpose | Lives in | Distribution |
  6. |---|---|---|---|
  7. | `@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 |
  8. | `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 |
  9. | `better-zsh` | VS Code extension: hovers, completions, semantic tokens, diagnostics. | `packages/vscode-better-zsh/` | VS Code Marketplace, Open VSX |
  10. | `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/> |
  11. Pick the package that matches your runtime; all wrap the same static zsh reference.
  12. ## Architecture in one paragraph
  13. 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.
  14. 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.
  15. ## Status and roadmap
  16. - Pre-release alphas are cut from this monorepo for CI/infra exercise.
  17. - A first non-alpha release bundle is planned; no date committed.
  18. ## Contributing
  19. - `docs/design.md` — architectural rationale
  20. - `AGENTS.md` — contributor conventions, testing, packaging, code style
  21. - `SECURITY.md` — security reporting
  22. ## License
  23. MIT. See `LICENSE`. Upstream zsh documentation notices: `THIRD_PARTY_NOTICES.md`.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.