Installation

Every channel that ships the mdsmith binary, the VS Code extension, or the Claude Code plugin — npm, PyPI, Homebrew, asdf, mise, a Flatpak bundle, the GitHub release, the Visual Studio Marketplace plus Open VSX, and the in-repository Claude Code marketplace — and which channel to pick for which workflow.

# Quick start (CLI only)

For a minimal setup, install the binary and run it. No config file, no kinds or schemas, no LSP, no editor plugin required:

go install github.com/jeduden/mdsmith/cmd/mdsmith@latest
mdsmith fix README.md
mdsmith check .

That works on a single-file README repo as well as on a 600-file docs monorepo. .mdsmith.yml is optional — the built-in defaults apply when no config is present. The rest of this guide covers the other channels, the editor extensions, and the supply-chain verification steps for regulated deployments.

# Channels

Each vX.Y.Z git tag ships the same Go binary through several channels. mdsmith version reports the same value on every channel because the version is stamped into the binary at build time. Pick one path:

A bare mise use mdsmith@latest needs a registry entry — “bare” meaning no backend prefix and no prior mise plugins install. The short asdf plugin add mdsmith needs one too. Neither registry entry exists yet. Everything else works today: the explicit-URL asdf install, Homebrew, and every backend-prefixed mise form below.

The binary ships for linux x86_64, linux aarch64, macOS x86_64, macOS arm64, and Windows amd64. Other targets require a Go toolchain.

# npm

npm install -g @mdsmith/cli
mdsmith version

The npm root is published as @mdsmith/cli (the unscoped mdsmith name on npm is owned by another project; we use the @mdsmith scope we own instead). The installed binary is still called mdsmith because the package’s bin field maps the command to a small Node.js shim.

The shim declares optionalDependencies for one platform sub-package per supported host (the canonical list lives in release-channels/npm.md ); npm installs only the one that matches process.platform and process.arch.

There is no postinstall hook, so npm install works in offline / air-gapped CI and on hosts that ban network calls during install.

npx @mdsmith/cli and pnpm dlx @mdsmith/cli work the same way without a permanent install.

# PyPI (pip / uvx / pipx)

pip install mdsmith
mdsmith version

uvx mdsmith check .

The PyPI release ships one platform-tagged wheel per supported host. Each wheel bundles the prebuilt binary under mdsmith/_bin/ and exposes an mdsmith console script that runs the binary in place: os.execv on POSIX (so signals and exit codes pass through unchanged) and subprocess.run on Windows, which has no execv semantics. pip, uv pip, pipx, uvx, and python -m mdsmith all work.

# asdf

The jeduden/asdf-mdsmith plugin installs the prebuilt binary for your platform and verifies it against the release checksums.txt:

asdf plugin add mdsmith https://github.com/jeduden/asdf-mdsmith.git
asdf install mdsmith latest
asdf set mdsmith latest
mdsmith version

Once the plugin is also listed in asdf-vm/asdf-plugins , the explicit URL becomes optional: asdf plugin add mdsmith resolves on its own.

# Homebrew

brew install jeduden/mdsmith/mdsmith
mdsmith version

This taps jeduden/homebrew-mdsmith and installs the prebuilt binary for macOS or Linux, on Intel or arm64, verified against the release checksums.txt. Upgrade with brew upgrade mdsmith. To tap once and then install by short name:

brew tap jeduden/mdsmith
brew install mdsmith

# mise

mise use github:jeduden/mdsmith
mdsmith version

mise installs mdsmith through any of its tool backends — all of these resolve today, none need a registry submission. The github backend above reads our release assets directly and auto-selects the build for your OS and architecture; pin a version with github:jeduden/mdsmith@0.13.2.

To reuse the same plugin the asdf install uses:

mise plugins install mdsmith https://github.com/jeduden/asdf-mdsmith.git
mise use mdsmith@latest

To build from source with the Go backend (needs a Go toolchain):

mise use go:github.com/jeduden/mdsmith/cmd/mdsmith

The ubi backend still works too, though mise has deprecated it for new registry entries:

mise use ubi:jeduden/mdsmith@latest

The one gap is a bare mise use mdsmith@latest: no backend prefix, and no prior mise plugins install like the asdf step above. That form needs an entry in mise’s curated registry (the registry/ dir in jdx/mise ), and no such entry exists yet. Use a backend-prefixed form, or install the plugin first as shown above.

# Flatpak

mdsmith ships an x86_64-only Flatpak bundle as an asset on the release page . The commands below download the latest mdsmith-x86_64.flatpak, install it, and run it:

curl -LO https://github.com/jeduden/mdsmith/releases/latest/download/mdsmith-x86_64.flatpak
flatpak install ./mdsmith-x86_64.flatpak
flatpak run io.github.jeduden.mdsmith check .

The first install also pulls the org.freedesktop.Platform 24.08 runtime from Flathub, if your host lacks it. Flatpak runs the linter in a sandbox. The bundle grants --filesystem=host, so mdsmith can read a repository anywhere on disk.

Invoke the linter through flatpak run io.github.jeduden.mdsmith. Or add the Flatpak exports directory to your PATH for a bare mdsmith command. aarch64 Linux hosts use npm, PyPI, or the GitHub release binary instead.

# GitHub release (direct download)

The release page attaches one binary per platform and a checksums.txt. Download, verify the SHA-256, and move the binary onto $PATH:

base="https://github.com/jeduden/mdsmith/releases/latest/download"
curl -L -o mdsmith-linux-amd64 "$base/mdsmith-linux-amd64"
curl -L -o checksums.txt       "$base/checksums.txt"
sha256sum -c <(grep mdsmith-linux-amd64 checksums.txt)
install -m 0755 mdsmith-linux-amd64 /usr/local/bin/mdsmith

Keep the binary saved under its release-asset name (mdsmith-linux-amd64) until verification is done — both sha256sum -c and gh attestation verify below match local files against that exact name. install copies the file rather than moving it, so the original remains for the verification steps.

For supply-chain-sensitive deployments, the release also ships a SLSA build provenance attestation per binary and a Sigstore signature on checksums.txt. Verify the provenance with gh:

gh attestation verify mdsmith-linux-amd64 \
  -R jeduden/mdsmith

Verify the checksums-file signature with cosign (requires cosign v3.0.0 or newer — earlier versions do not accept verify-blob --bundle; check yours with cosign version):

curl -L -o checksums.txt.bundle "$base/checksums.txt.bundle"
cosign verify-blob \
  --bundle checksums.txt.bundle \
  --certificate-identity-regexp \
    "^https://github.com/jeduden/mdsmith/.github/workflows/release.yml@" \
  --certificate-oidc-issuer \
    https://token.actions.githubusercontent.com \
  checksums.txt

Both verifications resolve through the workflow’s GitHub OIDC identity, so a forged binary or rewritten checksums file fails verification unless the attacker also controls release.yml on jeduden/mdsmith.

# Windows

Windows ships one binary: mdsmith-windows-amd64.exe. Scoop is the recommended install path; the direct download is the fallback for offline and air-gapped hosts.

Scoop. Install once; upgrades are automatic.

scoop bucket add mdsmith https://github.com/jeduden/scoop-mdsmith
scoop install mdsmith

Upgrade with scoop update mdsmith.

Direct download. No package manager required. There is one Windows asset, mdsmith-windows-amd64.exe — no <os>-<arch> to fill in.

Manual install — the path most people want. No PowerShell required; the steps are a browser download and the Settings UI. On the releases page , open the latest release and download mdsmith-windows-amd64.exe from its Assets.

To verify it before installing, also download checksums.txt from the same Assets. In the download folder, run certutil -hashfile mdsmith-windows-amd64.exe SHA256 (Command Prompt or PowerShell — certutil ships with Windows). Compare its hash to the mdsmith-windows-amd64.exe line in checksums.txt.

Then install it:

1. Make a folder to keep it in — for example %LOCALAPPDATA%\Programs\mdsmith — and move the file there. Rename it to mdsmith.exe so it runs as mdsmith.
2. Add that folder to your account PATH: open Edit environment variables for your account from the Start menu, edit Path, add the folder, and save.
3. Open a new terminal and run mdsmith version.

Scripted install (PowerShell). Download the binary and the checksums file:

$base = "https://github.com/jeduden/mdsmith/releases/latest/download"
Invoke-WebRequest "$base/mdsmith-windows-amd64.exe" -OutFile mdsmith.exe
Invoke-WebRequest "$base/checksums.txt" -OutFile checksums.txt

sha256sum -c is a POSIX tool. On Windows, compute the hash with Get-FileHash and compare it to the expected value pulled from checksums.txt:

$expected = (Select-String -Path checksums.txt -SimpleMatch `
  "mdsmith-windows-amd64.exe").Line.Split()[0].ToLower()
$actual = (Get-FileHash mdsmith.exe -Algorithm SHA256).Hash.ToLower()
if ($actual -eq $expected) { "checksum OK" } else { throw "checksum mismatch" }

A checksum OK line means the download is intact. Then move the binary into a directory on your user PATH so new shells find mdsmith:

$dest = "$env:LOCALAPPDATA\Programs\mdsmith"
New-Item -ItemType Directory -Force -Path $dest | Out-Null
Move-Item mdsmith.exe "$dest\mdsmith.exe" -Force
[Environment]::SetEnvironmentVariable(
  "Path",
  [Environment]::GetEnvironmentVariable("Path", "User") + ";$dest",
  "User")

Open a new terminal and run mdsmith version to confirm. The gh attestation verify and cosign verify-blob steps above work unchanged on Windows — both tools ship a Windows build, and attestation matches by content digest, so the local filename does not matter. Pass mdsmith.exe (or the verbatim mdsmith-windows-amd64.exe) as the file argument.

# CycloneDX SBOM

Every release also publishes a CycloneDX SBOM of the Go module the binaries were built from. The file is named mdsmith-sbom.cdx.json. The SHA-256 hash is in checksums.txt (it matches the mdsmith-* glob), so the same cosign signature transitively covers it.

curl -L -o mdsmith-sbom.cdx.json "$base/mdsmith-sbom.cdx.json"
sha256sum -c <(grep mdsmith-sbom.cdx.json checksums.txt)

Feed the SBOM into your dependency-scanner of choice (grype, osv-scanner, your SCA platform) for a component-and-license inventory of the binary.

This path is also the documented fallback if any of the package channels above is unavailable on a given day.

# VS Code extension

The extension talks to the Go binary over LSP. Install the binary by one of the channels above, then add the extension:

• Visual Studio Marketplace (stock VS Code, GitHub Codespaces, GitHub.dev): search for jeduden.mdsmith in the Extensions view, or run code --install-extension jeduden.mdsmith.
• Open VSX (VSCodium, Cursor, Theia, Gitpod): install from the marketplace UI, or run codium --install-extension jeduden.mdsmith.
• GitHub release: download the .vsix from the release page and run code --install-extension mdsmith-X.Y.Z.vsix.

The Marketplace, Open VSX, and GitHub-release .vsix have identical SHA-256 sums; they’re the same artifact uploaded to three places.

See VS Code Integration for the configuration surface (mdsmith.path, mdsmith.config, mdsmith.run, mdsmith.previewFix, and mdsmith.trace.server) and fix-on-save via editor.codeActionsOnSave.

# Obsidian plugin

The Obsidian plugin runs the engine as WebAssembly, so it needs no separate binary and works on desktop and mobile. Download mdsmith-obsidian-X.Y.Z.zip from the release page and unzip it into <vault>/.obsidian/plugins/mdsmith/. See mdsmith for Obsidian for the step-by-step install and the settings.

# Claude Code plugins

The Claude Code plugin is an optional editor surface. mdsmith itself never calls an LLM or any external service at runtime; the plugin only spawns mdsmith lsp as a local subprocess. See the telemetry policy for the full statement.

The mdsmith marketplace ships five user-facing plugins. Register once, then install whichever you need:

/plugin marketplace add jeduden/mdsmith

# mdsmith-lsp

Inline diagnostics, quick-fixes, and navigation (definition, references, symbol search, call-hierarchy) via mdsmith lsp. Required by most users.

/plugin install mdsmith-lsp@mdsmith
/reload-plugins

The plugin runs npx -y -p @mdsmith/cli mdsmith lsp. npx is bundled with npm, which standard Node.js installers ship and Claude Code already requires. First launch downloads @mdsmith/cli and the platform binary from npm; later launches reuse the cache. No global mdsmith install needed. To pin a version, edit the manifest args to @mdsmith/cli@<ver>.

If the /plugin Errors tab shows Executable not found in $PATH, npx is missing. Install Node 18 or later (20 LTS recommended) and run /reload-plugins.

See the Claude Code editor README for troubleshooting steps.

# mdsmith-skills

Three slash-command skills: /mdsmith-fix [path], /mdsmith-kinds [...], and /mdsmith-check [path]. Useful without the LSP plugin, or to run a targeted fix from the command palette.

/plugin install mdsmith-skills@mdsmith
/reload-plugins

Requires mdsmith on the $PATH Claude Code sees (or the mdsmith source tree under ./cmd/mdsmith).

# mdsmith-reviewer

A markdown-reviewer subagent that reviews Markdown PRs and drafts for structural drift. Loads rule-backed patterns from mdsmith help patterns at review time and checks three config-level patterns from a sibling patterns.md. Proposes config or directive snippets; no auto-fix.

/plugin install mdsmith-reviewer@mdsmith
/reload-plugins

Requires mdsmith on the $PATH.

# mdsmith-autofix

A PostToolUse hook that runs mdsmith fix on every .md file Claude Code edits. Keeps generated sections, whitespace, and table alignment in sync automatically.

/plugin install mdsmith-autofix@mdsmith
/reload-plugins

Requires mdsmith and jq on the $PATH. This plugin is opt-in: if you prefer to run /mdsmith-fix manually, skip it.

# mdsmith-audit

The markdown-audit skill. Audits an mdsmith repository for structural problems the built-in rules cannot see: hand-maintained indexes, similar files without a kind, missing .mdsmith.yml, and kinds without a path-pattern.

/plugin install mdsmith-audit@mdsmith
/reload-plugins