---
name: start-project
description: Start the development server in the background on port 3000
---

# /start-project

Starts the development server in the background on port 3000.

## Steps

### Step 1 — Detect OS

```bash
uname -s
```

- `Darwin` or `Linux` → use Unix commands in the following steps
- `MINGW*` / `MSYS*` / `CYGWIN*` → use Windows commands (PowerShell)

### Step 2 — Check port 3000

**Mac/Linux:**
```bash
lsof -ti:3000
```

**Windows (PowerShell):**
```powershell
Get-NetTCPConnection -LocalPort 3000 -ErrorAction SilentlyContinue | Select-Object -ExpandProperty OwningProcess
```

If the command returns nothing → port is free, skip to Step 4.

### Step 3 — Port in use: identify and confirm

Get the process name:

**Mac/Linux:**
```bash
ps -p <PID> -o comm=
```

**Windows:**
```powershell
Get-Process -Id <PID> | Select-Object -ExpandProperty ProcessName
```

Tell the user which process is using the port and ask for confirmation:

> Port 3000 is being used by **\<name\>** (PID \<PID\>).
> Do you want me to close it so I can start the project? (yes / no)

If the user says **no** → stop:
> I can't start the server without freeing port 3000. Run `/start-project` again once you've closed it.

If the user says **yes** → kill the process:

**Mac/Linux:**
```bash
kill <PID>
```

**Windows:**
```powershell
Stop-Process -Id <PID> -Force
```

Wait 1 second and verify the port is free (repeat the Step 2 command). If still in use, report and stop.

### Step 4 — Start server in background

```bash
mkdir -p .humand
```

**Mac/Linux:**
```bash
bun dev > .humand/dev.log 2>&1 &
echo $! > .humand/dev.pid
```

**Windows (PowerShell):**
```powershell
$proc = Start-Process -FilePath "cmd" -ArgumentList "/c bun dev >> .humand/dev.log 2>&1" -PassThru -NoNewWindow
$proc.Id | Out-File ".humand/dev.pid"
```

### Step 5 — Verify the server started

Wait 4 seconds, then check that the process is still alive:

**Mac/Linux:**
```bash
kill -0 $(cat .humand/dev.pid) 2>/dev/null && echo "running" || echo "stopped"
```

**Windows:**
```powershell
$id = Get-Content ".humand/dev.pid"
if (Get-Process -Id $id -ErrorAction SilentlyContinue) { "running" } else { "stopped" }
```

If `stopped` → the server failed. Read `.humand/dev.log`, report exactly what happened and what the user can do. **Do not try alternatives or run the server with a different command.**

If `running` → continue.

### Step 6 — Confirm the port responds

**Mac/Linux:**
```bash
curl -s -o /dev/null -w "%{http_code}" http://localhost:3000 || echo "unreachable"
```

**Windows:**
```powershell
try { (Invoke-WebRequest -Uri "http://localhost:3000" -UseBasicParsing -TimeoutSec 3).StatusCode } catch { "unreachable" }
```

If it responds → continue to Step 7.

If `unreachable` → wait 3 more seconds and retry once. If still unreachable, read `.humand/dev.log`, report the error and stop.

### Step 7 — Report result

> The project is running! Open http://localhost:3000 in your browser.
>
> Server logs are saved in `.humand/dev.log`.
> When you're done, run `/stop-project` to shut it down.