Skip to content

Development Setup

Get a local development environment running for contributing to Lumbergh.

Requirements

Clone and Bootstrap

git clone https://github.com/voglster/lumbergh.git
cd lumbergh
./bootstrap.sh

The bootstrap script creates a tmux session with three windows:

  1. claude -- Claude Code session
  2. backend -- FastAPI server on port 8420
  3. frontend -- Vite dev server on port 5420

Your browser opens automatically to http://localhost:5420.

Manual Start

If you prefer to start services yourself:

./backend/start.sh   # Backend on :8420
./frontend/start.sh  # Frontend on :5420

Dev Server Proxy

The Vite dev server on port 5420 proxies all /api requests to the backend on port 8420. Use port 5420 during development for hot reloading.

Linting

Run the lint script before submitting PRs:

./lint.sh

This auto-fixes what it can with ruff (format), prettier, and eslint. Fix any remaining errors before considering your work done.

Warning

The lint script exits non-zero if unfixable errors remain. CI will catch these too.

Contributing Tips

  • The backend is a thin layer over tmux and git subprocesses -- keep it simple.
  • TinyDB handles persistence; no database server needed.
  • WebSocket powers terminal streaming; REST + polling handles diffs and metadata.
  • Mobile-first responsive design -- test on small viewports.