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` (default for new users)	rewrite	preserved; appends `@~/.claude/toolkit/CLAUDE.defaults.md` import	merged: user keys preserved, toolkit keys (marked `_managed_by`) refreshed	yes (best-effort)
`--overwrite`	rewrite	replaced with toolkit stub	replaced wholesale from defaults	yes (mandatory; abort if fails)
`--update` (for nightly `git pull`)	rewrite	untouched	untouched	no
`--full`	alias for `--overwrite`

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 (no personal customizations): --overwrite. A backup of your current ~/.claude/ is taken first.

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. Your ~/.claude/CLAUDE.md and ~/.claude/settings.json are never touched by --update.

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 + directory junctions	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, which provides a Bash environment that supports symlinks.

Enable symlinks in Git for Windows

During Git installation, check "Enable symbolic links". If Git is already installed, you can enable this in the Git config:

git config --global core.symlinks true

You may also need to enable Developer Mode in Windows Settings > System > For developers, or run Git Bash as Administrator.

Once symlinks are enabled:

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

If symlink creation fails due to permissions, Git Bash will fall back to file copies, which means changes won't auto-sync on git pull. In that case, consider Option 2.

Option 2: PowerShell with Directory Junctions¶

Directory junctions are the native Windows equivalent of Unix directory symlinks. They work without admin rights and auto-sync with the repository.

Step 1: Create base directories¶

# Open PowerShell
New-Item -ItemType Directory -Force -Path "$env:USERPROFILE\.claude\plugins"
New-Item -ItemType Directory -Force -Path "$env:USERPROFILE\.claude\skills"
New-Item -ItemType Directory -Force -Path "$env:USERPROFILE\.claude\hooks"
New-Item -ItemType Directory -Force -Path "$env:USERPROFILE\.claude\commands"
New-Item -ItemType Directory -Force -Path "$env:USERPROFILE\.claude\agents"
New-Item -ItemType Directory -Force -Path "$env:USERPROFILE\.claude\output-styles"

Step 2: Create the plugin junction¶

$ToolkitRoot = "C:\path\to\V025-claude-toolkit"

# Create directory junction (no admin rights needed)
cmd /c mklink /J "$env:USERPROFILE\.claude\plugins\company-claude-toolkit" "$ToolkitRoot"

Step 3: Create skill symlinks from the manifest¶

$ToolkitRoot = "C:\path\to\V025-claude-toolkit"
$PluginDir = "$ToolkitRoot\plugins\vt-base"
$ClaudeDir = "$env:USERPROFILE\.claude"
$Manifest = "$PluginDir\.claude-plugin\skill-symlinks.manifest"

Get-Content $Manifest | ForEach-Object {
    $line = $_.Trim()
    if ($line -eq "" -or $line.StartsWith("#")) { return }

    $parts = $line -split '\s*->\s*'
    $linkName = $parts[0].Trim()
    $targetDir = $parts[1].Trim()
    $linkPath = "$ClaudeDir\skills\$linkName"
    $targetPath = "$PluginDir\skills\$targetDir"

    # Remove existing
    if (Test-Path $linkPath) { Remove-Item $linkPath -Force -Recurse }

    # Create junction
    cmd /c mklink /J "$linkPath" "$targetPath"
}

Step 4: Create hook and command symlinks¶

# Hook symlinks
$Manifest = "$PluginDir\.claude-plugin\hook-symlinks.manifest"
if (Test-Path $Manifest) {
    Get-Content $Manifest | ForEach-Object {
        $line = $_.Trim()
        if ($line -eq "" -or $line.StartsWith("#")) { return }

        $parts = $line -split '\s*->\s*'
        $linkName = $parts[0].Trim()
        $targetRel = $parts[1].Trim()
        $linkPath = "$ClaudeDir\hooks\$linkName"
        $targetPath = "$PluginDir\$targetRel"

        if (Test-Path $linkPath) { Remove-Item $linkPath -Force }

        # File symlinks require Developer Mode or admin
        cmd /c mklink "$linkPath" "$targetPath"
    }
}

# Command symlinks
$Manifest = "$PluginDir\.claude-plugin\command-symlinks.manifest"
if (Test-Path $Manifest) {
    Get-Content $Manifest | ForEach-Object {
        $line = $_.Trim()
        if ($line -eq "" -or $line.StartsWith("#")) { return }

        $parts = $line -split '\s*->\s*'
        $linkName = $parts[0].Trim()
        $targetRel = $parts[1].Trim()
        $linkPath = "$ClaudeDir\commands\$linkName"
        $targetPath = "$PluginDir\$targetRel"

        if (Test-Path $linkPath) { Remove-Item $linkPath -Force }
        cmd /c mklink "$linkPath" "$targetPath"
    }
}

Step 5: Copy config files¶

$ConfigDir = "$ToolkitRoot\configs\user-global"

Copy-Item "$ConfigDir\CLAUDE.md" "$ClaudeDir\CLAUDE.md" -Force
Copy-Item "$ConfigDir\settings.json" "$ClaudeDir\settings.json" -Force

# Agent files
if (Test-Path "$ConfigDir\agents") {
    Copy-Item "$ConfigDir\agents\*.md" "$ClaudeDir\agents\" -Force
}

# Output styles
if (Test-Path "$ConfigDir\output-styles") {
    Copy-Item "$ConfigDir\output-styles\*.md" "$ClaudeDir\output-styles\" -Force
}

Directory junctions vs symbolic links

Directory junctions (mklink /J) work for skill and plugin directories without admin rights
File symbolic links (mklink) for hooks and commands require either Developer Mode enabled or an admin prompt
If file symlinks fail, copy the files instead — you'll just need to re-copy after git pull

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).

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 --overwrite (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 with symlinks or PowerShell junctions (rows below) instead, 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 + junctions (Windows)	Yes (directories)	No for dirs, Developer Mode for files	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