--- name: loom-dev-setup description: Sets up an isolated Loom environment for one task — a worktree from origin/main, its own virtualenv, its own ClickHouse on free ports, migrations, a server from source. Use when starting a Loom change, or when asked to run the server or the integration tests locally. argument-hint: "" metadata: internal: true --- # Loom dev setup Everything a task touches is private to it: the branch, the checkout, the virtualenv, the ClickHouse and the server port. Shared state (the primary checkout's `main`, the git stash, a ClickHouse someone else started, a deployment's containers) is read, never written. ## 1. Worktree In Claude Code, run `git fetch origin main` (the tool reuses a fetch up to a day old), then enter one with the `EnterWorktree` tool: it creates `.claude/worktrees/` from `origin/main` and moves the session there, so the worktree's own `CLAUDE.md`, rules and settings load. Rename its branch (`git branch -m worktree- `), run `pwd` (that is `` below) and continue at §2. A path-scoped rule loads for files under the session's project directory, so a session that edits a sibling checkout from outside it works without the rules. Other agents create the worktree with git and start their session inside it: ```bash BRANCH="$ARGUMENTS" # Claude Code fills this in; elsewhere write the branch name, e.g. fix/search-floor git fetch origin main git worktree add --no-track -b "$BRANCH" "../loom-${BRANCH//\//-}" origin/main # no upstream until the first push sets one cd "../loom-${BRANCH//\//-}" && pwd # the worktree's absolute path: below ``` An agent's shell does not keep its working directory or variables between calls, so every block below starts with `cd &&`, the absolute path printed here. Without it, `uv sync` rewrites the launch checkout's `.venv` and the server serves the launch checkout's code. Branch from `origin/main`, not a local `main` or `FETCH_HEAD` (a concurrent fetch rewrites `FETCH_HEAD`). `main` and the stash are shared with every other worktree (`AGENTS.md`): set work aside with a WIP commit. ## 2. Virtualenv ```bash cd && uv sync --locked --python 3.12 --extra dev --extra code # the lockfile CI installs: same ruff, mypy, pytest .venv/bin/python -P -c 'import server; print(server.__file__)' # must be inside this worktree ``` The make targets use `.venv/bin/python`. Run repository scripts as modules (`.venv/bin/python -m scripts.ops.dump_schema`): a script run by path can import `server` from another checkout. ## 3. A private ClickHouse Pick free ports and a name that cannot be mistaken for a deployment's containers (`loom-blue`, `loom-green`, `loom-proxy`, `loom-server`, `loom-workers`, `loom--workers`, `loom-ch`, `loom-extractor` are taken by convention): ```bash cd && LOOM_CH_CONTAINER="ch-$(basename "$PWD")" LOOM_CH_HOST_PORT=18123 LOOM_CH_NATIVE_HOST_PORT=19000 bash dev/ci_start_clickhouse.sh docker ps --filter "name=^ch-$(basename "$PWD")$" --format '{{.Names}} {{.Ports}}' # yours, on your ports curl -s "http://loom:loomdev@localhost:18123/?query=SELECT+count()+FROM+system.tables+WHERE+database='loom'" # 0 before the first migrate ``` The script refuses a port that is already taken (pick others and re-run), so a failed start cannot hand your migrations to another server. Remove it when done: `docker rm -f "ch-$(basename "$PWD")"`. Keep a list of every container, compose project and volume you start, and remove exactly those, by full name. Never clean up by a pattern (`docker ps --filter name=loom-local-`, `cht-*`): other sessions on the same machine start containers with the same prefixes. ## 4. One `.env` for this worktree An agent's shell keeps no variables between calls, and a server started without them falls back to `localhost:8123` and migrates whatever answers there at boot. Put the worktree's values in its own `.env` (ignored; a fresh worktree has none), which the server, `make migrate` and the tests all read. `LOOM_CH_PORT` is the HTTP port §3 started ClickHouse on (18123 there; change both if you picked others). A variable already exported in the agent's environment wins over `.env`, so check for one first: ```bash cd || exit 1 env | grep -E '^LOOM_(CH_|BASE_URL|ENV_FILE|BACKGROUND_WORKERS|AUTH_REQUIRED|EMBEDDING_MODEL|LLM_PROVIDER)' && { echo "these override .env in every later call: remove them from the shell profile, or start each later command with env -u NAME"; exit 1; } bash -c '(exec 3<>/dev/tcp/127.0.0.1/7790)' 2>/dev/null && { # bash's /dev/tcp; zsh has none echo "port 7790 is taken: pick another for the label, URL and --port"; exit 1; } test -e .env && { echo ".env exists: check its LOOM_CH_* before migrating"; exit 1; } cat > .env < && LOOM_INSTANCE_LABEL="iso:$(pwd | cksum | cut -d' ' -f1):7790" LOOM_BUILD_COMMIT=$(git rev-parse --short HEAD) \ .venv/bin/uvicorn server.main:app \ --app-dir "$PWD" --host 127.0.0.1 --port 7790 --loop asyncio --reload --reload-dir "$PWD/server" ``` Check it in a separate call, by its label rather than its commit (two worktrees fresh from `origin/main` report the same `build_commit`); the label is a checksum of the worktree path because the server keeps only 64 characters of it: ```bash cd && curl -s localhost:7790/v1/health | jq -e --arg l "iso:$(pwd | cksum | cut -d' ' -f1):7790" '.instance_label == $l and .status == "ok"' ``` A `false` means another server holds the port. `--app-dir "$PWD"` makes uvicorn serve this worktree's code; `build_commit` confirms it (a source run reports `unknown` without `LOOM_BUILD_COMMIT`). The label is read from the process environment, not `.env`: without it the server refuses to start. ## 6. Frontend dependencies A worktree's `frontend/node_modules` may be a symlink into another checkout. `npm ci` through that link empties the other checkout's directory. Check first, and replace a link with a real install: ```bash cd && test -L frontend/node_modules && rm frontend/node_modules # removes the link only cd && npm --prefix frontend ci ``` ## 7. Integration tests ```bash cd && make test-integration cd && .venv/bin/python -m pytest tests/integration -m "not slow and not destructive" -q # quick pass ``` Tests read `LOOM_CH_HOST` and `LOOM_BASE_URL` from the environment or from the `.env` the session loads (`LOOM_ENV_FILE=` loads none) and skip without them ([integration tests](../../../docs/development/testing.md#integration-tests)); never point them at a shared or production server. Tests that need self-signup skip in CI, so new tests use `mint_test_token`. ## Reference - [Local development](../../../docs/development/local-development.md), [testing](../../../docs/development/testing.md)