Local Development

This guide covers setting up LordClaw for local development.

Prerequisites

git clone https://github.com/InternetJohnny/lordclaw.git
cd lordclaw

npm install

docker compose up -d

This starts a PostgreSQL 16 container on port 5555 (not the default 5432, to avoid conflicts).

npx prisma migrate dev

npm run dev -- --hostname 127.0.0.1 --port 3334

⚠️

On the Mac Mini, public port 3333 is reserved by the LordClaw proxy. Run the Next dev server on 127.0.0.1:3334.

The proxy forwards remote traffic from port 3333 to the app server on 3334.

If your dev machine is on Tailscale:

Open http://<tailscale-ip>:3333 or http://<magic-dns>:3333
Set the gateway URL to wss://<magic-dns> if the gateway is exposed through Tailscale Serve

See Remote Access via Tailscale for the canonical Tailscale Serve example. Keep that setup in one place so the commands do not drift.

postgresql://LordClaw_user:LordClaw_password@localhost:5555/LordClaw

After a machine restart, Docker Desktop may not auto-start:

# Start Docker Desktop (macOS)
open -a Docker
 
# Wait ~15 seconds for the daemon, then:
docker start LordClaw-db

You may also need to restart the dev server, as Prisma caches failed connections.

🚫

Never run prisma migrate reset — this drops all data. Only with explicit approval.

Always use npx prisma migrate dev --name <name> --create-only first, inspect the SQL, then apply
Never use prisma db push (causes schema drift)
New columns must be nullable or have defaults
No destructive operations (DROP TABLE, DROP COLUMN) without approval

npm test          # single run
npm run test:watch  # watch mode

Tests use Vitest and cover slash command parsing, format utilities, pricing calculations, and channel health logic.

npm run build

TypeScript is in strict mode with no any allowed. The build must pass without errors.