headless-pm: Instructions file for Codex

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Environment Setup

Automated Setup (Recommended)

# Run universal setup script - handles platform-specific requirements
./setup/universal_setup.sh

# This will:
# - Detect your architecture (ARM64 for native Mac, x86_64 for Claude Code)
# - Create the appropriate virtual environment (venv or claude_venv)
# - Install correct package versions for your platform
# - Create .env from env-example if needed

Manual Setup (if needed)

# For LLM agents (x86_64), use claude_venv:
python -m venv claude_venv
source claude_venv/bin/activate
pip install pydantic==2.11.7 pydantic-core==2.33.2
pip install -r setup/requirements.txt

# For native Mac (ARM64), use standard venv:
python -m venv venv
source venv/bin/activate
pip install -r setup/requirements.txt

# Configure environment
cp env-example .env
# Edit .env with API keys and database configuration

# Initialize database
python -m src.cli.main init
python -m src.cli.main seed  # Optional: add sample data

Running the Application

Quick Start (Recommended)

# Activate your virtual environment first
source venv/bin/activate  # or source claude_venv/bin/activate

# Use the automated start script (checks environment, DB, starts server)
./start.sh

Manual Start

# Run API server
bash start.sh

The start.sh script automatically:

• ✅ Validates Python 3.11+ requirement
• ✅ Checks required packages are installed
• ✅ Creates .env from env-example if needed
• ✅ Tests database connection
• ✅ Initializes database if needed
• ✅ Checks port availability
• ✅ Starts server with proper configuration
• ✅ Starts only services with defined ports in .env

Service Port Configuration:

• Services are only started if their port is defined in .env
• To skip a service, remove or comment out its port variable:
  • SERVICE_PORT - API server (default: 6969)
  • MCP_PORT - MCP server (default: 6968)
  • DASHBOARD_PORT - Web dashboard (default: 3001)