⚠️ DELEGATION REQUIRED

This skill must be executed by the instruction-follower subagent.

When you see this skill invoked, you MUST use the Task tool to delegate it:

Task(
    subagent_type="instruction-follower",
    description="[Brief 3-5 word description]",
    prompt="Follow the instructions in .claude/skills/py-stop-local/skill.md to [complete task description]."
)

DO NOT execute the instructions below directly. The subagent will read this file and execute autonomously, then report back the results.

---

Python Stop Local Server

Overview

Stops a locally running Flask server by killing the process on port 8080. Works for both foreground and background server instances.

When to Use

Invoke this skill when the user:

• Asks to "stop the server"
• Wants to "kill the Flask app"
• Says "stop local server"
• Mentions shutting down the Python server
• Needs to stop before deploying or restarting

Prerequisites

• Server must be running on port 8080
• Either a PID file exists (server.pid) or lsof command available
• macOS or Linux system

Instructions

Option 1: Using stop.sh Script

1. Navigate to the server directory:

   cd path/to/server/imp/py
   

2. Run the stop script:

   ./stop.sh
   

3. The script will:

   • Read PID from server.pid file
   • Kill the process
   • Clean up PID file
   • Report success

Option 2: Manual Stop by Port

If no script available:

lsof -ti:8080 | xargs kill

This finds and kills any process using port 8080.

Option 3: Foreground Server

If running in foreground mode:

• Press Ctrl+C in the terminal

Expected Output

Using stop.sh:

🛑 Stopping Firefly server...
✅ Server stopped (PID: 12345)

Manual stop:

# Silent if successful, or:
kill: 12345: No such process (if already stopped)

How It Works

stop.sh script:

if [ -f server.pid ]; then
    PID=$(cat server.pid)
    kill $PID
    rm server.pid
    echo "Server stopped"
else
    # Fallback: kill by port
    lsof -ti:8080 | xargs kill
fi

lsof method:

• lsof -ti:8080: Lists process IDs using port 8080
• xargs kill: Pipes PIDs to kill command
• Clean termination (SIGTERM)

Verification

Check server is stopped:

# Try to curl - should fail
curl http://localhost:8080/api/ping

# Check port is free
lsof -ti:8080
# (no output = port free)

Common Issues

"No such process":

• Server already stopped (not an error)
• PID file may be stale
• Delete server.pid if it exists

"Operation not permitted":

• Server running as different user
• Try with sudo (not recommended)
• Check process owner: ps aux | grep python3

Port still in use after stop:

• Process didn't terminate cleanly
• Force kill: lsof -ti:8080 | xargs kill -9
• Wait a few seconds for port to free

server.pid file not found:

• Server wasn't started with start.sh
• Use manual stop: lsof -ti:8080 | xargs kill
• Or kill foreground server with Ctrl+C

Kill Signals

SIGTERM (default kill):

• Polite termination request
• Allows cleanup
• Process can catch and handle
• Used by stop.sh

SIGKILL (kill -9):

• Immediate termination
• No cleanup possible
• Cannot be caught
• Use as last resort

Always try SIGTERM first.

When to Stop

Before deploying:

./stop.sh
# Make changes
./start.sh

Before testing different port:

./stop.sh
# Edit app.py to use different port
python3 app.py

Before remote deployment:

./stop.sh  # Stop local
# Deploy to remote with py-deploy-remote

When switching modes:

# Stop background server
./stop.sh
# Start foreground for debugging
python3 app.py

Port Conflicts

If port 8080 is used by another app:

Find what's using port:

lsof -i:8080

Output shows:

COMMAND  PID   USER   FD   TYPE DEVICE SIZE/OFF NODE NAME
python3  12345 user   3u  IPv4  0x...  0t0  TCP *:8080 (LISTEN)

Kill specific process:

kill 12345

Cleanup

The stop script cleans up:

• Terminates Python process
• Removes server.pid file
• Frees port 8080

Logs (server.log) are preserved for review.

Safe to Call Repeatedly

This operation is idempotent:

• Safe to call if server already stopped
• Won't error on missing PID
• Graceful failure on no process found

Integration with Other Skills

Restart workflow:

1. py-stop-local
2. Make code changes
3. py-start-local

Deploy workflow:

1. py-stop-local (local server)
2. py-deploy-remote (to production)
3. py-start-local (resume local development)

Alternative: Process Manager

For production, use a process manager:

• supervisord: Automatic restart, logging
• systemd: System-level service
• pm2: Node.js-based process manager

But for development, manual start/stop is simpler.

Notes

• Only stops server on current machine
• Does not affect remote deployments
• Port 8080 becomes available immediately after stop
• Logs remain in server.log for review
• PID file is automatically cleaned up