Installation¶

Prerequisites¶

You need four things before installing the toolkit. Run each command to check — if any fails, follow the install instruction below it.

Node.js¶

node --version    # Should show v18 or higher

If missing, install from nodejs.org or via your package manager (sudo apt install nodejs npm on Ubuntu/Debian).

Git¶

git --version

If missing: sudo apt install git (Linux) or download from git-scm.com.

Python 3¶

python3 --version

Required by the setup script for JSON parsing. If missing: sudo apt install python3 (Linux).

Claude Code CLI¶

claude --version

If missing, install and authenticate:

npm install -g @anthropic-ai/claude-code
claude login

Follow the browser prompts to sign in with your Anthropic account. You need an active Claude Pro, Max, Team, or Enterprise subscription.

Clone the Toolkit¶

git clone https://github.com/Visitrans/V025-claude-toolkit.git
cd V025-claude-toolkit

macOS¶

macOS is the primary development platform. The setup script works out of the box.

Install modes (SPEC-124)¶

The setup script offers three modes that differ in how they treat your existing ~/.claude/ files:

Mode	Toolkit symlinks	`~/.claude/CLAUDE.md`	`~/.claude/settings.json`	Backup before write
`--safe` (the default, and the only installing mode)	rewrite	preserved; appends `@~/.claude/toolkit/CLAUDE.defaults.md` import	merged: user keys preserved, toolkit keys (listed in `~/.claude/toolkit/managed-settings-keys.json`) refreshed	yes (best-effort)
`--update` (for nightly `git pull`)	rewrite	untouched	untouched	no

Which one should I run?

First-time install on a fresh machine: --safe. It will create ~/.claude/CLAUDE.md with the @-import line and you can edit your personal preferences above it.
First-time install but you already have personal ~/.claude/ customizations: --safe. The script appends the @-import and merges settings.json without losing your keys. Make sure to run --verify --pre-install first to see the plan.
After git pull of the toolkit: --update, or use /vt-t-toolkit-update from inside Claude Code. Both leave your personal files untouched.
You want the toolkit's default CLAUDE.md content and nothing of your own: there is no longer a flag for this — --overwrite was deleted (SPEC-169 FR-8) because it was the SPEC-124 regression. Move your ~/.claude/CLAUDE.md aside and run --safe; the installer will create a fresh one with the @-import. Doing it by hand means you decide what is lost, which is the point.

Preview the install (always safe)¶

scripts/setup.sh --verify --pre-install

Prints a table of every file the install would touch and what action it would take. Reports CONFLICT for any path the toolkit needs but where a user-owned file blocks it. Makes zero writes. Run this first whenever you're unsure.

Recommended install¶

scripts/setup.sh --safe

What this does:

Backup ~/.claude/ to ~/.claude.backup-<UTC>/ (excluding the existing toolkit symlink subtree).
Symlink ~/.claude/plugins/company-claude-toolkit to the toolkit root.
Deploy vt-c-* namespace symlinks for every skill, agent, command, and hook in the plugin manifests.
Append @~/.claude/toolkit/CLAUDE.defaults.md to your ~/.claude/CLAUDE.md (idempotent — re-running won't duplicate).
Merge toolkit-managed entries into your ~/.claude/settings.json (preserves your custom keys).
Run an integrity check.

The first time you start a Claude Code session after install, Claude Code will prompt you to approve the @-import directive — this is expected; click "Allow" once and the toolkit defaults will load automatically on all future sessions.

Migrating from a pre-SPEC-124 install¶

If you previously copied the toolkit standards directly into your ~/.claude/CLAUDE.md (the old layout), migrate to the import-based layout:

scripts/setup.sh --migrate-v2              # dry-run; reports planned changes
scripts/setup.sh --migrate-v2 --commit     # actually performs the migration

The migration extracts the inlined # VisiTrans - Claude Code Standards section into ~/.claude/toolkit/CLAUDE.defaults.md, replaces it in your CLAUDE.md with the @-import line, and backs up the original. Idempotent — running twice doesn't double-migrate.

Interactive setup¶

Run the setup manager without flags for a guided experience:

scripts/setup.sh

Selective plugin install¶

Install only specific plugins (required plugins are always included automatically):

scripts/setup.sh --safe --plugins vt-base

Staying up to date¶

Once installed, the session-start hook prints ℹ Toolkit updates available — run /vt-t-toolkit-update at most once per day when the toolkit repo's HEAD has moved past your last-applied SHA. Inside Claude Code, run:

/vt-t-toolkit-update

This invokes git pull --ff-only on the toolkit and setup.sh --update to refresh toolkit-owned files. If your install predates SPEC-193, --update leaves eight retired agent copies behind (it never deletes); --safe removes those its install record proves unchanged, and Manual cleanup: the eight retired agents covers the rest. Your ~/.claude/CLAUDE.md is never touched by --update, and your ~/.claude/settings.json is touched in exactly one place:

The one exception: enabledPlugins. --update adds the toolkit's own plugin entry — and never removes anything. Every other key in your settings.json, including every plugin you enabled, is left byte-identical, and that is enforced by a test rather than merely intended (scripts/tests/setup/39-update-repairs-the-enable-flag.sh, row B1).

Tidying up an entry retired by an older toolkit release is left to setup.sh --safe, which takes a backup of ~/.claude/ first. --update takes none, so it does not delete.

Without this, --update was a trap: it registered the toolkit's plugin in the plugin registries but left the enable flag pointing at a name deleted in 5.0.0, so the toolkit installed, reported success, and did not load. If you would rather manage that key yourself, set it to false — a deliberate false is preserved, with a warning, not overwritten.

One cleanup besides: the old _managed_by marker. Installs before BUG-307 wrote "_managed_by": "company-claude-toolkit" into each toolkit-owned value, and Claude Code reports the one under hooks as Unknown hook event "_managed_by" on every start. --update and --safe remove that marker and nothing else from the value, and record the key in ~/.claude/toolkit/managed-settings-keys.json instead. That file lists which top-level keys the toolkit owns and refreshes on --safe; delete a name from it to keep your own version of that key. If Claude Code offers to "Fix with Claude" the warning before you update, choose Continue instead: removing the marker by hand would make the toolkit stop refreshing its hooks. If that already happened, put "hooks" into the keys list of that file (create it as {"keys": ["hooks"]} if it does not exist) and run scripts/setup.sh --safe.

Run it from the checkout you installed from. Every ~/.claude link names that checkout by its absolute path. If --safe or --update runs from a different checkout (a second clone, a copy), it stops with REFUSED: this home is installed from another checkout and names both, instead of re-pointing every link into a tree that may be deleted next (BUG-322). If you really moved the toolkit, run it once from the new checkout with --move-install. If the old checkout is already gone, no flag is needed: re-pointing dangling links is the repair.

Windows¶

The toolkit's setup scripts are written in Bash and don't run natively on Windows. There are three approaches, ordered by recommendation.

Your setup	Recommended method	Jump to
Git for Windows installed	Git Bash (closest to macOS/Linux experience)	Option 1
PowerShell preferred, no WSL	PowerShell, running the same `setup.sh`	Option 2
WSL already set up	WSL (setup script works as-is)	Option 3
Not sure which to pick	Start with Git Bash	Option 1

Option 1: Git Bash (recommended)¶

Git for Windows ships with Git Bash. setup.sh runs there as it does on macOS and Linux, once three things are in place.

Before the first install

Windows Developer Mode is on (Settings > System > For developers). Git Bash can create real symlinks only with it, or from a shell run as Administrator. setup.sh asks Git Bash for real symlinks (it sets MSYS=winsymlinks:nativestrict unless you set a winsymlinks mode yourself). Without Developer Mode, the install stops with an error naming it. It no longer quietly copies files that git pull would never update.
python3 --version works in Git Bash (see Prerequisites). If it opens the Microsoft Store instead, Python is not installed.
Git checks out symlinks. During Git installation, check "Enable symbolic links". If Git is already installed:
```
git config --global core.symlinks true
```

You do not need rsync, which Git Bash lacks. setup.sh --safe then takes its safety snapshot of ~/.claude with a Python helper. The Restore: line it prints uses the same helper and restores exactly what the rsync version would.

# Open Git Bash
cd /c/path/to/V025-claude-toolkit
scripts/setup.sh --safe

Line endings. The repository pins LF line endings, so a fresh clone is correct whatever core.autocrlf says. A clone made before that change still has CRLF files in its working tree. setup.sh copes with them, but you can rewrite them once, in a clone with no local changes (this discards uncommitted edits):

git rm -r --cached -q . && git reset --hard -q HEAD

If the install stops with an error:

Message	Cause	Fix
`ln made a copy, not a symlink` or `could not link`	Developer Mode is off	Turn it on, then re-run `scripts/setup.sh --safe`
`... is a real directory or file, not a symlink` for `~/.claude/plugins/company-claude-toolkit`	An older run copied the whole toolkit there	Move that directory aside, then re-run
`rsync not found, and the python3 fallback ... is unavailable`	`python3` is missing	Install Python 3, then re-run

Copies of toolkit hooks and commands that an older run left behind are replaced automatically on the next run.

Option 2: PowerShell¶

PowerShell cannot run setup.sh itself, but Git for Windows — already a prerequisite — ships the bash.exe behind Git Bash. Run the same setup.sh through it, and you get exactly the Option 1 install: every plugin, agents included, plugin registration, git hooks, and --safe's merge instead of overwriting your CLAUDE.md and settings.json.

The requirements are Option 1's: Windows Developer Mode on, a working python3, and Git's "Enable symbolic links" — see Before the first install.

Set-Location C:\path\to\V025-claude-toolkit
& "$env:ProgramFiles\Git\bin\bash.exe" scripts/setup.sh --safe

If Git is not installed under Program Files, bash.exe sits in the bin folder of your Git installation — the folder above the cmd folder that holds git.exe ((Get-Command git).Source shows where that is).

Everything else works the same way, for example & "$env:ProgramFiles\Git\bin\bash.exe" scripts/setup.sh --verify.

Why the manual PowerShell steps are gone

This section used to walk through directory junctions and mklink by hand. Those steps linked only the vt-base plugin (73 of 241 entries), deployed no agents from any plugin, never registered the plugin, and copied CLAUDE.md and settings.json over yours (BUG-225). A second, hand-kept copy of the installer drifts; running the real one does not. If you installed that way, run the command above once — --safe keeps your own files and adds what was missing.

Option 3: WSL (Windows Subsystem for Linux)¶

If you run Claude Code from within WSL, the Bash setup script works as-is:

cd /mnt/c/path/to/V025-claude-toolkit
scripts/setup.sh --safe

WSL path mapping — read this before proceeding

WSL and Windows have separate home directories. Running setup.sh inside WSL deploys to /home/<user>/.claude/, but the VS Code Claude Code extension runs on the Windows host and looks at C:\Users\<user>\.claude\. These are two different locations — so the extension won't see your toolkit skills.

If you use the VS Code extension: run the setup targeting your Windows home instead:

HOME=/mnt/c/Users/<your-windows-username> scripts/setup.sh --safe

If you use Claude Code from the terminal: run claude in VS Code's integrated WSL terminal. The CLI finds ~/.claude/ in the WSL filesystem where the symlinks live.

See WSL + VS Code Troubleshooting below for details.

Linux¶

The setup script works identically to macOS:

scripts/setup.sh --safe

Ensure python3 is available (used for JSON parsing in the setup script).

Manual cleanup: the eight retired agents (SPEC-193)¶

This applies to every install made before SPEC-193, on macOS, Linux and Windows alike.

SPEC-193 stopped shipping eight standalone agent files. Removing them from the repository stops new installs from receiving them; it did not remove copies already on your machine, because these eight were installed as plain copies and the installer only removed symlinks.

Since BUG-220, scripts/setup.sh --safe removes such a copy itself — but only when its install record (~/.claude/toolkit/.installed-files) lists the file and the file is byte-for-byte what the toolkit wrote, and only after --safe has taken its snapshot. --update never deletes. A copy that was installed before the toolkit kept that record, or that you edited, stays: it may be yours. scripts/setup.sh --verify reports what is left with a [!!] line; the steps below remove it by hand. The same applies to output styles and skill docs the toolkit stops shipping.

Why remove them. No toolkit skill, command or orchestrator dispatches them. Claude Code still offers every file in ~/.claude/agents/ as an agent it can pick, though, and all eight can write files (three declare no tool list and so get every tool; most can also run shell commands). It may, for example, send a security request to the stale security-auditor instead of security-sentinel, which now holds the one piece of unique substance those eight carried. Delete them unless you use one deliberately.

Check before you delete. The eight names are generic, so a file with one of them may be yours: edited by you, written by you, or a symlink you set up. The commands below compare each file with the last copy the toolkit shipped (commit e18bdc5d), ignoring line endings — a Windows checkout stores these files with CRLF, and that alone is not an edit. The delete step removes only files whose content is that shipped copy. Run both from your toolkit checkout.

unmodified — the shipped copy; the delete step removes it.
DIFFERS — edited, empty, or from an older toolkit version. Left in place; look at it and delete it by hand if you do not want it.
SYMLINK — not a copy the toolkit made. Left in place.
CANNOT-COMPARE — the file could not be read, or this checkout does not contain e18bdc5d (a shallow clone, or the wrong directory). Left in place; nothing is ever deleted on this state. If you see it for every name, fix the checkout and run the check again.
A name you see no line for is not installed, or is already gone.

macOS, Linux, Git Bash and WSL¶

Under WSL an install can sit in either home, or in both: WSL keeps its own home (/home/<user>) apart from your Windows home. Option 3 above installs into the WSL home, or with HOME=/mnt/c/Users/<name> into the Windows home, and Option B of WSL + VS Code: Skills Not Showing installs into both. Run both commands below, and scripts/setup.sh --verify, once for every home you installed into: unprefixed for the WSL home, and with HOME=/mnt/c/Users/<name> in front of bash and of scripts/setup.sh for the Windows home. For the Windows home you can use the PowerShell variant from Windows instead.

Check:

bash <<'EOF'
for n in code-refactorer content-writer frontend-designer prd-writer project-task-planner security-auditor system-architect vibe-coding-coach; do
  f="$HOME/.claude/agents/$n.md"; b="e18bdc5d:configs/user-global/agents/$n.md"
  [ -e "$f" ] || continue
  if   [ -L "$f" ];                      then echo "SYMLINK: $n"
  elif [ ! -r "$f" ];                    then echo "CANNOT-COMPARE: $n"
  elif ! git cat-file -e "$b" 2>/dev/null; then echo "CANNOT-COMPARE: $n"
  elif diff -q <(tr -d '\r' < "$f") <(git cat-file blob "$b" | tr -d '\r') >/dev/null; then echo "unmodified: $n"
  else echo "DIFFERS: $n"; fi
done
EOF

Delete the unmodified copies:

bash <<'EOF'
for n in code-refactorer content-writer frontend-designer prd-writer project-task-planner security-auditor system-architect vibe-coding-coach; do
  f="$HOME/.claude/agents/$n.md"; b="e18bdc5d:configs/user-global/agents/$n.md"
  [ -f "$f" ] && [ ! -L "$f" ] && [ -r "$f" ] || continue
  git cat-file -e "$b" 2>/dev/null || continue
  diff -q <(tr -d '\r' < "$f") <(git cat-file blob "$b" | tr -d '\r') >/dev/null || continue
  rm -- "$f" && echo "deleted: $n"
done
exit 0
EOF

Windows PowerShell¶

Installs made with the manual PowerShell steps that Option 2 used to list never ran setup.sh, so this section is the only notice they get. (Option 2 now runs setup.sh, and its --verify reports these copies itself.)

Check:

$agents = Join-Path $env:USERPROFILE '.claude/agents'
'code-refactorer','content-writer','frontend-designer','prd-writer','project-task-planner','security-auditor','system-architect','vibe-coding-coach' | ForEach-Object {
  $name = $_
  $file = Join-Path $agents "$name.md"
  if (-not (Test-Path -LiteralPath $file)) { return }
  if ((Get-Item -LiteralPath $file).LinkType) { "SYMLINK: $name"; return }
  try { $live = [IO.File]::ReadAllText($file) } catch { "CANNOT-COMPARE: $name"; return }
  $shipped = (git cat-file blob "e18bdc5d:configs/user-global/agents/$name.md" | Out-String)
  if ($LASTEXITCODE -ne 0) { "CANNOT-COMPARE: $name"; return }
  if (($live -replace "`r","") -ceq ($shipped -replace "`r","")) { "unmodified: $name" } else { "DIFFERS: $name" }
}

Delete the unmodified copies:

$agents = Join-Path $env:USERPROFILE '.claude/agents'
'code-refactorer','content-writer','frontend-designer','prd-writer','project-task-planner','security-auditor','system-architect','vibe-coding-coach' | ForEach-Object {
  $name = $_
  $file = Join-Path $agents "$name.md"
  if (-not (Test-Path -LiteralPath $file)) { return }
  if ((Get-Item -LiteralPath $file).LinkType) { return }
  try { $live = [IO.File]::ReadAllText($file) } catch { return }
  $shipped = (git cat-file blob "e18bdc5d:configs/user-global/agents/$name.md" | Out-String)
  if ($LASTEXITCODE -ne 0) { return }
  if (($live -replace "`r","") -ceq ($shipped -replace "`r","")) { Remove-Item -LiteralPath $file; "deleted: $name" }
}

After Setup: Get Ready to Work¶

The setup script deployed toolkit files (skills, agents, hooks) into ~/.claude/. A few more steps before you're ready.

Step 1: Start a New Session¶

Skills, agents, and hooks are loaded when Claude Code starts a new session. If you had Claude Code running before you ran the setup script, you must start a fresh session for the toolkit to take effect.

Terminal: exit any running claude session (type /exit or press Ctrl+C), then start a new one with claude
VS Code: close the current Claude Code panel and open a new conversation (Cmd+N / Ctrl+N)

Step 2: Verify the Toolkit¶

scripts/setup.sh --verify

All checks should show [OK]. If you see [ERR], re-run scripts/setup.sh --safe (preserves your customizations) or scripts/setup.sh --safe (replaces user files; creates backup first).

Step 3: Test in a Project¶

Open a terminal, navigate to any Git repository (or create a new one), and launch Claude Code:

mkdir my-test-project && cd my-test-project && git init
claude

Inside the Claude Code session, type:

/vt-d-0-start

If the skill runs and shows the workflow overview, your setup is complete.

Optional: VS Code Extension¶

If you use Visual Studio Code, the Claude Code VS Code extension gives you a graphical chat panel integrated directly into your editor. This is optional — the toolkit works fully from the terminal too.

Install the Extension¶

Open VS Code
Press Ctrl+Shift+X (Linux/Windows) or Cmd+Shift+X (Mac) to open the Extensions view
Search for "Claude Code"
Install the one published by Anthropic (extension ID: anthropic.claude-code)
Restart VS Code

VS Code version

The extension requires VS Code 1.98.0 or higher. Check your version under Help > About.

When you first open the Claude Code panel, you'll be prompted to sign in with your Anthropic account. If you already authenticated via claude login in the terminal, the extension picks up your session automatically.

Open Claude Code in VS Code¶

Three ways to open it:

Spark icon: click the spark icon in the top-right corner of the editor (only visible when a file is open)
Status bar: click Claude Code in the bottom-right corner of the window
Command Palette: press Ctrl+Shift+P, type "Claude Code", select "Open in New Tab"

Using Toolkit Skills in VS Code¶

The extension uses the same ~/.claude/ configuration as the terminal. All toolkit skills, agents, and commands work the same way — type /vt-d-0-start in the chat panel to verify.

Terminal fallback

Some advanced Claude Code features (like certain slash commands) are only available in the CLI. You can always open VS Code's integrated terminal (Ctrl+`) and run claude there.

For full VS Code extension documentation, see Anthropic's VS Code guide.

WSL + VS Code: Skills Not Showing¶

If you ran setup.sh --safe inside WSL but the VS Code Claude Code extension doesn't show any toolkit skills (slash commands like /vt-d-0-start are missing), the problem is a path mismatch.

Why it happens: setup.sh deploys symlinks to ~/.claude/ — but inside WSL, ~ is /home/<user>/, while the VS Code extension runs on the Windows host and looks at C:\Users\<user>\.claude\. These are two completely different directories.

Fix — choose one:

Option A: Use the CLI in VS Code's terminal (recommended)Option B: Deploy to both locations

Open VS Code's integrated terminal (Ctrl+`), which connects to WSL, and run:

claude

The CLI finds ~/.claude/ in the WSL filesystem where your symlinks live. All skills work normally.

Run the setup script a second time, targeting the Windows home directory:

HOME=/mnt/c/Users/<your-windows-username> scripts/setup.sh --safe

This creates symlinks in the Windows ~/.claude/ so the VS Code extension can find them.

Symlink compatibility

Symlinks created inside WSL pointing to /mnt/c/... paths generally work. If skills still don't load, there is currently no copy-based fallback: scripts/install.sh was retired in 5.0.0 because it created no ~/.claude symlinks at all, pointed the plugin link at the wrong target, and overwrote your CLAUDE.md. Use Git Bash (Option 1) or PowerShell (Option 2) instead — both run the same setup.sh — and open an issue if neither works for your setup.

Installation Methods Compared¶

Method	Auto-syncs on `git pull`	Admin rights needed	Works with
`setup.sh --safe` (macOS/Linux)	Yes (symlinks)	No	macOS, Linux
Git Bash + symlinks (Windows)	Yes	Developer Mode or admin	Windows
PowerShell running `setup.sh` (Windows)	Yes	Developer Mode or admin	Windows
WSL (Windows)	Yes	No	WSL only
~~`scripts/install.sh` copy mode~~	Retired in 5.0.0 — never deployed any skills	—	—

What's Next¶

After installation:

Follow After Setup: Get Ready to Work above to verify and test
Optionally install the VS Code Extension
Read Your First Project for a guided walkthrough

--overwrite and its --full alias were deleted by SPEC-169 FR-8. They replaced the user's CLAUDE.md and settings.json wholesale, which is the regression SPEC-124 fixed and this spec found had returned. There is no flag that does that any more; --safe preserves your files and is the default.