Skip to main content
command CX Codex

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

Install into Claude Code · Manually: put the files in place All methods and platforms ↓
.claude/commands/install-local.md
Open on GitHub

What 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-local to 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.md

Call it with /install-local. For all projects use ~/.claude/commands/

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

Similar slash commands

All slash commands for Agent setup: memory, context, orchestration →

From the same set83

The whole set →
speckit.companion.status speckit.companion.status — a command for Claude Code and Codex reads .spec-context.json and reports the active spec’s step, status, decisions, and next action. It is read-only. CX Codex +1 ★ 110repo stars speckit.plan speckit.plan runs an implementation planning workflow from a feature spec, generating research.md, data models, and API contracts. CX Codex GP ChatGPT ★ 110repo stars sandbox This command builds throwaway SpecKit sandboxes from recipes or lists available recipes and existing folders. It works with Claude Code and Codex. CX Codex +1 ★ 110repo stars release-qa release-qa is a Claude Code command that checks code before release. It compares the last version tag, runs automated and manual checks, and blocks /publish until all checks pass. CX Codex +1 ★ 110repo stars speckit.companion.living-drift speckit.companion.living-drift finds capability files that changed after their living spec was last committed. Use it to spot project changes that have not made it back into the spec. CX Codex +1 ★ 110repo stars speckit.companion.resume speckit.companion.resume is a command for Claude Code that resumes spec-driven development after a pause. It carries recorded decisions forward and starts the next pipeline step. CX Codex +1 ★ 110repo stars speckit.git.commit speckit.git.commit is a Claude Code command that stages and commits changes after Spec Kit commands, according to project configuration. CX Codex +1 ★ 110repo stars speckit-git-commit The speckit-git-commit skill stages and commits project changes around Spec Kit commands. Use it when Git history should be updated from the project’s Spec Kit settings. CX Codex +1 ★ 110repo stars

Project sponsors

Companies that keep this analytics open