Claudia Windows Fix - Enable Claude Code on Windows via WSL

1-claudia-windows-fix.md

Claudia on Windows - Community Fix v4.2

A comprehensive guide to run Claudia GUI on Windows using WSL (Windows Subsystem for Linux) as a compatibility bridge.

🎯 Quick Overview

This fix enables Claudia to run on Windows by:

• Installing Claude CLI in WSL where it works natively
• Creating a Windows bridge script (claude.bat) that Claudia can communicate with
• Automatically detecting and adapting to different Claude CLI versions
• Providing pre-flight checks to ensure everything is configured correctly
• Handling Windows-specific build issues and icon problems

---

📋 Prerequisites

Before starting, ensure you have:

Component	Description	Installation	Notes
Windows 10/11	With latest updates	Windows Update
WSL 2	Windows Subsystem for Linux	wsl --install in Admin PowerShell	May already be installed
Ubuntu	Linux distribution for WSL	Microsoft Store	Default WSL distro
Node.js 18+	Required in WSL for Claude Code	Install via NodeSource in WSL	NOT Windows Node.js
Bun	JavaScript runtime (Windows)	bun.sh	Install in Windows, not WSL
Rust	For building Tauri	rustup.rs	Install in Windows
VS Build Tools	C++ compiler	Download	Select "Desktop development with C++"
Claudia	The app source code	Clone from GitHub
RAM	Minimum 4GB recommended	System requirement

---

🚀 Quick Start (For Experienced Users)

1. Download all files from this gist to your Claudia folder (.gist_v4.2)
2. Apply the main.rs patch from 2-claude_binary_patch.rs
3. Run 3-setup-windows.bat (installs Claude CLI in WSL and creates bridge)
4. Fix Windows compatibility issues in build scripts (see Step 5C)
5. Run bun install and bun run build in Windows CMD/PowerShell
6. Build with bun run tauri build in Windows CMD/PowerShell
7. Launch with 4-start-claudia.bat

Note: Follow the numbered order (2 → 3 → 4) for the setup files!

---

📖 Detailed Installation Guide

Step 0: Pre-Installation Checks

1. Check if components are already installed:

   # In Windows CMD/PowerShell:
   wsl --status
   bun --version
   rustc --version
   
   # In WSL:
   wsl bash -lc "claude --version"

2. If Claude Code is already installed in WSL, skip to Step 3.

Step 1: Install WSL and Ubuntu

1. Open PowerShell as Administrator

   # Install WSL with Ubuntu
   wsl --install

2. Restart your computer

3. Set up Ubuntu

   • Ubuntu will open after restart
   • Create username and password
   • Keep these credentials safe

Step 2: Install Node.js and Claude Code in WSL

⚠️ Important: Claude Code does NOT run directly on Windows. It must be installed inside WSL. ⚠️ Critical: Make sure you're using WSL Node.js, NOT Windows Node.js!

1. Open Ubuntu/WSL Terminal

2. Install Node.js 18+ via NodeSource (Recommended)

   # Update package list
   sudo apt update
   
   # Install curl if not present
   sudo apt install -y curl
   
   # Add NodeSource repository for Node.js 20.x
   curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
   
   # Install Node.js
   sudo apt install -y nodejs
   
   # Verify installation (should show v20.x or higher)
   node --version
   npm --version

3. Configure npm for Linux (Important for WSL)

   # Ensure npm uses Linux paths, not Windows
   npm config set prefix ~/.npm-global
   npm config set os linux
   
   # Add npm global bin to PATH
   echo 'export PATH="$HOME/.npm-global/bin:$PATH"' >> ~/.bashrc
   source ~/.bashrc

4. Install Claude Code

   # Install Claude Code globally (do NOT use sudo)
   npm install -g @anthropic-ai/claude-code
   
   # If you encounter platform detection errors, use:
   npm install -g @anthropic-ai/claude-code --force --no-os-check
   
   # Verify installation
   claude --version

5. Troubleshooting Node/npm in WSL

   If which npm shows /mnt/c/... (Windows path), you're using Windows npm:

   # Check if using Windows npm/node
   which npm
   which node
   
   # If pointing to /mnt/c/, remove Windows paths from WSL
   # Edit ~/.bashrc and remove any Windows PATH additions
   nano ~/.bashrc
   # Remove lines that add /mnt/c/... to PATH

Step 3: Install Required Software on Windows

1. Install Bun (in Windows, NOT WSL)

   • Visit https://bun.sh/
   • Run the PowerShell command (NOT as admin)
   • Verify: bun --version

2. Install Rust (in Windows, NOT WSL)

   • Visit https://rustup.rs/
   • Run the installer
   • Verify: rustc --version

3. Install Visual Studio Build Tools

   • Download from Microsoft
   • Select "Desktop development with C++"
   • Install and restart if needed

Step 4: Clone Claudia and Prepare Files

1. Clone Claudia (if not already done)

   git clone https://github.com/getAsterisk/claudia.git
   cd claudia

2. Create .gist_v4.2 folder and download fix files

   mkdir .gist_v4.2

   • Save all files from this gist into .gist_v4.2 folder:
     • 1-claudia-windows-fix.md (this file)
     • 2-claude_binary_patch.rs
     • 3-setup-windows.bat
     • 4-start-claudia.bat
     • 5-apply-patches.bat (NEW - automatic patching)
     • README.md

Step 5: Execute Setup in Correct Order

⚠️ Important: Follow the numbered order of the files! 💡 Why this order? Patching first ensures code compatibility before setting up the bridge.

Step 5.1: Apply Main.rs Patch (File #2)

1. Open src-tauri/src/main.rs
2. Add the version checking code from 2-claude_binary_patch.rs
3. Important: Keep existing imports and handlers, just add the version check code
4. This patch: Allows Claudia to accept multiple Claude CLI versions

Step 5.2: Run Setup Script (File #3)

1. Navigate to .gist_v4.2 folder and run:

   3-setup-windows.bat

2. This will:

   • ✅ Create the Windows bridge script (claude.bat)
   • ✅ Set up required directories
   • ✅ Configure PATH variables
   • ✅ Install/update Claude Code in WSL (if needed)

3. Important Note: The default path to npm must be followed.

   C:\Users\USERNAME\AppData\Roaming\npm\claude.bat
   

   If Claude Code is already installed, some errors are normal

Step 5.3: Apply Build Script Patches (Critical for Windows)

Choose ONE of these methods:

Method A: Automatic Patching (Easiest)

1. Run the patch script:

   cd .gist_v4.2
   5-apply-patches.bat

2. Done! The script applies all patches automatically.

Method B: Manual Patching (If automatic fails)

Only 3 simple search & replace operations needed:

1. File: scripts/fetch-and-build.js

   • Find: await runCommand('cp'
   • Replace entire line with:

   if (process.platform === 'win32') {
     await runCommand('robocopy', [srcPath, destPath, '/E', '/NFL', '/NDL', '/NJH', '/NJS', '/nc', '/ns', '/np']);
   } else {
     await runCommand('cp', ['-r', srcPath, destPath]);
   }

2. File: scripts/build-executables.js

   • Find: spawn(command, args, { stdio: 'inherit' }
   • Replace with: spawn(command, args, { stdio: 'inherit', shell: process.platform === 'win32' }

3. File: src-tauri/tauri.conf.json

   • Find: "icons/icon.png"
   • Add after it: , and new line "icons/icon.ico"

Step 5.4: Place Start Script (File #4)

1. Place the start script in main Claudia directory:

   copy .gist_v4.2\4-start-claudia.bat start-claudia.bat

2. Important: The script must be in the root Claudia folder, not in .gist_v4.2

Step 6: Handle Icon Issues

If you encounter icon format errors:

1. Create an icons backup folder:

   mkdir C:\Development\icons

2. Copy working icons (if provided) to src-tauri/icons/

3. Common icon error:

   • Error: resource file icon.ico is not in 3.00 format
   • Solution: Use properly formatted .ico files or icon generation tools

Step 7: Build Claudia

⚠️ CRITICAL: All build commands MUST be run in Windows CMD/PowerShell, NOT in WSL!

1. Install dependencies (in Windows CMD)

   bun install

2. Build frontend (in Windows CMD)

   bun run build

3. Build Tauri app (in Windows CMD)

   bun run tauri build

Step 8: Launch Claudia

1. Ensure start-claudia.bat is in the main Claudia folder

   • The file must be copied from .gist_v4.2\4-start-claudia.bat to the root directory
   • Final location: C:\path\to\claudia\start-claudia.bat (NOT in .gist_v4.2)

2. Always use start-claudia.bat to launch (not 4-start-claudia.bat)

   • Double-click the file or run from CMD
   • This script performs pre-flight checks
   • If any check fails, follow the on-screen instructions

---

🔧 How It Works

graph LR
    A[Claudia GUI] -->|calls| B[claude.bat]
    B -->|forwards to| C[WSL]
    C -->|executes| D[Claude CLI]
    D -->|returns| C
    C -->|returns| B
    B -->|returns| A

Loading

Key Components:

1. Claude CLI - Runs natively in WSL/Linux environment
2. claude.bat - Windows bridge script that:
   • Detects Claude CLI version automatically
   • Filters incompatible Windows arguments
   • Handles proper command escaping
3. Patched main.rs - Accepts multiple Claude versions
4. start-claudia.bat - Pre-flight checker and launcher

---

🐛 Troubleshooting

Common Issues and Solutions

Error	Cause	Solution
claude: command not found	CLI not installed in WSL	Run 2-setup-windows.bat again
claude.bat is not recognized	PATH not configured	Add C:\Users\USERNAME\AppData\Roaming\npm to system PATH
Failed to load settings	Missing ~/.claude directory	Run setup script or wsl mkdir -p ~/.claude
Version mismatch	Old patch version	Ensure you applied v4.2 patch
Wrong WSL distribution	Multiple WSL installs	Edit claude.bat, set WSL_DISTRO=Ubuntu
icon.ico not in 3.00 format	Invalid icon format	Use provided icons or regenerate
cp command not found	Unix commands in Windows	Apply build script patches
ENOENT: spawn bun	Missing shell option	Apply build-executables.js patch
Couldn't find a .ico icon	Missing icon in config	Add icon.ico to tauri.conf.json
pkg-config not found	Building in WSL instead of Windows	Build in Windows CMD, not WSL

Build Location Issues

NEVER run build commands in WSL! Common mistakes:

• ❌ Running cargo build in WSL terminal
• ❌ Running bun run build in WSL terminal
• ✅ Always use Windows CMD or PowerShell
• ✅ The start-claudia.bat script runs in the correct environment

Verify Installation

Run these commands to verify your setup:

# Check WSL
wsl --status

# Check Claude in WSL
wsl bash -lc "~/.npm-global/bin/claude --version"

# Check bridge
claude --version

# Check Bun
bun --version

# Check Rust
rustc --version

Manual PATH Configuration

If claude.bat is not found:

1. Press Win + X → System → Advanced system settings
2. Click "Environment Variables"
3. Under "User variables", select "Path" and click "Edit"
4. Add new entry: C:\Users\USERNAME\AppData\Roaming\npm (replace USERNAME with your actual username)
5. Click OK and restart Command Prompt

---

🆕 What's New in v4.2

Feature	v4.1	v4.2
Build Script Patches	Not mentioned	Detailed Windows fixes
Icon Handling	Basic	Comprehensive troubleshooting
Build Location	Unclear	Explicit Windows CMD requirement
Error Documentation	Basic	Extensive with solutions
Pre-installation Checks	None	Check existing installations
Script Modifications	Main.rs only	Multiple script patches

Key Improvements:

• Added Windows-specific build script patches
• Clear warnings about build location (Windows vs WSL)
• Comprehensive icon error handling
• Robocopy exit code handling
• Shell spawn fixes for Windows
• Better error messages and solutions

---

📝 Notes

• Development Mode: The start script runs Claudia in dev mode by default
• Production Build: For production, use bun run tauri build instead
• Updates: When updating Claudia, you may need to reapply patches
• Multiple WSL: If you have multiple distributions, edit claude.bat to specify which one
• Build Environment: ALWAYS build in Windows CMD/PowerShell, NEVER in WSL

---

🤝 Contributing

Found an issue or improvement? Please contribute:

1. Test the fix thoroughly
2. Document any new issues
3. Share your improvements with the community

---

📜 Credits

This fix was developed collaboratively by the Claudia community. Special thanks to all testers and contributors who helped refine this solution for Windows users.

Version: 4.2
Last Updated: January 2025
Compatibility: Windows 10/11, WSL2, Claudia 0.1.0+ Major Contributors: Community testers who identified build script issues, icon problems, and WSL/Windows confusion

2-claude_binary_patch.rs

// Prevents additional console window on Windows in release, DO NOT REMOVE!!
#![cfg_attr(not(debug_assertions), windows_subsystem = "windows")]

mod checkpoint;
mod claude_binary;
mod commands;
mod process;

use checkpoint::state::CheckpointState;
use commands::agents::{
    cleanup_finished_processes, create_agent, delete_agent, execute_agent, export_agent,
    export_agent_to_file, fetch_github_agent_content, fetch_github_agents, get_agent,
    get_agent_run, get_agent_run_with_real_time_metrics, get_claude_binary_path,
    get_live_session_output, get_session_output, get_session_status, import_agent,
    import_agent_from_file, import_agent_from_github, init_database, kill_agent_session,
    list_agent_runs, list_agent_runs_with_metrics, list_agents, list_claude_installations,
    list_running_sessions, set_claude_binary_path, stream_session_output, update_agent, AgentDb,
};
use commands::claude::{
    cancel_claude_execution, check_auto_checkpoint, check_claude_version, cleanup_old_checkpoints,
    clear_checkpoint_manager, continue_claude_code, create_checkpoint, execute_claude_code,
    find_claude_md_files, fork_from_checkpoint, get_checkpoint_diff, get_checkpoint_settings,
    get_checkpoint_state_stats, get_claude_session_output, get_claude_settings, get_project_sessions,
    get_recently_modified_files, get_session_timeline, get_system_prompt, list_checkpoints,
    list_directory_contents, list_projects, list_running_claude_sessions, load_session_history,
    open_new_session, read_claude_md_file, restore_checkpoint, resume_claude_code,
    save_claude_md_file, save_claude_settings, save_system_prompt, search_files,
    track_checkpoint_message, track_session_messages, update_checkpoint_settings,
    ClaudeProcessState,
};
use commands::mcp::{
    mcp_add, mcp_add_from_claude_desktop, mcp_add_json, mcp_get, mcp_get_server_status, mcp_list,
    mcp_read_project_config, mcp_remove, mcp_reset_project_choices, mcp_save_project_config,
    mcp_serve, mcp_test_connection,
};

use commands::usage::{
    get_session_stats, get_usage_by_date_range, get_usage_details, get_usage_stats,
};
use process::ProcessRegistryState;
use std::sync::Mutex;
use tauri::Manager;
use std::process::Command;

fn main() {
    // Initialize logger
    env_logger::init();

    tauri::Builder::default()
        .plugin(tauri_plugin_dialog::init())
        .setup(|app| {
            // Check Claude CLI version
            let claude_path = match std::env::var("CLAUDIE_CLI_PATH") {
                Ok(val) => val,
                Err(_) => "claude".to_string(),
            };

            let claude_version_output = Command::new(&claude_path)
                .arg("--version")
                .output();

            if let Ok(output) = claude_version_output {
                let claude_version = if output.status.success() {
                    String::from_utf8_lossy(&output.stdout).trim().to_string()
                } else {
                    "unknown".to_string()
                };

                // Accept multiple versions - check if it contains valid version pattern
                // This accepts any version that contains "Claude Code" or has a version number format
                let is_valid_version = claude_version.contains("Claude Code") || 
                                     claude_version.chars().any(|c| c.is_digit(10)) && claude_version.contains('.');
                
                if claude_version == "unknown" || !is_valid_version {
                    let window = app.get_webview_window("main");
                    if let Some(window) = window {
                        let message = format!(
                            "Claude CLI version is not compatible. Found version: {}, expected Claude Code x.x.x format. Please check your Claude CLI installation.",
                            claude_version
                        );
                        // Show a dialog to the user using tauri_plugin_dialog
                        tauri::async_runtime::spawn(async move {
                            use tauri_plugin_dialog::DialogExt;
                            window.dialog()
                                .message(message)
                                .title("Version Mismatch")
                                .blocking_show();
                        });
                    }
                }
            }

            // Initialize agents database
            let conn = init_database(&app.handle()).expect("Failed to initialize agents database");
            app.manage(AgentDb(Mutex::new(conn)));

            // Initialize checkpoint state
            let checkpoint_state = CheckpointState::new();

            // Set the Claude directory path
            if let Ok(claude_dir) = dirs::home_dir()
                .ok_or_else(|| "Could not find home directory")
                .and_then(|home| {
                    let claude_path = home.join(".claude");
                    claude_path
                        .canonicalize()
                        .map_err(|_| "Could not find ~/.claude directory")
                })
            {
                let state_clone = checkpoint_state.clone();
                tauri::async_runtime::spawn(async move {
                    state_clone.set_claude_dir(claude_dir).await;
                });
            }

            app.manage(checkpoint_state);

            // Initialize process registry
            app.manage(ProcessRegistryState::default());

            // Initialize Claude process state
            app.manage(ClaudeProcessState::default());

            Ok(())
        })
        .invoke_handler(tauri::generate_handler![
            list_projects,
            get_project_sessions,
            get_claude_settings,
            open_new_session,
            get_system_prompt,
            check_claude_version,
            save_system_prompt,
            save_claude_settings,
            find_claude_md_files,
            read_claude_md_file,
            save_claude_md_file,
            load_session_history,
            execute_claude_code,
            continue_claude_code,
            resume_claude_code,
            cancel_claude_execution,
            list_running_claude_sessions,
            get_claude_session_output,
            list_directory_contents,
            search_files,
            create_checkpoint,
            restore_checkpoint,
            list_checkpoints,
            fork_from_checkpoint,
            get_session_timeline,
            update_checkpoint_settings,
            get_checkpoint_diff,
            track_checkpoint_message,
            track_session_messages,
            check_auto_checkpoint,
            cleanup_old_checkpoints,
            get_checkpoint_settings,
            clear_checkpoint_manager,
            get_checkpoint_state_stats,
            get_recently_modified_files,
            list_agents,
            create_agent,
            update_agent,
            delete_agent,
            get_agent,
            execute_agent,
            list_agent_runs,
            get_agent_run,
            list_agent_runs_with_metrics,
            get_agent_run_with_real_time_metrics,
            list_running_sessions,
            kill_agent_session,
            get_session_status,
            cleanup_finished_processes,
            get_session_output,
            get_live_session_output,
            stream_session_output,
            get_claude_binary_path,
            set_claude_binary_path,
            list_claude_installations,
            export_agent,
            export_agent_to_file,
            import_agent,
            import_agent_from_file,
            fetch_github_agents,
            fetch_github_agent_content,
            import_agent_from_github,
            get_usage_stats,
            get_usage_by_date_range,
            get_usage_details,
            get_session_stats,
            mcp_add,
            mcp_list,
            mcp_get,
            mcp_remove,
            mcp_add_json,
            mcp_add_from_claude_desktop,
            mcp_serve,
            mcp_test_connection,
            mcp_reset_project_choices,
            mcp_get_server_status,
            mcp_read_project_config,
            mcp_save_project_config
        ])
        .run(tauri::generate_context!())
        .expect("error while running tauri application");
}

3-setup-windows.bat

@echo off
SETLOCAL

echo =================================================================
echo ==                                                             ==
echo ==         CLAUDIA FOR WINDOWS - SETUP SCRIPT V4.2             ==
echo ==                                                             ==
echo =================================================================
echo.
echo This script will configure the WSL bridge for Claudia.
echo It will:
echo  1. Create a 'claude.bat' wrapper in %APPDATA%\npm.
echo  2. Install/Update to the latest 'claude' CLI in WSL.
echo  3. Create the necessary '~/.claude' directory in WSL.
echo.
pause

REM === STEP 1: Create claude.bat bridge script ===
echo.
echo [INFO] Creating the 'claude.bat' bridge script in %APPDATA%\npm...

REM Ensure the npm directory exists
if not exist "%APPDATA%\npm" (
    mkdir "%APPDATA%\npm"
)

REM Create the claude.bat file with automatic version detection
(
echo @echo off
echo setlocal enabledelayedexpansion
echo.
echo REM This is a bridge script for Claudia on Windows.
echo REM It calls the 'claude' CLI within WSL and handles argument filtering.
echo.
echo REM --- Configuration ---
echo REM Enter the name of your WSL distribution here ^(e.g., "Ubuntu"^).
echo REM Leave empty to use the default distribution.
echo SET "WSL_DISTRO="
echo.
echo REM --- Argument Handling ---
echo.
echo REM ** IMPORTANT: Version check - get real version from WSL claude **
echo if /I "%%~1" == "--version" ^(
echo     REM Get the actual version from claude in WSL and format it correctly
echo     for /f "delims=" %%%%i in ^('wsl bash -lc "source ~/.bashrc ^&^& ~/.npm-global/bin/claude --version 2^>^/dev/null"'^) do set "CLAUDE_VERSION=%%%%i"
echo     
echo     REM If we got a version, output it in the format Claudia expects
echo     if defined CLAUDE_VERSION ^(
echo         echo ^^!CLAUDE_VERSION^^!
echo     ^) else ^(
echo         echo Claude Code 1.0.41
echo     ^)
echo     exit /b 0
echo ^)
echo.
echo REM Build command with all arguments EXCEPT --system-prompt and --no-color
echo set "CMD="
echo set "SKIP_NEXT=0"
echo.
echo :parse_args
echo if "%%~1"=="" goto :execute
echo.
echo if "^^!SKIP_NEXT^^!"=="1" ^(
echo     set "SKIP_NEXT=0"
echo     shift
echo     goto :parse_args
echo ^)
echo.
echo if "%%~1"=="--system-prompt" ^(
echo     set "SKIP_NEXT=1"
echo     shift
echo     goto :parse_args
echo ^)
echo.
echo if "%%~1"=="--no-color" ^(
echo     shift
echo     goto :parse_args
echo ^)
echo.
echo REM Add argument to command - handle quoted arguments properly
echo set "ARG=%%~1"
echo REM Escape quotes for bash
echo set "ARG=^^!ARG:"=\"^^!"
echo.
echo if defined CMD ^(
echo     set "CMD=^^!CMD^^! \"^^!ARG^^!\""
echo ^) else ^(
echo     set "CMD=\"^^!ARG^^!\""
echo ^)
echo.
echo shift
echo goto :parse_args
echo.
echo :execute
echo REM Execute with proper escaping using the correct path
echo if defined WSL_DISTRO ^(
echo     wsl -d "%%WSL_DISTRO%%" bash -lc "source ~/.bashrc ^&^& ~/.npm-global/bin/claude ^^!CMD^^!"
echo ^) else ^(
echo     wsl bash -lc "source ~/.bashrc ^&^& ~/.npm-global/bin/claude ^^!CMD^^!"
echo ^)
) > "%APPDATA%\npm\claude.bat"

if exist "%APPDATA%\npm\claude.bat" (
    echo [OK] 'claude.bat' created successfully.
) else (
    echo [ERROR] Failed to create 'claude.bat'.
    pause
    exit /b 1
)

REM === STEP 2: Install Claude CLI in WSL ===
echo.
echo =====================================================
echo    Installing/Updating Claude CLI in WSL...
echo =====================================================
echo.

REM Check if Node.js is installed in WSL
echo [INFO] Checking Node.js installation in WSL...
wsl bash -lc "node --version" >nul 2>nul
if %ERRORLEVEL% NEQ 0 (
    echo [ERROR] Node.js is not installed in WSL.
    echo.
    echo Please install Node.js in WSL first by running these commands in Ubuntu:
    echo   sudo apt update
    echo   curl -fsSL https://deb.nodesource.com/setup_20.x ^| sudo -E bash -
    echo   sudo apt install -y nodejs
    echo.
    pause
    exit /b 1
)

echo [INFO] Configuring npm for WSL...
wsl bash -lc "npm config set prefix ~/.npm-global && npm config set os linux"

echo [INFO] Installing @anthropic-ai/claude-code using npm...
wsl bash -lc "npm install -g @anthropic-ai/claude-code"

if %ERRORLEVEL% EQU 0 (
    echo [OK] Claude CLI installed successfully.
) else (
    echo [ERROR] Failed to install Claude CLI.
    echo Please check your internet connection and WSL installation.
    pause
    exit /b 1
)

REM === STEP 3: Create ~/.claude directory ===
echo.
echo [INFO] Creating ~/.claude configuration directory in WSL...
wsl bash -lc "mkdir -p ~/.claude"

if %ERRORLEVEL% EQU 0 (
    echo [OK] Configuration directory created.
) else (
    echo [WARNING] Could not create ~/.claude directory.
)

REM === STEP 4: Update PATH in .bashrc ===
echo.
echo [INFO] Updating PATH in WSL .bashrc...
wsl bash -lc "grep -q 'export PATH=\"\$HOME/.npm-global/bin:\$PATH\"' ~/.bashrc || echo 'export PATH=\"\$HOME/.npm-global/bin:\$PATH\"' >> ~/.bashrc"

if %ERRORLEVEL% EQU 0 (
    echo [OK] PATH updated in .bashrc.
) else (
    echo [WARNING] Could not update PATH in .bashrc.
)

echo.
echo =================================================================
echo ==                                                             ==
echo ==            SETUP COMPLETED SUCCESSFULLY!                    ==
echo ==                                                             ==
echo ==   You can now run Claudia using 'start-claudia.bat'        ==
echo ==                                                             ==
echo =================================================================
echo.
pause

4-start-claudia.bat

@echo off
SETLOCAL

REM =================================================================
REM ==                                                             ==
REM ==         CLAUDIA FOR WINDOWS - PRE-FLIGHT CHECK & LAUNCHER   ==
REM ==                           v4.2                               ==
REM =================================================================
echo.
echo  This script will verify your system configuration and then
echo  launch the Claudia application.
echo.
echo -----------------------------------------------------------------
echo  [1/5] Verifying System Prerequisites...
echo -----------------------------------------------------------------
echo.

REM --- CHECK 1: Is Bun installed? ---
echo Checking for 'bun'...
where bun >nul 2>nul
if %ERRORLEVEL% NEQ 0 (
    echo [ERROR] Bun is not installed or not in your PATH.
    echo.
    echo Please install Bun from https://bun.sh/ and ensure
    echo it is added to your system's PATH variable.
    echo.
    pause
    exit /b 1
)
echo  -^> [OK] Bun found.
echo.

REM --- CHECK 2: Is WSL installed? ---
echo Checking for 'WSL'...
wsl --status >nul 2>nul
if %ERRORLEVEL% NEQ 0 (
    echo [ERROR] Windows Subsystem for Linux ^(WSL^) is not installed.
    echo.
    echo Please open PowerShell as an Administrator and run:
    echo wsl --install
    echo Then, restart your computer.
    echo.
    pause
    exit /b 1
)
echo  -^> [OK] WSL is installed.
echo.

REM --- CHECK 3: Is the 'claude.bat' bridge script in PATH? ---
echo Checking for 'claude.bat' bridge...
where claude.bat >nul 2>nul
if %ERRORLEVEL% NEQ 0 (
    echo [ERROR] The 'claude.bat' bridge script was not found.
    echo.
    echo This means the setup script was not run correctly
    echo or %%APPDATA%%\npm is not in your system PATH.
    echo.
    echo Please run '2-setup-windows.bat' again.
    echo.
    pause
    exit /b 1
)
echo  -^> [OK] 'claude.bat' bridge found.
echo.

REM --- CHECK 4: Is the 'claude' CLI tool installed in WSL? ---
echo Checking for 'claude' CLI in WSL...
wsl test -f ~/.npm-global/bin/claude
if %ERRORLEVEL% NEQ 0 (
    echo [ERROR] The 'claude' CLI tool was not found in your WSL distribution.
    echo.
    echo Please ensure you have run the '2-setup-windows.bat' script
    echo to install the tool inside your WSL environment.
    echo.
    pause
    exit /b 1
)
echo  -^> [OK] 'claude' CLI found in WSL.
echo.

REM --- CHECK 5: Does the .claude config directory exist? ---
echo Checking for '~/.claude' config directory in WSL...
wsl test -d ~/.claude
if %ERRORLEVEL% NEQ 0 (
    echo [WARNING] The '~/.claude' directory is missing in WSL. Attempting to create it...
    wsl mkdir -p ~/.claude
    if %ERRORLEVEL% NEQ 0 (
        echo [ERROR] Could not create the directory. Please create it manually in WSL:
        echo mkdir -p ~/.claude
        pause
        exit /b 1
    )
    echo  -^> [OK] Directory created successfully.
) else (
    echo  -^> [OK] Config directory exists.
)
echo.

echo -----------------------------------------------------------------
echo  All checks passed! Launching Claudia...
echo -----------------------------------------------------------------
echo.

REM Change to the project directory (assumes the script is in the root)
cd /d "%~dp0"

echo Working Directory: %CD%
echo Frontend will be available at http://localhost:1420/
echo Press Ctrl+C in the console window to exit.
echo.

bun run tauri dev

pause

5-apply-patches.bat

@echo off
SETLOCAL EnableDelayedExpansion

echo =================================================================
echo ==                                                             ==
echo ==         CLAUDIA FOR WINDOWS - AUTO PATCH SCRIPT V4.2        ==
echo ==                                                             ==
echo =================================================================
echo.
echo This script will automatically apply all necessary Windows patches.
echo.
pause

REM Change to Claudia root directory (two levels up from .gist_v4.2)
cd /d "%~dp0\..\.."

REM === PATCH 1: scripts/fetch-and-build.js ===
echo.
echo [1/3] Patching scripts/fetch-and-build.js...

REM Backup original file
if not exist "scripts\fetch-and-build.js.backup" (
    copy "scripts\fetch-and-build.js" "scripts\fetch-and-build.js.backup" >nul
    echo       Created backup: fetch-and-build.js.backup
)

REM Create temporary patch file
(
echo const origRunCommand = runCommand;
echo runCommand = async function^(command, args = [], options = {}^) {
echo     return new Promise^(^(resolve, reject^) =^> {
echo         console.log^(`Running: ${command} ${args.join^(' '^)}`^);
echo         const child = spawn^(command, args, { 
echo             stdio: 'inherit',
echo             shell: process.platform === 'win32',
echo             ...options 
echo         }^);
echo         
echo         child.on^('error', ^(error^) =^> {
echo             console.error^(`Failed to execute command: ${error.message}`^);
echo             reject^(error^);
echo         }^);
echo         
echo         child.on^('exit', ^(code^) =^> {
echo             // Robocopy returns 0-7 as success codes
echo             const isRobocopy = command === 'robocopy' ^|^| command.endsWith^('robocopy.exe'^);
echo             const isSuccess = isRobocopy ? code ^>= 0 ^&^& code ^<= 7 : code === 0;
echo             
echo             if ^(isSuccess^) {
echo                 resolve^(^);
echo             } else {
echo                 reject^(new Error^(`Command failed with exit code ${code}`^)^);
echo             }
echo         }^);
echo     }^);
echo };
) > "%TEMP%\claudia_patch_runcommand.js"

REM Apply robocopy patch
powershell -Command "(Get-Content 'scripts\fetch-and-build.js') -replace 'await runCommand\(''cp''.*?\)', 'if (process.platform === ''win32'') { await runCommand(''robocopy'', [srcPath, destPath, ''/E'', ''/NFL'', ''/NDL'', ''/NJH'', ''/NJS'', ''/nc'', ''/ns'', ''/np'']); } else { await runCommand(''cp'', [''-r'', srcPath, destPath]); }' | Set-Content 'scripts\fetch-and-build.js.temp'"

if exist "scripts\fetch-and-build.js.temp" (
    move /Y "scripts\fetch-and-build.js.temp" "scripts\fetch-and-build.js" >nul
    echo       ✓ Applied robocopy patch
) else (
    echo       ⚠ Warning: Could not apply robocopy patch automatically
    echo       Please apply manually as described in the guide
)

REM === PATCH 2: scripts/build-executables.js ===
echo.
echo [2/3] Patching scripts/build-executables.js...

REM Backup original file
if not exist "scripts\build-executables.js.backup" (
    copy "scripts\build-executables.js" "scripts\build-executables.js.backup" >nul
    echo       Created backup: build-executables.js.backup
)

REM Apply shell support patch
powershell -Command "(Get-Content 'scripts\build-executables.js') -replace 'spawn\(command, args, \{ stdio: ''inherit'' \}\)', 'spawn(command, args, { stdio: ''inherit'', shell: process.platform === ''win32'' })' | Set-Content 'scripts\build-executables.js'"

echo       ✓ Applied shell support patch

REM === PATCH 3: src-tauri/tauri.conf.json ===
echo.
echo [3/3] Patching src-tauri/tauri.conf.json...

REM Backup original file
if not exist "src-tauri\tauri.conf.json.backup" (
    copy "src-tauri\tauri.conf.json" "src-tauri\tauri.conf.json.backup" >nul
    echo       Created backup: tauri.conf.json.backup
)

REM Check if icon.ico already exists in config
findstr /C:"icon.ico" "src-tauri\tauri.conf.json" >nul
if %ERRORLEVEL% NEQ 0 (
    REM Add icon.ico to the array
    powershell -Command "(Get-Content 'src-tauri\tauri.conf.json' -Raw) -replace '(\"icon\": \[[^\]]*)(\"icons/icon\.png\")', '$1$2,`n      \"icons/icon.ico\"' | Set-Content 'src-tauri\tauri.conf.json'"
    echo       ✓ Added icon.ico to configuration
) else (
    echo       ✓ icon.ico already in configuration
)

echo.
echo =================================================================
echo ==                   PATCHING COMPLETE!                        ==
echo =================================================================
echo.
echo ✓ All patches have been applied successfully!
echo ✓ Original files backed up with .backup extension
echo.
echo You can now continue with Step 6 of the installation guide.
echo.
pause

README.md

Claudia Windows Fix v4.2

This folder contains the Windows compatibility fix for Claudia GUI.

Files

1. 1-claudia-windows-fix.md - Complete installation guide (READ THIS FIRST!)
2. 2-claude_binary_patch.rs - Version compatibility patch for main.rs
3. 3-setup-windows.bat - Automated setup script for WSL bridge
4. 4-start-claudia.bat - Pre-flight check and launcher script
5. 5-apply-patches.bat - Automatic Windows patch applicator (NEW!)
6. patches/ folder - (Optional) Contains pre-patched files if automatic patching fails

Installation Order

⚠️ IMPORTANT: Follow the files in numerical order!

1. Read the complete guide in 1-claudia-windows-fix.md
2. Apply the patch from 2-claude_binary_patch.rs to your main.rs
3. Run 3-setup-windows.bat to set up the WSL bridge
4. Run 5-apply-patches.bat to automatically patch build scripts
5. Use 4-start-claudia.bat to launch Claudia

Note: Step 4 uses file #5 because it patches the build scripts after setup.

Why This Order?

The patch (file #2) is applied first because:

• It's a simple code change with no external dependencies
• It prepares Claudia to accept different Claude CLI versions
• The setup script (file #3) can then install any Claude version
• This prevents version mismatch errors during setup

What's New in v4.2

• Fixed installation order documentation
• Added comprehensive build script patches
• Improved icon error handling
• Clear build environment requirements (Windows CMD vs WSL)
• Better error messages and solutions
• Automatic patch script for easier installation
• Pre-patched files as backup option

Troubleshooting Patches

If 5-apply-patches.bat fails, you can use the pre-patched files:

# From Claudia root directory:
copy .gist_v4.2\patches\fetch-and-build.js scripts\
copy .gist_v4.2\patches\build-executables.js scripts\
copy .gist_v4.2\patches\tauri.conf.json src-tauri\

Quick Tips

• Always build in Windows CMD/PowerShell, NOT in WSL
• Check that all steps have been installed correctly before proceeding
• If you encounter icon errors, check the troubleshooting section
• Claude Code must be installed in WSL, not Windows
• The numbered files should be executed in order (2→3→4→5)
• The start script must be copied to the main Claudia folder

For detailed instructions, see 1-claudia-windows-fix.md

I cant get this to work, even with Claude's assistance. Im seeing:

`C:\DS\claudia>4-start-claudia.bat

This script will verify your system configuration and then
launch the Claudia application.

---

[1/5] Verifying System Prerequisites...

Checking for 'bun'...

Checking for 'WSL'...
is was unexpected at this time.`

I tried to do things related to your last troubleshoot but it isn't working. Thanks for trying to do this.

hi @Vaslo

Update 4.2 is live.
Now everything should work fine. Let me know if there are any problems.

Still not sure what to do. For example, what does this mean?

Add the version checking code from 2-claude_binary_patch.rs
Important: Keep existing imports and handlers, just add the version check code

Which lines are the version checking? Should I just copy the whole thing over or some portion? What's a handler? I don't know anything about Rust or Windows Batch files, I'm sorry. I suspect others will have the same issues.

Sorry I just found this, let me try this:
[https://github.com/Kirchlive/Claudia-For-Windows](https://github.com/[Kirchlive/Claudia-For-Windows](https://github.com/Kirchlive/Claudia-For-Windows))

Hi @Kirchlive, I have an issue when building

📋 Copying required files from Claude Code package...
Copying cli.js...
Copying yoga.wasm...
Copying vendor/ directory...
Running: robocopy claudia\temp-claude-package\package\vendor claudia\vendor /E /NFL /NDL /NJH /NJS /nc /ns /np

❌ Build process failed: Command failed with exit code 1
error: script "build:executables:current" exited with code 1
error: script "predev" exited with code 1
       Error The "beforeDevCommand" terminated with a non-zero status code.
error: script "tauri" exited with code 1
Press any key to continue . . .

but I changed the fetch-and-build.js file in the code

child.on("exit", (code) => {
 if (code === 0) {
 resolve();
 } else {
 reject(new Error(`Command failed with exit code ${code}`));
 }
 });

then update the code to

if (command === "robocopy" && code < 8) {
 resolve();
 } else if (code === 0) {
 resolve();
 } else {
 reject(new Error(`Command failed with exit code ${code}`));
 }

now it works fine

win10，It can be run in the AppData\Roaming\npm\claude.bat directory

i don't have a scripts folder and no fetch-and-build.js or build-executables.js files. However, i can build fine. Is this an issue?

other than no fetch-and-build.js or build-executables.js files, i can execute claudia via start-claudia.bat but app cannot find claude cli. Any idea why?

I went through these steps and still had some issues getting Claudia to work on my Windows 11 computer. Claude is executing successfully now, but I am seeing some odd behavior 1) it always tries to run 'claude-code' not claude 2) Every prompt I provide results in output from claude and tools in triplicate (Every response is shown 3x in the terminal). I am working through fixing those now and can create a PR once I have these issues sorted out. My 'best' working copy is here: https://github.com/randlee/claudia/tree/windows-fixes I will merge fixes from 1 & 2 once they seem stable. I will also test on Mac once those fixes are in place.

I am messaging primarily so others know there are fixes for the issues I am seeing. I can create a PR sooner to merge to a branch on your repo sooner if you prefer.

I'm getting an error about an invalid API key even though I have Max Subscription and have signed in via Claude Code CLI. When I try and run the /login command in Claudia, the application just spins and the chat prompt remains active but nothing happens (I can press the stop button which is how I assume the system is still working & the spinning circle icon).

Anyone have any similar problems that they've been able to solve?