win-remote-toolkit/docs/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

This is a Windows remote administration toolkit designed for configuring and managing a specific Windows machine (PC-74269 at 192.168.88.112) from macOS/Linux systems. The toolkit provides automated scripts for system debloating, application installation, security configuration, and diagnostics.

Architecture Pattern

Dual-Script Architecture: Each functionality consists of two files:

• .ps1 - PowerShell script that runs on the target Windows machine
• .sh - macOS/Linux shell wrapper that uploads and executes the PowerShell script via SSH

Execution Flow:

1. Shell script uses sshpass + scp to upload PowerShell script to target
2. Executes PowerShell script remotely via SSH with powershell -NoProfile -ExecutionPolicy Bypass
3. Output is simultaneously displayed and logged to logs/ with timestamps

Key Commands

Prerequisites

# Install sshpass (required for all operations)
brew install hudochenkov/sshpass/sshpass

System Reconnaissance

./recon.sh                    # Complete system inventory (15 sections)
./verify-ai-removed.sh        # Verify Windows AI components removed
./verify-debloat.sh          # Verify Win11Debloat changes applied

Core System Configuration

./firewall-allow-ssh.sh       # Enable permanent SSH access
./activate-windows.sh         # Activate Windows via KMS
./remove-windows-ai.sh        # Remove Windows AI/Copilot components
./win11debloat.sh            # Remove bloatware and disable telemetry

Application Management

./install-thunderbird.sh     # Install Thunderbird email client
./setup-thunderbird.sh       # Configure IMAP/SMTP (edit thunderbird-config.json first)
./install-telegram.sh        # Install Telegram for target user

Diagnostics and Tools

./install-nirsoft.sh         # Install 16 NirSoft diagnostic tools
./nirsoft-dump.sh           # Collect and package system diagnostic data

Environment Variables

All scripts support connection overrides:

HOST=192.168.x.x USER_NAME=foo PASS='xxx' ./script.sh
MODE=Apply|Revert ./remove-windows-ai.sh    # AI removal modes
TARGET_USER=someone ./apply-ui-to-user.sh   # UI settings target

Configuration Files

win11debloat-config.json

Configuration for Win11Debloat operations. Uses schema with Tweaks, Deployment, and Apps sections. All tweak names must exist in Win11Debloat's Config/Features.json or they'll be rejected as "no importable data".

thunderbird-config.json

Email account configuration for Thunderbird setup. Supports IMAP/SMTP with various providers (Gmail, Outlook, iCloud, custom servers).

nirsoft-config.json

Defines the 16 NirSoft diagnostic tools to install, their download URLs, and installation paths.

Important Gotchas

1. PowerShell Encoding: Chinese Windows systems read UTF-8 scripts as CP950 without BOM. Scripts automatically add UTF-8 BOM to downloaded PowerShell files.

2. Firewall Persistence: Windows firewall profiles reset on reboot. The firewall script creates permanent rules and enables all profiles.

3. Thunderbird Profiles: Thunderbird 72+ uses [Install<HASH>] sections in profiles.ini, not Default=1. Setup script handles this correctly.

4. Win11Debloat Scope: Silent mode only applies UI settings to the executing user. Use apply-ui-to-user.sh to sync settings to other users.

5. Registry Paths: Many "common knowledge" registry paths for Windows settings are incorrect. Always verify actual paths used by tools.

Logging and Output

• All operations create timestamped logs in logs/ directory
• Format: {operation}-{host}-{timestamp}.log
• Diagnostic dumps saved to dumps/ directory as ZIP files
• Scripts provide real-time output while simultaneously logging

Remote Target Requirements

• Windows machine with OpenSSH Server enabled on port 22
• Default credentials: Admin@192.168.88.112 / P@ssw0rd!
• Target must be accessible from execution environment
• PowerShell 5.1 required (not PowerShell 7/Core)

Connection Methods

This toolkit supports two connection methods with different strengths:

SSH Method (Stable, for Large Scripts)

• ✅ Proven stability and reliability
• ✅ Handles large scripts (>3KB) without issues
• ✅ File upload capabilities via scp
• ✅ All existing .sh scripts use this method
• ⏱️ Execution time: ~22 seconds for recon
• Requires OpenSSH Server on target Windows machine

WinRM Method (Fast, for Quick Tasks)

• ⚡ 1.9x faster execution (12s vs 22s for recon)
• ✅ Native Windows remote management
• ✅ Better PowerShell integration and error handling
• ✅ Structured logging and real-time output
• ⚠️ Limited by command line length for large scripts
• Requires WinRM service configuration on target

# SSH method (reliable for large scripts)
./recon.sh

# WinRM method (faster for small tasks)  
python3 test_simple_winrm.py
python3 benchmark_ssh_vs_winrm.py

# Smart method selection
python3 smart_executor.py script.ps1

WinRM Setup and Usage

Prerequisites for WinRM

# Install Python WinRM library
pip3 install pywinrm

# Generate WinRM wrapper scripts
python3 generate_winrm_wrappers.py

WinRM Configuration Scripts

• check-winrm.sh - Verify WinRM configuration status
• enable-winrm.sh - Configure WinRM service for remote access
• fix-winrm.sh - Fix common WinRM connectivity issues
• test_winrm_python.py - Test WinRM connectivity with Python
• winrm_executor.py - Core WinRM execution framework

WinRM Target Requirements

• WinRM service running on port 5985 (HTTP) or 5986 (HTTPS)
• Enable-PSRemoting -Force executed on target
• Firewall rules enabled for Windows Remote Management
• For HTTP: AllowUnencrypted=true in WinRM configuration

Recommended Execution Order

For new machines, follow this sequence:

1. firewall-allow-ssh.sh - Ensure permanent SSH access
2. enable-winrm.sh - Configure WinRM (if using WinRM method)
3. recon.sh or recon-winrm.py - System inventory
4. activate-windows.sh - Windows activation
5. AI removal + reboot + verification
6. Win11Debloat + reboot + verification
7. Application installations
8. Account management (rename/hide should be done last)