azcomputerguru/claudetools

Fork 0

Files

Mike Swanson dc7174a53d Add cross-platform setup guide and context recovery for Mac/Windows/Linux

2026-01-20 16:10:28 -07:00

12 KiB

Raw Blame History

New Machine Setup - Complete ClaudeTools Clone (Cross-Platform)

This guide will help you set up a complete, identical ClaudeTools environment on a new machine (Windows or Mac).

Platform-Specific Notes:

Windows commands shown as: Windows> command
Mac/Linux commands shown as: Mac> command
When only one command shown, it works on both platforms

Prerequisites

Required Software (All Platforms):

Git (for cloning repository)
Python 3.9+ (for ClaudeTools API)
Node.js/npm (for MCP servers)
Claude Code CLI installed
SSH client (built-in on Mac/Linux, use Git Bash or OpenSSH on Windows)

Installation:

# Mac (using Homebrew)
Mac> brew install git python node

# Windows (using winget or Chocolatey)
Windows> winget install Git.Git Python.Python.3.11 OpenJS.NodeJS
# OR
Windows> choco install git python nodejs

Step 1: Clone Repository from Gitea

Choose Your Project Location:

# Windows
Windows> cd D:\
Windows> git clone ssh://azcomputerguru@172.16.3.20:2222/azcomputerguru/claudetools.git ClaudeTools
Windows> cd ClaudeTools

# Mac
Mac> cd ~/Projects  # or wherever you want it
Mac> git clone ssh://azcomputerguru@172.16.3.20:2222/azcomputerguru/claudetools.git ClaudeTools
Mac> cd ClaudeTools

Note: You'll need SSH access to the Gitea server (172.16.3.20:2222)

For This Guide:

Windows path: D:\ClaudeTools
Mac path: ~/Projects/ClaudeTools (adjust as needed)

Step 2: Set Up Python Virtual Environment

# Create virtual environment (both platforms)
python -m venv api/venv

# Activate virtual environment
Windows> api\venv\Scripts\activate
Mac> source api/venv/bin/activate

# Install Python dependencies (both platforms, once activated)
pip install -r requirements.txt

# Install development dependencies (if needed)
pip install -r requirements-dev.txt

Verify Activation:

# You should see (venv) in your prompt
# Check Python location:
Windows> where python
Mac> which python
# Should show path inside api/venv/

Step 3: Configure Environment Variables

Copy Environment Template:

Windows> copy .env.example .env
Mac> cp .env.example .env

Edit .env:

Windows> notepad .env
Mac> nano .env  # or vim .env, or use VS Code: code .env

Required Variables in .env:

# Database Configuration
DATABASE_URL=mysql+pymysql://claudetools:CT_e8fcd5a3952030a79ed6debae6c954ed@172.16.3.30:3306/claudetools?charset=utf8mb4

# JWT Configuration
JWT_SECRET_KEY=your-jwt-secret-key-here
JWT_ALGORITHM=HS256
JWT_ACCESS_TOKEN_EXPIRE_MINUTES=30

# Encryption Configuration
ENCRYPTION_KEY=your-fernet-encryption-key-here

# API Configuration
API_HOST=0.0.0.0
API_PORT=8000

Get actual values from credentials.md in the repository!

Step 4: Set Up MCP Servers

The .mcp.json file needs platform-specific paths.

Windows - Edit .mcp.json:

{
  "mcpServers": {
    "github": {
      "command": "cmd",
      "args": ["/c", "npx", "-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": ""
      }
    },
    "filesystem": {
      "command": "cmd",
      "args": ["/c", "npx", "-y", "@modelcontextprotocol/server-filesystem", "D:\\ClaudeTools"]
    },
    "sequential-thinking": {
      "command": "cmd",
      "args": ["/c", "npx", "-y", "@modelcontextprotocol/server-sequential-thinking"]
    }
  }
}

Mac - Edit .mcp.json:

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": ""
      }
    },
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/yourusername/Projects/ClaudeTools"]
    },
    "sequential-thinking": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-sequential-thinking"]
    }
  }
}

Important for Mac: Update the filesystem path to match your actual ClaudeTools location!

Verify npm is installed:

npm --version
# Should show version number (18.0.0 or higher)

MCP servers will auto-install on first use via npx

Step 5: Test Database Connection

# Activate venv if not already active
Windows> api\venv\Scripts\activate
Mac> source api/venv/bin/activate

# Test database connection (both platforms)
python test_db_connection.py

Expected output: Connection successful to 172.16.3.30:3306/claudetools

Note: Ensure you have network access to 172.16.3.30:3306 (MariaDB server)

Step 6: Run Database Migrations (if needed)

# Check current migration status (both platforms)
alembic current

# Upgrade to latest (if needed)
alembic upgrade head

Step 7: Test API Server

# Activate venv first
Windows> api\venv\Scripts\activate
Mac> source api/venv/bin/activate

# Start the API server (both platforms)
python -m api.main

# Or use uvicorn directly
uvicorn api.main:app --reload --host 0.0.0.0 --port 8000

Test endpoints:

Local: http://localhost:8000/api/docs
Network: http://172.16.3.30:8001/api/docs (if running on RMM server)

Stop Server: Press Ctrl+C

Step 8: Configure SSH Keys for Infrastructure

Generate SSH Key (if you don't have one):

# Both platforms
ssh-keygen -t ed25519 -C "your_email@example.com"
# Press Enter to accept default location
# Enter passphrase (optional but recommended)

For AD2 (Windows Server):

Host: 192.168.0.6
User: INTRANET\sysadmin
Password: See credentials.md
Note: Password authentication (SSH keys not typically used with Windows domain accounts)

For D2TESTNAS (Linux NAS):

# Copy your SSH key to the NAS
ssh-copy-id root@192.168.0.9

# Test connection (both platforms)
ssh root@192.168.0.9 "ls /data/test/COMMON/ProdSW/"

For Gitea Server:

# Test Gitea SSH access (both platforms)
ssh -p 2222 azcomputerguru@172.16.3.20

# Should show Gitea greeting, then disconnect

Mac-Specific SSH Notes:

Keys stored in: ~/.ssh/
Config file: ~/.ssh/config
Permissions must be correct: chmod 600 ~/.ssh/id_ed25519

Windows-Specific SSH Notes:

Keys stored in: C:\Users\YourName\.ssh\
Use Git Bash or PowerShell for SSH commands
OpenSSH should be installed (Windows 10+)

Step 9: Update File Paths in Context Recovery Prompt

The context recovery prompt has Windows paths. Update them for your platform:

For Mac, change:

D:\ClaudeTools → /Users/yourusername/Projects/ClaudeTools
Or use relative paths (just PROJECT_ORGANIZATION.md instead of full path)

Context Recovery Prompt (Platform-Agnostic Version):

See CONTEXT_RECOVERY_PROMPT.md in the repository. When pasting to Claude Code, use paths appropriate for your platform:

Working directory: D:\ClaudeTools          (Windows)
Working directory: ~/Projects/ClaudeTools   (Mac)

Step 10: Restore Full Context in Claude Code

Open Claude Code in your ClaudeTools directory:

Windows> cd D:\ClaudeTools
Mac> cd ~/Projects/ClaudeTools

Then paste the context recovery prompt from CONTEXT_RECOVERY_PROMPT.md

The prompt will tell Claude to read all necessary files and restore full context including:

Project states (DOS, API, clients)
Credentials and infrastructure access
Organization system
MCP servers, commands, and skills

Step 11: Verify Everything Works

Test Checklist:

Python venv activates
Database connection successful (172.16.3.30:3306)
API server starts and responds (http://localhost:8000/api/docs)
SSH to D2TESTNAS works (ssh root@192.168.0.9)
SSH to Gitea works (ssh -p 2222 azcomputerguru@172.16.3.20)
Claude Code loads in ClaudeTools directory
MCP servers load (check Claude Code startup messages)
Context recovery prompt works
Available commands show: /save, /context, /checkpoint, etc.
Git push to Gitea works

Platform-Specific Quick Reference

Windows

Start API:

cd D:\ClaudeTools
api\venv\Scripts\activate
python -m api.main

File Paths:

Project root: D:\ClaudeTools
Venv: D:\ClaudeTools\api\venv
Credentials: D:\ClaudeTools\credentials.md

Deploy to DOS:

scp file.BAT root@192.168.0.9:/data/test/COMMON/ProdSW/

Mac

Start API:

cd ~/Projects/ClaudeTools
source api/venv/bin/activate
python -m api.main

File Paths:

Project root: ~/Projects/ClaudeTools
Venv: ~/Projects/ClaudeTools/api/venv
Credentials: ~/Projects/ClaudeTools/credentials.md

Deploy to DOS:

scp file.BAT root@192.168.0.9:/data/test/COMMON/ProdSW/

Cross-Platform Notes

What's the Same:

Git commands (clone, commit, push, pull)
Python/pip commands (once venv activated)
SSH commands (ssh, scp)
Database access (same connection string)
API endpoints (same URLs)
File organization structure

What's Different:

Path separators: \ (Windows) vs / (Mac/Linux)
Venv activation: Scripts\activate vs bin/activate
File copy: copy vs cp
Text editors: notepad vs nano/vim
MCP .mcp.json: cmd /c npx vs just npx
Absolute paths: D:\ vs /Users/ or ~

Troubleshooting

MCP servers not loading:

Restart Claude Code completely
Check npm is installed: npm --version
Check .mcp.json is valid JSON
Mac: Verify paths use forward slashes: /Users/...
Windows: Verify paths use double backslashes: D:\\...

Database connection fails:

Verify network access to 172.16.3.30:3306
Mac: Check firewall settings (System Preferences → Security)
Windows: Check Windows Firewall
Test with: python test_db_connection.py

SSH keys not working:

# Mac: Fix permissions
chmod 700 ~/.ssh
chmod 600 ~/.ssh/id_ed25519
chmod 644 ~/.ssh/id_ed25519.pub

# Windows: Use Git Bash for SSH operations
# Or ensure OpenSSH is installed and running

API won't start:

# Check port 8000 not in use
Windows> netstat -ano | findstr :8000
Mac> lsof -i :8000

# Verify venv is activated (should see (venv) in prompt)
# Check all dependencies: pip list

Git push fails:

# Ensure SSH key is added to Gitea
# Test connection:
ssh -p 2222 azcomputerguru@172.16.3.20

# Check remote URL:
git remote -v

What You Now Have (All Platforms)

Complete Environment:

✅ All project files organized by project/client
✅ Full git history from Gitea
✅ Python API environment configured
✅ MCP servers ready to use
✅ SSH access to infrastructure (D2TESTNAS, Gitea)
✅ Database connection to MariaDB (172.16.3.30)
✅ All credentials and context
✅ All commands and skills available

Full Context:

✅ Dataforth DOS project status and history
✅ ClaudeTools API development history
✅ Client history (Horseshoe Management)
✅ Infrastructure access details
✅ Recent work and decisions

Works On:

✅ Windows 10/11
✅ macOS (Intel and Apple Silicon)
✅ Linux (Ubuntu, Debian, etc.)

Next Steps After Setup

Test DOS deployment on TS-4R (pending from last session)
Continue API development (Phase 5 complete, optional Phase 7 available)
Handle client support requests (Horseshoe Management, etc.)

All work will automatically be organized into correct project/client folders and synced back to Gitea.

Setup Complete! You now have an identical ClaudeTools environment on your new machine, whether it's Windows, Mac, or Linux.

Last Updated: 2026-01-20 File Location: NEW_MACHINE_SETUP.md (in Gitea repository) Platforms: Windows, macOS, Linux

12 KiB Raw Blame History