⚡ EXECUTION INSTRUCTIONS FOR CLAUDE
When this command is invoked, YOU (Claude) must execute these steps immediately:
This is NOT documentation - these are COMMANDS to execute right now.
Use TodoWrite to track progress through multi-phase workflows.
🚨 EXECUTION WORKFLOW
Phase 1: Execution Logic
Action Steps:
The /localserver launcher performs the following steps before starting the servers:
- Project Root Detection: Changes into the repository root so relative paths behave correctly.
- Script Discovery: Checks for
run_local_server.sh in:
<project-root>/run_local_server.sh
<project-root>/scripts/run_local_server.sh
- Validation: Exits with a clear error if neither location exists.
- Execution: Runs the discovered script (forwarding any arguments) using its executable bit if set, or via
bash otherwise.
This ensures /localserver works whether the helper script lives at the repository root or inside the scripts/ directory.
📋 REFERENCE DOCUMENTATION
/localserver
Starts the local development server for testing with health verification.
Usage
/localserver
What it does
Executes the dedicated ./claude_command_scripts/commands/localserver.sh launcher which locates and runs run_local_server.sh from either the project root or scripts/ directory. The launcher provides:
- Dual Server Setup: Flask backend + React v2 frontend on separate ports
- Aggressive Cleanup: Interactive server cleanup with options to kill all servers or specific ports
- Dynamic Port Assignment: Automatically finds available ports starting from defaults (Flask: 8081, React: 3002)
- Force Port Clearing: Ensures target ports are available by killing conflicting processes
- Virtual Environment: Automatically sets up and activates Python virtual environment
- Comprehensive Health Checks: Validates both servers with curl before declaring success
- API Testing: Tests actual API endpoints to ensure backend is responding correctly
Enhanced Features Integrated
Aggressive Cleanup
- Lists all running servers with branch names and PIDs
- Interactive cleanup options:
[a] Kill all servers (aggressive cleanup) - default
[p] Kill processes on target ports only
[n] Keep all servers running
- Force port clearing for default Flask (8081) and React (3002) ports
Health Verification
- Flask backend:
curl http://localhost:{FLASK_PORT}/ with retry logic
- React frontend:
curl http://localhost:{REACT_PORT}/ with extended timeout
- API connectivity: Tests
/api/campaigns endpoint for proper authentication response
- Failure handling: Kills servers and exits on Flask failure, warns on React issues
- Success criteria: Flask must respond, React warnings allowed (common startup delay)
Dynamic Port Management
- Smart port finding: Starts from defaults, finds next available if occupied
- Port conflict resolution: Clears target ports before finding alternatives
- Reliable assignment: Uses server-utils.sh functions for robust port management
Implementation
./claude_command_scripts/commands/localserver.sh [optional-args]
All the enhanced features (cleanup, health checks, port management) are now integrated into the main server launcher script, providing a single, robust solution for local development.
Server URLs
- Flask Backend:
http://localhost:{FLASK_PORT} (dynamic port starting from 8081)
- React Frontend:
http://localhost:{REACT_PORT} (dynamic port starting from 3002)
- Test Mode Access:
http://localhost:{REACT_PORT}?test_mode=true&test_user_id=test-user-123
Notes
- Both servers run in separate terminals/processes for independent debugging
- Testing mode enabled (TESTING=true) for mock AI responses
- Health checks are mandatory - script only declares success after validation
- Aggressive cleanup ensures clean startup environment