Start Services - Intelligent Service Launcher

This skill helps you start project services (backend API, frontend server) with automatic detection and resolution of port conflicts. Optimized for Python/FastAPI backend and static frontend projects.

When to Use This Skill

• User explicitly asks: "start services", "start the server", "run the app", "launch backend/frontend"
• After session recovery: When recovering context with /recover-context
• After git pull: When starting work after pulling latest changes
• Development workflow: Beginning a development session
• After dependency installation: When setting up environment for first time

Common Port Conflicts Observed

From real-world usage, common conflicts include:

1. Port 8000: Often occupied by MCP servers (workspace-mcp), uvicorn instances, other FastAPI apps
2. Port 8080: Often occupied by previous http.server instances, other web servers
3. Port 3000: Often occupied by React dev servers, Node.js apps
4. Port 5000: Often occupied by Flask apps, other Python servers

Instructions

Step 1: Check Project Structure

Determine what services exist in the project:

# Check for backend (FastAPI/Flask)
ls -la src/api/main.py 2>/dev/null && echo "Backend exists" || echo "Backend not implemented yet"

# Check for frontend
ls -la frontend/index.html 2>/dev/null && echo "Frontend exists" || echo "Frontend not found"

# Check for requirements.txt
ls -la requirements.txt 2>/dev/null && echo "Requirements file exists" || echo "No requirements.txt"

# Check for virtual environment
ls -la venv/ 2>/dev/null && echo "venv exists" || echo "venv not created"

Step 2: Detect Port Conflicts

CRITICAL: Always check for port conflicts BEFORE attempting to start services.

# Check common ports for conflicts
lsof -i :8000 -i :8080 -i :3000 -i :5000 || echo "All common ports are available"

If ports are occupied, identify what's using them:

# For each occupied port, check the process
lsof -i :8000 | grep LISTEN  # Backend port
lsof -i :8080 | grep LISTEN  # Frontend port

# Get detailed process info
ps -p <PID> -o pid,ppid,command

Step 3: Resolve Port Conflicts

Decision Tree for Port Conflicts:

If port is occupied by same project (previous session):

# Kill the old process gracefully
kill <PID>

# Verify port is released
lsof -i :<PORT> || echo "Port <PORT> is now available"

If port is occupied by MCP server or system service:

# DO NOT KILL - Choose alternative port instead
# For backend: Use 8001, 8002, etc.
# For frontend: Use 8081, 8082, etc.

# Report to user that alternative port will be used
echo "Port 8000 occupied by MCP server, using port 8001 instead"

If port is occupied by unknown process:

# Ask user before killing
# Use AskUserQuestion tool to confirm:
# - Show process details (PID, command)
# - Ask if safe to kill
# - Offer alternative port option

Step 4: Setup Virtual Environment (Python Projects)

CRITICAL: ALWAYS use virtual environment for Python dependencies (per CLAUDE.md instructions).

# Check if venv exists
if [ ! -d venv ]; then
    echo "Creating virtual environment..."
    python -m venv venv
fi

# Activate venv (macOS/Linux)
source venv/bin/activate

# Verify activation
which python  # Should point to venv/bin/python

# Install dependencies if requirements.txt exists
if [ -f requirements.txt ]; then
    pip install -r requirements.txt
fi

Windows activation:

venv\Scripts\activate

Step 5: Start Backend Service (if exists)

Only if src/api/main.py exists:

# Activate venv first (if not already active)
source venv/bin/activate

# Start FastAPI with uvicorn
uvicorn src.api.main:app --reload --port 8000 &

# Or if port 8000 is occupied, use alternative:
uvicorn src.api.main:app --reload --port 8001 &

# Capture background process ID
BACKEND_PID=$!
echo "Backend started with PID: $BACKEND_PID on port 8000"

Verify backend is running:

sleep 2  # Give it time to start
lsof -i :8000 | grep LISTEN && echo "✅ Backend running on port 8000"

Step 6: Start Frontend Service (if exists)

Only if frontend/index.html exists:

# Navigate to frontend directory and start simple HTTP server
cd frontend && python -m http.server 8080 &

# Or if port 8080 is occupied:
cd frontend && python -m http.server 8081 &

# Capture background process ID
FRONTEND_PID=$!
echo "Frontend started with PID: $FRONTEND_PID on port 8080"

Verify frontend is running:

sleep 2
lsof -i :8080 | grep LISTEN && echo "✅ Frontend running on port 8080"

Step 7: Report Service Status to User

Provide a clear summary with URLs and PIDs:

✅ Services Started Successfully!

**Backend Service** (if applicable):
- Status: ✅ Running
- Port: 8000 (or alternative if conflict)
- PID: <process_id>
- URL: http://localhost:8000
- API Docs: http://localhost:8000/docs (FastAPI)
- Health Check: http://localhost:8000/health

**OR**:
- Status: ⚠️ Not implemented yet (src/api/ not found)
- Next Step: Implement Phase 2 backend

**Frontend Service**:
- Status: ✅ Running
- Port: 8080 (or alternative if conflict)
- PID: <process_id>
- URL: http://localhost:8080
- Dashboard: http://localhost:8080/index.html

**OR**:
- Status: ❌ Frontend not found

**Port Conflicts Resolved**:
- Port 8000: Was occupied by <process_name> (PID <pid>) → Killed/Alternative port used
- Port 8080: Was occupied by previous http.server → Killed and restarted

**Virtual Environment**:
- Status: ✅ Activated (venv/bin/python)
- Dependencies: ✅ Installed from requirements.txt

**Quick Links**:
- Frontend Dashboard: http://localhost:8080
- Backend API Docs: http://localhost:8000/docs
- Health Check: http://localhost:8000/health

**To Stop Services**:
```bash
# Stop backend
kill <BACKEND_PID>

# Stop frontend
kill <FRONTEND_PID>

# Or kill all Python servers
pkill -f "python -m http.server"
pkill -f "uvicorn"

Next Steps:

1. Open http://localhost:8080 in browser
2. Test frontend visualization with playback controls
3. [Project-specific next steps]

## Edge Cases & Error Handling

### Case 1: Virtual Environment Not Activated
```bash
# Check if venv is active
if [ -z "$VIRTUAL_ENV" ]; then
    echo "⚠️ Virtual environment not activated"
    source venv/bin/activate
fi

Case 2: Dependencies Not Installed

# Check if FastAPI/uvicorn installed
python -c "import uvicorn" 2>/dev/null || {
    echo "⚠️ Dependencies not installed"
    pip install -r requirements.txt
}

Case 3: Backend Crashes on Startup

# Capture startup errors
uvicorn src.api.main:app --reload --port 8000 2>&1 | tee backend.log &

# Check for errors after 2 seconds
sleep 2
if ! lsof -i :8000 | grep LISTEN; then
    echo "❌ Backend failed to start. Check backend.log"
    cat backend.log
fi

Case 4: Port Already in Use (Cannot Kill)

# If lsof shows port occupied but kill fails
# Offer alternative port automatically
BACKEND_PORT=8000
while lsof -i :$BACKEND_PORT; do
    BACKEND_PORT=$((BACKEND_PORT + 1))
done
echo "Using alternative port: $BACKEND_PORT"
uvicorn src.api.main:app --reload --port $BACKEND_PORT &

Case 5: Multiple Project Servers Running

# If user has multiple projects with servers running
# Show all Python servers and ask which to kill
echo "Found multiple Python servers:"
lsof -i :8000 -i :8080 -i :3000 -i :5000

# Use AskUserQuestion to confirm which to kill

Project-Specific Patterns

Pattern 1: Aviation Safety Monitor (This Project)

# Frontend only (backend not implemented yet in Phase 1)
cd frontend && python -m http.server 8080 &
echo "Frontend running at http://localhost:8080"
echo "Open dashboard at http://localhost:8080/index.html"

Pattern 2: FastAPI + Frontend

# Start both services
source venv/bin/activate
uvicorn src.api.main:app --reload --port 8000 &
cd frontend && python -m http.server 8080 &

Pattern 3: Flask Backend

source venv/bin/activate
python src/app.py &  # or flask run

Pattern 4: Node.js Frontend

cd frontend
npm install  # if needed
npm start &  # Usually starts on port 3000

Observability & Monitoring

Health Checks

# Backend health check (if implemented)
curl http://localhost:8000/health

# Frontend availability
curl -I http://localhost:8080

# Check if services are responsive
curl -s http://localhost:8000/health | grep -q "ok" && echo "✅ Backend healthy" || echo "❌ Backend unhealthy"

Process Monitoring

# Check if processes are still running
ps -p $BACKEND_PID && echo "Backend still running" || echo "Backend stopped"
ps -p $FRONTEND_PID && echo "Frontend still running" || echo "Frontend stopped"

Log Tailing

# If logs are generated
tail -f backend.log &
tail -f frontend.log &

Common Mistakes to Avoid

1. DON'T kill MCP servers or system services - Use alternative ports
2. DON'T forget to activate venv - Always source venv/bin/activate first
3. DON'T assume ports are available - Always check with lsof first
4. DON'T start services in global Python - Virtual environment required
5. DON'T leave zombie processes - Track PIDs and report them
6. DON'T skip dependency installation - Check requirements.txt

Integration with Project Workflow

This skill works well with other project commands:

# Typical workflow
/recover-context              # Load project context
# [start-services skill runs]  # Start services
# [Development work]
/save-session                 # Save progress
/clear                        # Clear context

Quality Gates

Before reporting success, verify:

• Virtual environment activated (if Python project)
• All port conflicts resolved
• Services actually listening on expected ports
• Health checks passing (if implemented)
• PIDs tracked and reported to user
• URLs accessible and correct

Benefits of This Skill

1. Prevents Port Conflicts: Automatically detects and resolves conflicts
2. Smart Process Management: Distinguishes between project vs system processes
3. Virtual Environment Safety: Ensures venv is used (per CLAUDE.md)
4. Clear Status Reporting: User knows exactly what's running and where
5. Error Recovery: Handles common failure modes gracefully
6. Time Savings: Automates 5+ manual commands into one skill
7. Consistency: Same service startup process every session

Notes

• This is a project-agnostic skill that adapts to project structure
• Reads project configuration (frontend/, src/api/, requirements.txt)
• Respects CLAUDE.md instruction: "ALWAYS use venv for Python dependencies"
• Handles partial implementations (frontend exists, backend doesn't)
• Safe for concurrent MCP servers on port 8000
• Works on macOS, Linux, Windows (with slight adaptations)

Example Usage

Example 1: User Explicitly Asks

User: "start the services"

Claude:

1. Check project structure (find frontend/, no backend yet)
2. Check port conflicts (find http.server on 8080 from previous session)
3. Kill old http.server process
4. Start frontend on port 8080
5. Report status with URL

Example 2: After Session Recovery

Context: Just ran /recover-context

Claude (proactively): "I'll start the services for you." [Executes start-services skill]

Example 3: Port Conflict with MCP Server

Context: Port 8000 occupied by workspace-mcp

Claude:

1. Detect port 8000 occupied by MCP server (PID 22880)
2. Recognize it's system service (not project-related)
3. Choose alternative port 8001 for backend
4. Report: "Port 8000 occupied by MCP server, using 8001 instead"

Example 4: Fresh Project Setup

Context: Just cloned project, no venv yet

Claude:

1. Detect no venv exists
2. Create virtual environment
3. Install dependencies from requirements.txt
4. Start services
5. Report complete setup

Critical Reminders

• ALWAYS check for port conflicts BEFORE starting services
• ALWAYS use virtual environment for Python projects
• ALWAYS track process IDs and report them
• ALWAYS verify services are actually listening before reporting success
• NEVER kill MCP servers or system services without user confirmation
• NEVER install to global Python (per CLAUDE.md)
• NEVER assume ports are available

Debugging Commands

If services fail to start:

# Check what's using the ports
lsof -i :8000 -i :8080

# Check if venv is activated
echo $VIRTUAL_ENV

# Check if dependencies are installed
pip list | grep -E "fastapi|uvicorn"

# Check for Python syntax errors
python -m py_compile src/api/main.py

# Check for import errors
python -c "from src.api.main import app"

# Test backend manually
python -m uvicorn src.api.main:app --reload --port 8000

# Test frontend manually
cd frontend && python -m http.server 8080

Version History

• v1.0 (2025-11-14): Initial skill created based on real port conflict observations
  • Observed port 8000 conflict with workspace-mcp (PID 22880)
  • Observed port 8080 conflict with previous http.server (PID 91781)
  • Successfully resolved by killing project-owned process, respecting MCP server