Development setup

This page takes you from a clean checkout to a running dev environment with hot reload on both halves of the app. The everyday loop is two terminals: the Python backend on :1112 and the Vite dev server on :1515, each side reloading its own code.

First-time setup

Run these once. They install dependencies for both halves and write your local config.

# Python deps (reads pyproject.toml + uv.lock)
uv sync

# Node deps
cd ui
npm install
cd ..

# Initial config: profile, LLM keys, ports, etc.
uv run cremind setup

uv run cremind setup is interactive and writes ~/.cremind/ with your profile and provider credentials. You only need to run it again if you delete ~/.cremind/.

The two-terminal loop

The daily loop runs the backend and the Vite dev server side by side. The backend serves the API on :1112; Vite serves the UI on :1515 with hot module replacement (HMR).

Prerequisite: free port :1515 for Vite

The merged backend always binds the single public port (CREMIND_UI_PORT, default :1515) — whether or not a SPA is built — so by default it fights Vite for :1515. Free that port for Vite by running the backend on loopback only:

# Bind only the internal API (loopback :1112); open no public :1515 bind.
$env:CREMIND_UI_PORT = "0"

Terminal A — backend

$env:CREMIND_UI_PORT = "0"               # bind the internal API on :1112 only; free :1515 for Vite
$env:APP_URL = "http://localhost:1112"   # agent card + OAuth redirects target the backend, not Vite
uv run cremind serve

The log shows CREMIND_UI_PORT=0 — serving loopback-only on http://127.0.0.1:1112: the backend binds only the internal API (loopback) and leaves :1515 free for Vite.

Terminal B — Vite dev server

cd ui
$env:VITE_AGENT_URL = "http://localhost:1112"   # point the SPA at the backend's internal API
npm run web:dev

Open http://localhost:1515 (Vite). VITE_AGENT_URL points the SPA at the backend's internal API — the merged app is same-origin in production, so without it runtimeConfig.ts would resolve the API at Vite's own :1515, which doesn't serve it. (Tip: put VITE_AGENT_URL=http://localhost:1112 in ui/.env.local so you don't set it each session.)

To confirm you're hitting Vite and not a stale backend bundle, open browser DevTools and look at the Sources panel. You should see /@vite/client — that's HMR live. If you only see a hashed file like assets/index-Cabc123.js, the backend bound :1515 (you didn't set CREMIND_UI_PORT=0); revisit the prerequisite above.

What hot-reloads

Optional: auto-restart on Python edits

cremind serve doesn't expose --reload, but you can wrap it with watchfiles from the outside:

uv run --with watchfiles watchfiles "uv run cremind serve" app

This watches app/ and restarts the whole process on any change. It's slower than an in-process reload — roughly a couple of seconds for a cold restart — but it always works.

Variations

Gotchas

• Backend grabbed :1515. If you forget CREMIND_UI_PORT=0, the merged backend binds :1515 (Terminal A logs Serving on public http://0.0.0.0:1515) and Vite can't take it — or you end up viewing the bundled build instead of HMR. Set the env var and restart Terminal A.
• First page load after setup. The SPA on :1515 may show the setup wizard until the agent URL is configured. After that it sticks.
• Backend not picking up code changes. Kill and restart Terminal A. Don't restart Vite — it's stateful for HMR.
• The dev SPA needs VITE_AGENT_URL. The old :1515→:1112 port-swap was removed (the SPA is same-origin in production), so in dev you must point it at the backend with VITE_AGENT_URL=http://localhost:1112 (or ui/.env.local).
• Don't edit ui/package.json's version field. It's regenerated from app/__version__.py by scripts/sync_ui_version.py, wired into the prebuild / preweb:build npm hooks. See Versioning.

Next