claude-os/docs/SCRIPTS_GUIDE.md

Claude OS Scripts Guide 🚀

Quick reference for managing Claude OS services on macOS.

Quick Start

# First time setup (installs dependencies)
./setup_native.sh

# Start all services
./start_all_services.sh

# Restart services
./restart_services.sh

# Stop all services
./stop_all_services.sh

---

Scripts Overview

1. setup_native.sh - Initial Setup

When to use:

• First time setting up Claude OS
• After cloning the repository
• When dependencies are missing

What it does:

• ✅ Checks Ollama installation
• ✅ Pulls required AI models (llama3.1, nomic-embed-text)
• ✅ Creates Python virtual environment
• ✅ Installs Python dependencies from requirements.txt
• ✅ Creates data/ directory for SQLite database
• ✅ Creates logs/ directory for output files
• ✅ Sets up Node.js frontend (if installed)

Usage:

./setup_native.sh

Output:

🚀 Claude OS Setup - NATIVE (No Docker, No PostgreSQL)
==================================================
Step 1: Checking Ollama installation...
  ✅ Ollama found
  ✅ Ollama is running on port 11434
  Checking models... ✓

Step 2: Pulling required models...
  [models download output...]
  ✅ Models ready

Step 3: Setting up Python environment...
  ✅ Python 3.14 found
  Installing Python dependencies...
  ✅ Python environment ready

Step 4: Creating data directory...
  ✅ Created data/ directory
  ✅ Created logs/ directory

Step 5: Initializing SQLite database...
  ✅ SQLite schema file found
  💾 Database will be created at: data/claude-os.db

Step 6: Setting up Node.js frontend...
  ✅ Node.js v20.x found
  ✅ Frontend dependencies ready

✅ Claude OS Setup Complete!

---

2. start_all_services.sh - Start Services

When to use:

• After setup is complete
• Every time you want to start working
• After stopping services

What it does:

• ✅ Checks Ollama is running (starts if needed)
• ✅ Verifies AI models are available
• ✅ Sets up Python environment
• ✅ Creates data directory if missing
• ✅ Starts MCP Server (port 8051)
• ✅ Starts React Frontend (port 5173)
• ✅ Shows URLs and logs

Usage:

./start_all_services.sh

Output:

🚀 Claude OS - Starting All Services
==================================================

1. Checking Ollama...
   ✓ Ollama is running on port 11434
   Checking models... ✓

2. Setting up Python environment...
   ✓ Python environment ready

3. Checking data directory...
   ✓ data/ directory exists
   ✓ logs/ directory exists

4. Starting MCP Server...
   Server PID: 12345 (logging to logs/mcp_server.log)
   Waiting for server to start... ✓

5. Starting React Frontend...
   Frontend PID: 12346 (logging to logs/frontend.log)
   Waiting for frontend to start... ✓

✅ All Services Started Successfully!

📡 Service URLs:
   🎨 Frontend:    http://localhost:5173
   🔌 API Server:  http://localhost:8051
   📚 API Docs:    http://localhost:8051/docs

🔧 Ollama:
   Host:    http://localhost:11434
   Models:  llama3.1:latest, nomic-embed-text:latest

💾 Database:
   Type:     SQLite (single file)
   Location: data/claude-os.db

📝 Log Files:
   MCP Server:  logs/mcp_server.log
   Frontend:    logs/frontend.log

🛑 To Stop All Services:
   ./stop_all_services.sh

🔄 To Restart All Services:
   ./restart_services.sh

---

3. stop_all_services.sh - Stop Services

When to use:

• When you're done working
• Before restarting
• To free up ports

What it does:

• ✅ Stops MCP Server (port 8051)
• ✅ Stops React Frontend (port 5173)
• ✅ Preserves SQLite database
• ✅ Leaves Ollama running (used by other apps)

Usage:

./stop_all_services.sh

Output:

🛑 Claude OS - Stopping All Services
==================================================

Stopping 🔌 MCP Server (port 8051)...
   ✓ MCP Server stopped (PID: 12345)
Stopping 🎨 React Frontend (port 5173)...
   ✓ React Frontend stopped (PID: 12346)

✅ All Claude OS services stopped

ℹ️  Note:
   - Ollama is NOT stopped (may be used by other apps)
   - SQLite database (data/claude-os.db) is preserved

To restart:
   ./restart_services.sh

To start with full setup:
   ./start_all_services.sh

---

4. restart_services.sh - Restart Services

When to use:

• After code changes to backend
• When services are behaving strangely
• As a quick restart command

What it does:

• ✅ Stops all services
• ✅ Waits for ports to be released
• ✅ Starts all services again

Usage:

./restart_services.sh

---

Common Workflows

First Time Setup

# 1. Clone the repo
git clone <repo>
cd claude-os

# 2. Run setup
./setup_native.sh

# 3. Start services
./start_all_services.sh

# 4. Open browser
open http://localhost:5173

Daily Development

# Morning: start services
./start_all_services.sh

# Work on features...

# Change backend code?
./restart_services.sh

# Frontend auto-reloads, no restart needed

# End of day: stop services
./stop_all_services.sh

Troubleshooting

# Check if services are running
lsof -i :5173  # Frontend
lsof -i :8051  # MCP Server

# View logs
tail -f logs/mcp_server.log
tail -f logs/frontend.log

# Restart if something is wrong
./restart_services.sh

# Clear old database and start fresh
rm data/claude-os.db
./start_all_services.sh

---

Ports Used

Service	Port	Purpose
Frontend	5173	React dev server
MCP Server	8051	API & RAG engine
Ollama	11434	LLM inference

---

Environment Requirements

macOS

• Ollama (installed via brew install ollama)
• Python 3.11+ (python3 --version)
• Node.js 18+ (npm --version, optional for frontend)

Files Used

data/
  ├── claude-os.db          # SQLite database (auto-created)
  └── uploads/              # User-uploaded documents

logs/
  ├── mcp_server.log        # MCP Server logs
  └── frontend.log          # Frontend logs

venv/                        # Python virtual environment

---

Advanced Usage

Kill Specific Port

# Kill process on port 8051
lsof -i :8051 | grep -v COMMAND | awk '{print $2}' | xargs kill -9

View Real-time Logs

# Watch MCP Server logs
tail -f logs/mcp_server.log

# Watch Frontend logs
tail -f logs/frontend.log

# Follow both
tail -f logs/*.log

Backup Database

# Create backup
cp data/claude-os.db data/claude-os.db.backup

# Restore from backup
cp data/claude-os.db.backup data/claude-os.db

Reset Everything

# Stop services
./stop_all_services.sh

# Clear database
rm data/claude-os.db

# Re-setup
./setup_native.sh

# Start fresh
./start_all_services.sh

---

Tips & Tricks

🚀 Fast Restart

# One-liner restart
./stop_all_services.sh && sleep 2 && ./start_all_services.sh

📊 Monitor Resources

# Watch CPU/Memory usage
top -o %CPU

# Watch Ollama model usage
ollama ps

🔧 Debug Mode

# Run server directly (no background)
source venv/bin/activate
cd mcp_server
python server.py

🎨 Frontend Development

# Frontend auto-reloads on file changes
# No restart needed for React components
# Only restart for Python changes

---

Troubleshooting

"Port already in use"

# Check what's using the port
lsof -i :8051

# Kill the process
kill -9 <PID>

# Or use our stop script
./stop_all_services.sh

"Ollama is not running"

# Check status
ollama ps

# Start Ollama
brew services start ollama

# Or manually
ollama serve

"Module not found" errors

# Reinstall dependencies
source venv/bin/activate
pip install -r requirements.txt

Database corrupted?

# Backup old database
mv data/claude-os.db data/claude-os.db.old

# Restart (creates new database)
./start_all_services.sh

# Restore if needed
mv data/claude-os.db.old data/claude-os.db

---

Support

Check logs for errors:

tail -50 logs/mcp_server.log
tail -50 logs/frontend.log

For issues:

1. Check logs
2. Try ./restart_services.sh
3. Try ./setup_native.sh again
4. Check if Ollama is running: ollama ps

---

Ready to go! 🚀

Next: Open http://localhost:5173 and start building! 💪