Getting Started

Prerequisites

• Homebrew
• tmux: brew install tmux
• just: brew install just
• uv: brew install uv
• nvm

Building

From the repo root:

just clean rebuild

Running Locally

just source (alias just start-onboard) runs the app from source the way a fresh clone behaves for a real user — the full first-run flow: welcome, onboarding, and repo selection. It resets local dev state each run, so every launch is a true first-run.

just source

Skip onboarding with just start — it seeds an onboarded config and lands straight on the new-workspace form for the current repo, preserving your dev state:

just start

just stop tears down the session (both frontend and backend); only one runs per checkout at a time.

Or run them separately:

just backend   # in one terminal
just frontend  # in another

After pulling new changes, rebuild:

just rebuild

To clear your database and other local state files:

# when running with just start
mv <repo>/.dev_sculptor <repo>/.dev_sculptor.bkp

Running Tests

just test-unit
just test-integration

Code Quality

just format     # Auto-fix formatting (ruff, eslint)
just lint       # Lint Python and JS/TS
just typecheck  # Type check Python (pyrefly) and JS/TS (tsc)
just ratchets   # Run ratchet checks (needs `just install-ratchets`)
just check      # Run all checks, see <repo>/justfile

See the style guide and testing docs for details.