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.

Automated Setup (recommended)

scripts/setup.sh --full

This will:

1. Create a symlink from ~/.claude/plugins/company-claude-toolkit to the toolkit root
2. Deploy skill, hook, and command symlinks from plugin manifests
3. Copy CLAUDE.md, settings.json, and agent files from golden copies
4. Set script permissions
5. Run an integrity check

Interactive Setup

Run the setup manager without flags for a guided experience:

scripts/setup.sh

You'll be presented with options to do a full restore, select specific plugins, verify integrity, or show differences.

Selective Plugin Install

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

scripts/setup.sh --full --plugins core-standards

---

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 --full

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\core-standards"
$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 --full

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 --full

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 --full

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

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-c-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

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

VS Code version

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

Sign In

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-c-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 --full inside WSL but the VS Code Claude Code extension doesn't show any toolkit skills (slash commands like /vt-c-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 --full

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, but if skills still don't load, try the copy-based installer instead: HOME=/mnt/c/Users/<your-windows-username> scripts/install.sh and choose option 2 (copy).

---

Installation Methods Compared

Method	Auto-syncs on git pull	Admin rights needed	Works with
setup.sh --full (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	No — re-run after pull	No	All platforms

---

What's Next

After installation:

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