SerpentStack dev-server

Monitor and auto-fix the development environment. Use when: debugging backend/frontend errors, watching log streams, diagnosing startup failures, or running make dev.

install

source · Clone the upstream repo

git clone https://github.com/Benja-Pauls/SerpentStack

Claude Code · Install into ~/.claude/skills/

T=$(mktemp -d) && git clone --depth=1 https://github.com/Benja-Pauls/SerpentStack "$T" && mkdir -p ~/.claude/skills && cp -r "$T/.skills/dev-server" ~/.claude/skills/benja-pauls-serpentstack-dev-server && rm -rf "$T"

manifest: .skills/dev-server/SKILL.md

source content

Dev Server

Starting the Dev Environment

make dev          # Starts Postgres, Redis, runs migrations, launches backend + frontend
make dev-docker   # Alternative: run everything in Docker

Backend: http://localhost:8000 · API docs: http://localhost:8000/api/docs Frontend: http://localhost:5173

make dev

fails, check

docker compose ps

to verify Postgres is healthy.

Error Detection Patterns

Backend (FastAPI) — Structured JSON Logs

Pattern	Meaning	Fix
`"level": "ERROR"`	Application error	Read `traceback` , `module` , `lineno` fields
`ModuleNotFoundError`	Missing dependency	`cd backend && uv add <package>`
`sqlalchemy.exc.OperationalError`	Database connection failed	Check Postgres is running, migrations are current
`sqlalchemy.exc.ProgrammingError: relation "X" does not exist`	Missing migration	`cd backend && uv run alembic upgrade head`
`pydantic.ValidationError`	Schema field mismatch	Compare request payload against Pydantic model
`ImportError: cannot import name 'X' from 'app.models'`	Model not exported	Add import to `backend/app/models/__init__.py`

Frontend (Vite/React)

Pattern	Meaning	Fix
`TS\d{4}:` (e.g., `TS2345` )	TypeScript error	Read file path + line number from message
`[vite] Internal server error`	Build failure	Read full error below the message
`Module not found: Can't resolve`	Missing package	`cd frontend && npm install` or add the dependency
`Uncaught Error:`	React runtime error	Read component stack trace
`[hmr] Failed to reload`	HMR failure (usually syntax)	File path is in the message

Auto-Fix Workflow

When an error is detected:

Classify: syntax, type, import, runtime, or database error
Locate: extract file path and line number from the error output
Check recent changes:
```
git diff HEAD~1 -- <file>
```
Read the file: open at the relevant line, read 20 lines of surrounding context
Fix: apply the minimal change to resolve the error
Verify: wait for hot-reload, confirm the error is gone

Verification

make verify   # Runs lint + typecheck + test for both backend and frontend