====== Claudia - GUI for Claude Code on Windows ======

===== Introduction =====

**Claudia** is a powerful desktop GUI application for Claude Code, built by Asterisk. It transforms the command-line Claude Code experience into a beautiful, intuitive visual interface with advanced features like custom agents, session management, usage analytics, and more.

<note important>
Claudia is built with **Tauri 2** and requires Claude Code CLI to be installed first. This guide covers installation on Windows with common troubleshooting solutions.
</note>

===== What is Claudia? =====

Claudia serves as your **command center for Claude Code**, providing:

  * 🗂️ **Visual Project Management** - Browse Claude Code projects with a GUI
  * 🤖 **Custom AI Agents** - Create specialized agents with custom prompts
  * 📊 **Usage Analytics** - Track API costs and token usage
  * ⏰ **Session Timeline** - Create checkpoints and navigate session history
  * 🔌 **MCP Server Management** - Manage Model Context Protocol servers
  * 📝 **CLAUDE.md Editor** - Built-in markdown editor with live preview

===== System Requirements =====

==== Minimum Requirements ====
  * **OS:** Windows 10 version 2004+ or Windows 11
  * **RAM:** 4GB (8GB recommended)
  * **Storage:** 1GB free space
  * **Prerequisites:** Claude Code CLI installed and working

==== Required Tools ====
  * **Rust** (1.70.0 or later)
  * **Bun** (latest version)
  * **Git**
  * **Visual Studio Build Tools** (C++ support)
  * **WebView2** (usually pre-installed on Windows 11)

===== Prerequisites Installation =====

==== 1. Install Claude Code CLI ====

First, ensure Claude Code is installed and working. Follow the [[claude-code-windows|Claude Code Windows Installation Guide]].

<code bash>
# Verify Claude Code is installed
claude --version
</code>

==== 2. Install Rust ====

<code bash>
# Install Rust via rustup
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

# Or on Windows, download from: https://rustup.rs/
# After installation, restart terminal and verify:
rustc --version
cargo --version
</code>

==== 3. Install Bun ====

<code bash>
# Install Bun
curl -fsSL https://bun.sh/install | bash

# Or on Windows via PowerShell:
powershell -c "irm bun.sh/install.ps1 | iex"

# Verify installation
bun --version
</code>

==== 4. Install Visual Studio Build Tools ====

Download and install **Visual Studio Build Tools** with C++ support:
  * Go to https://visualstudio.microsoft.com/downloads/
  * Download "Build Tools for Visual Studio"
  * Install with "C++ build tools" workload

==== 5. Install Git ====

Download from https://git-scm.com/ or use winget:

<code bash>
winget install Git.Git
</code>

===== Installation Methods =====

==== Method 1: Pre-built Releases (Coming Soon) ====

<note>
Pre-built executables will be available soon from the GitHub releases page.
</note>

==== Method 2: Build from Source ====

=== Step 1: Clone Repository ===

<code bash>
git clone https://github.com/getAsterisk/claudia.git
cd claudia
</code>

=== Step 2: Install Dependencies ===

<code bash>
# Install frontend dependencies
bun install
</code>

=== Step 3: Build Application ===

<code bash>
# For development (with hot reload)
bun run tauri dev

# For production build
bun run tauri build
</code>

===== Common Build Issues and Solutions =====

==== Issue 1: Icon Problems ====

**Problem:** `error RC2175 : resource file icon.ico is not in 3.00 format`

**Solution:** Convert PNG to proper ICO format using ImageMagick:

<code bash>
# Install ImageMagick
winget install ImageMagick.ImageMagick

# Convert PNG to ICO
magick "src-tauri/icons/128x128.png" "src-tauri/icons/icon.ico"
</code>

==== Issue 2: Bundle Configuration ====

**Problem:** `Couldn't find a .ico icon` during bundling

**Solution:** Add icon path to `src-tauri/tauri.conf.json`:

<code json>
{
  "bundle": {
    "icon": [
      "icons/32x32.png",
      "icons/128x128.png",
      "icons/128x128@2x.png",
      "icons/icon.icns",
      "icons/icon.png",
      "icons/icon.ico"
    ]
  }
}
</code>

**Alternative:** Build without bundling:

<code bash>
# Build executable only (no installer)
bun run tauri build --no-bundle

# Or modify package.json
{
  "scripts": {
    "tauri": "tauri build --no-bundle"
  }
}
</code>

==== Issue 3: MSVC Not Found ====

**Problem:** `MSVC not found` error during build

**Solution:**
  - Install Visual Studio Build Tools with C++ support
  - Restart terminal after installation
  - Verify with: `cl.exe` (should be found in PATH)

==== Issue 4: Out of Memory ====

**Problem:** Build fails with memory errors

**Solution:**
<code bash>
# Build with fewer parallel jobs
cargo build -j 2

# Or set environment variable
set CARGO_BUILD_JOBS=2
bun run tauri build
</code>

==== Issue 5: WebView2 Missing ====

**Problem:** WebView2 runtime not found

**Solution:**
  - Download from: https://developer.microsoft.com/en-us/microsoft-edge/webview2/
  - Install "Evergreen Standalone Installer"
  - Restart system

===== Build Configuration Options =====

==== Development Build ====

<code bash>
# Fast compilation, larger binary, debug symbols
bun run tauri dev
</code>

==== Production Build ====

<code bash>
# Optimized build with installer
bun run tauri build

# Build without installer (executable only)
bun run tauri build --no-bundle

# Debug build (faster compilation)
bun run tauri build --debug
</code>

==== Build Artifacts ====

After successful build, find files in:
<code>
src-tauri/target/release/
├── claudia.exe              # Main executable
└── bundle/                  # Installers (if bundling enabled)
    ├── msi/                 # MSI installer
    └── nsis/                # NSIS installer
</code>

===== Running Claudia =====

==== First Launch ====

<code bash>
# Run the built executable
cd src-tauri/target/release
./claudia.exe

# Or from project root during development
bun run tauri dev
</code>

==== Initial Setup ====

1. **Welcome Screen:** Choose between CC Agents or CC Projects
2. **Auto-Detection:** Claudia automatically finds your `~/.claude` directory
3. **Project Import:** Existing Claude Code projects are imported automatically

===== Using Claudia =====

==== Project Management ====

<code>
CC Projects → Select Project → View Sessions → Resume or Start New
</code>

  * Browse all Claude Code projects visually
  * View session history with timestamps
  * Resume previous sessions or start new ones
  * Search projects and sessions quickly

==== Creating Custom Agents ====

<code>
CC Agents → Create Agent → Configure → Execute
</code>

1. **Design Agent:** Set name, icon, and system prompt
2. **Configure Model:** Choose Claude model (Sonnet, Opus, etc.)
3. **Set Permissions:** Configure file access and network permissions
4. **Execute Tasks:** Run agent on any project

==== Usage Analytics ====

<code>
Menu → Usage Dashboard → View Analytics
</code>

  * Monitor API costs by model and project
  * Track token usage over time
  * Export data for accounting
  * Visual charts and trends

==== MCP Server Management ====

<code>
Menu → MCP Manager → Add Server → Configure
</code>

  * Add Model Context Protocol servers
  * Import from Claude Desktop configuration
  * Test server connections
  * Manage server permissions

===== Upgrading Claudia =====

==== From Source ====

<code bash>
# Navigate to Claudia directory
cd claudia

# Pull latest changes
git pull origin main

# Update dependencies
bun install

# Rebuild application
bun run tauri build
</code>

==== Automated Update Script ====

<code bash>
#!/bin/bash
# Save as update-claudia.bat

echo "🔄 Updating Claudia..."

cd claudia
git pull origin main

echo "📦 Installing dependencies..."
bun install

echo "🔨 Building application..."
bun run tauri build --no-bundle

echo "✅ Update complete!"
echo "📍 Executable location: src-tauri/target/release/claudia.exe"
</code>

===== Advanced Configuration =====

==== Custom Build Settings ====

Create `.cargo/config.toml` in project root:

<code toml>
[build]
jobs = 2                    # Limit parallel jobs
target-dir = "target"       # Custom target directory

[target.x86_64-pc-windows-msvc]
rustflags = ["-C", "target-cpu=native"]  # Optimize for your CPU
</code>

==== Environment Variables ====

<code bash>
# Set before building
set RUST_LOG=debug                    # Enable debug logging
set TAURI_DEBUG=true                  # Enable Tauri debug mode
set CARGO_BUILD_JOBS=2                # Limit build parallelism
set RUSTFLAGS="-C target-cpu=native"  # CPU optimization
</code>

==== Tauri Configuration ====

Edit `src-tauri/tauri.conf.json` for custom settings:

<code json>
{
  "build": {
    "beforeBuildCommand": "bun run build",
    "beforeDevCommand": "bun run dev",
    "devPath": "http://localhost:5173",
    "distDir": "../dist"
  },
  "bundle": {
    "active": false,  // Disable bundling for faster builds
    "targets": ["nsis"],  // Use NSIS instead of WiX
    "windows": {
      "certificateThumbprint": null,
      "digestAlgorithm": "sha256",
      "timestampUrl": ""
    }
  }
}
</code>

===== Troubleshooting =====

==== Performance Issues ====

**Slow Build Times:**
<code bash>
# Use fewer CPU cores
set CARGO_BUILD_JOBS=2

# Use faster linker (install first)
cargo install -f cargo-binutils
rustup component add llvm-tools-preview
</code>

**High Memory Usage:**
<code bash>
# Increase virtual memory
# Control Panel → System → Advanced → Performance Settings → Virtual Memory
# Set to 8GB+ if you have sufficient disk space
</code>

==== Runtime Issues ====

**Application Won't Start:**
  - Verify WebView2 is installed
  - Check Windows Defender/antivirus exclusions
  - Run as Administrator (temporarily)
  - Check Windows Event Viewer for errors

**Claude Code Not Found:**
<code bash>
# Verify Claude Code installation
claude --version

# Check PATH
echo $PATH | grep -i claude

# Reinstall if necessary
npm install -g @anthropic-ai/claude-code
</code>

===== Development Setup =====

==== For Contributors ====

<code bash>
# Clone and setup development environment
git clone https://github.com/getAsterisk/claudia.git
cd claudia

# Install dependencies
bun install

# Start development server
bun run tauri dev

# Run tests
cd src-tauri && cargo test

# Format code
cd src-tauri && cargo fmt
</code>

==== Project Structure ====

<code>
claudia/
├── src/                   # React frontend
│   ├── components/        # UI components
│   ├── lib/               # API client & utilities
│   └── assets/            # Static assets
├── src-tauri/             # Rust backend
│   ├── src/
│   │   ├── commands/      # Tauri command handlers
│   │   ├── checkpoint/    # Timeline management
│   │   └── process/       # Process management
│   └── tests/             # Rust test suite
└── public/                # Public assets
</code>

===== Security Considerations =====

Claudia prioritizes security:

  * **Process Isolation:** Agents run in separate processes
  * **Permission Control:** Granular file and network access
  * **Local Storage:** All data stays on your machine
  * **No Telemetry:** No data collection or tracking
  * **Open Source:** Full code transparency

===== Useful Resources =====

  * [[https://github.com/getAsterisk/claudia|Official Claudia Repository]]
  * [[https://claudiacode.com|Claudia Website]]
  * [[https://docs.anthropic.com/en/release-notes/claude-code|Claude Code Documentation]]
  * [[https://tauri.app/|Tauri Framework]]
  * [[https://bun.sh/|Bun Package Manager]]
  * [[https://rust-lang.org/|Rust Programming Language]]

===== FAQ =====

==== Q: Do I need Claude Code CLI installed? ====
A: Yes, Claudia is a GUI wrapper for Claude Code CLI. Install Claude Code first.

==== Q: Can I use Claudia without building from source? ====
A: Pre-built releases will be available soon. Currently, building from source is required.

==== Q: Why does the build take so long? ====
A: Rust compilation is thorough but slow. Use `--debug` flag for faster development builds.

==== Q: Is Claudia free to use? ====
A: Yes, Claudia is open source (AGPL-3.0 license). You still need Claude API access.

==== Q: Can I contribute to Claudia? ====
A: Absolutely! Check the GitHub repository for contribution guidelines.