claude-os/docs/SCRIPTS_GUIDE.md

# Claude OS Scripts Guide 🚀

Quick reference for managing Claude OS services on macOS.

## Quick Start

```bash
# 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:**
```bash
./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:**
```bash
./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:**
```bash
./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:**
```bash
./restart_services.sh
```

---

## Common Workflows

### First Time Setup

```bash
# 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

```bash
# 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

```bash
# 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

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

### View Real-time Logs

```bash
# 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

```bash
# 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

```bash
# 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

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

### 📊 Monitor Resources

```bash
# Watch CPU/Memory usage
top -o %CPU

# Watch Ollama model usage
ollama ps
```

### 🔧 Debug Mode

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

### 🎨 Frontend Development

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

---

## Troubleshooting

### "Port already in use"

```bash
# 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"

```bash
# Check status
ollama ps

# Start Ollama
brew services start ollama

# Or manually
ollama serve
```

### "Module not found" errors

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

### Database corrupted?

```bash
# 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:
```bash
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! 💪