install-local — Claude Code command: what it does, how to install
The install-local command for Claude Code builds and installs local speckit-companion VS Code and spec-kit extensions, bumping the patch version to trigger an editor reload banner.
MIT ★ 110 updated 2026-10-19
.claude/commands/install-local.mdWhat install-local does
The command automates local reinstallations for both parts of the speckit-companion repository: the VS Code extension (.vsix) and the spec-kit companion extension inside apps/speckit-extension/. To prevent VS Code from ignoring the package due to version caching, the script checks existing installs in ~/.vscode/extensions/ alongside package.json and increments the patch number above both.
After calculating the target version, it runs npm run package and forces installation with code --install-extension speckit-companion-{version}.vsix --force. It immediately cleans up the scratch version bump using git restore package.json package-lock.json so git history stays clean. The CLI flag code --command workbench.action.reloadWindow warns and no-ops on current builds, so you need to click the reload banner or trigger the reload command manually.
When apps/speckit-extension/extension.yml is present, it runs specify extension add ./apps/speckit-extension --dev --force to regenerate commands under .specify/extensions/companion/. If the specify executable is missing or lacks the extension subcommand from a stock PyPI release, it skips that stage and notes the reason in the completion report.
What it helps with
- Package and force-install local VS Code extension builds
- Bypass VS Code extension cache during local iterative testing
- Regenerate spec-kit agent commands in companion directories
- Prevent throwaway build version bumps from leaking into git commits
Example prompts for the agent
- Run
/install-localto update both extensions - Reinstall local VS Code and spec-kit builds via
/install-local - Package and deploy local speckit-companion changes to the editor
How to install install-local
Manually: put the files in place
.claude/commands/install-local.mdCall it with /install-local. For all projects use ~/.claude/commands/
Manually: put the files in place
~/.codex/prompts/install-local.mdCall it with /prompts:install-local. Codex marks this format deprecated in favour of skills
Manually: put the files in place
.github/prompts/install-local.prompt.mdManually: put the files in place
.gemini/commands/install-local.tomlGemini stores commands as TOML: the prompt text goes into the prompt field
Questions about install-local
How do I install install-local in Claude Code?
Place the command file at .claude/commands/install-local.md in your project repository.
Why does install-local bump the package version?
VS Code caches extensions by version number and does not show an update banner if the version is not strictly newer. The script checks all local installs in ~/.vscode/extensions/, picks the highest number, increments the patch, and restores package.json through git.
What happens if the specify CLI is not available?
The script finishes packaging and installing the VS Code extension, bypasses the spec-kit installation step, and explains the omission in the summary.
Source text
install-local.md · MIT
---
allowed-tools: Bash(npm version:*), Bash(npm run package:*), Bash(code --install-extension:*), Bash(code --command:*), Bash(specify extension:*)
description: Bump version and install both extensions locally (VS Code + spec-kit)
---
## Context
- Current version: !`node -p "require('./package.json').version"`
## Your task
This repo ships **two** extensions: the **VS Code extension** (`.vsix`) and the **spec-kit extension** (`apps/speckit-extension/` — the `/speckit.companion.*` commands + capture scripts). Reinstall both so local changes to either are picked up.
### 1. VS Code extension
1. Bump to one patch **above both the repo version AND the highest already-installed version**. Throwaway local installs accumulate in `~/.vscode/extensions/` at versions *above* the git baseline (each `/install-local` bump is restored in git but the installed `.vsix` stays), so a plain `npm version patch` from the baseline can produce a version ≤ what's installed → VS Code sees nothing newer and shows **no reload banner**. Compute a safe target instead:
```bash
INSTALLED=$(ls -d ~/.vscode/extensions/alfredoperez.speckit-companion-* 2>/dev/null \
| sed -E 's/.*-([0-9]+\.[0-9]+\.[0-9]+)$/\1/' | sort -V | tail -1)
REPO=$(node -p "require('./package.json').version")
BASE=$(printf '%s\n%s\n' "$INSTALLED" "$REPO" | sort -V | tail -1)
NEXT=$(node -e "const [a,b,c]=process.argv[1].split('.').map(Number);console.log([a,b,c+1].join('.'))" "$BASE")
npm version "$NEXT" --no-git-tag-version
```
2. Package the extension: `npm run package`
3. Install in VS Code: `code --install-extension speckit-companion-{version}.vsix --force`
4. Reload: the new-higher version makes VS Code surface a **"Restart Extensions / Reload"** banner. `code --command workbench.action.reloadWindow` is NOT a supported CLI flag in current builds (it warns and no-ops) — don't rely on it; tell the user to click the banner or run **Developer: Reload Window** if it doesn't appear.
**Important:** Never skip the version bump, and never bump *below* an installed version — VS Code caches by version number, so same-or-lower = no update and no banner. After installing, restore the throwaway bump in git (`git restore package.json package-lock.json`) so it never lands in a feature commit.
### 2. spec-kit extension (only if `apps/speckit-extension/extension.yml` exists)
5. Reinstall it so changed/new commands + scripts are re-emitted to the agent dirs:
`specify extension add ./apps/speckit-extension --dev --force`
- This regenerates `.specify/extensions/companion/` and the per-agent command emissions — all gitignored (source of truth is `apps/speckit-extension/`), so it produces no commit churn.
- If `specify` isn't installed or lacks the `extension` subcommand (stock PyPI build), skip with a note — see `apps/speckit-extension/docs/install.md`.
6. Confirm the commands registered: `specify extension add` prints the provided commands; verify any you just changed (e.g. `speckit.companion.status` / `speckit.companion.resume`) appear.
### 3. Report
Report the new VS Code version installed **and** whether the spec-kit extension was reinstalled (with the command count), or why it was skipped.
© alfredoperez · MIT · alfredoperez/speckit-companion