Installation

Prerequisites

Before installing the toolkit, ensure you have:

• Claude Code CLI installed and authenticated
• Git installed
• Python 3 available (used by the setup script for JSON parsing)

Install Claude Code if you haven't already:

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

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.

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

WSL uses a separate filesystem from Windows. If Claude Code runs in Windows (not WSL), the symlinks created inside WSL won't be visible to it. Only use this option if you run Claude Code from within WSL.

---

Linux

The setup script works identically to macOS:

scripts/setup.sh --full

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

---

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. Run scripts/setup.sh --verify to confirm everything is healthy
2. Start Claude Code in a project and try /0-start to see the workflow
3. Read Your First Project for a guided walkthrough