# SWARM_ENV.md

Canonical environment contract for Swarm / Swarm2 work.

## One true repo

- **Swarm code, git, build, and tests run only in:** `/Users/aurora/claude-workspace`
- **Do not use:** `/Users/aurora/claude-workspace`

If you detect `claude-workspace`, stop and switch to the canonical repo.

## Memory vs code

- **Memory / handoffs root:** `/Users/aurora/.openclaw/workspace`
- **Daily notes + handoffs writable path:** `/Users/aurora/.openclaw/workspace/memory`
- Use the memory root for notes and handoffs only, not for app code builds.

## Worker runtime model

- Workers are **Claude profiles** under `~/.claude/profiles/<workerId>`
- Wrappers are **canonical launch points** at `~/.local/bin/swarmN`
- One persistent tmux session per worker, named **`swarm-<workerId>`**
- `/swarm2` should attach to the same live session the worker is already using
- Prefer live tmux delivery over one-shot subprocesses

## Machine-readable source of truth

Do not guess layout from random filesystem probes when the API can answer it.
Use:

- `/api/swarm-environment`
- `/api/swarm-runtime`
- `/api/swarm-health`
- `/api/swarm-project`
- `/api/swarm-chat`
- `/api/swarm-decompose`
- `/api/swarm-dispatch`
- `/api/swarm-tmux-start`
- `/api/swarm-tmux-stop`
- `/api/swarm-tmux-scroll`

## Default commands

```bash
cd /Users/aurora/claude-workspace && npm run build
cd /Users/aurora/claude-workspace && npm test -- src/screens/swarm2
cd /Users/aurora/claude-workspace && PORT=3002 npm run dev
```

## Writable roots

- `/Users/aurora/claude-workspace`
- `/Users/aurora/.openclaw/workspace/memory`

## Read-only roots

- `/Users/aurora/.openclaw/workspace`
- `~/.claude/profiles`
- `~/.local/bin`

## Forbidden roots

- `/Users/aurora/claude-workspace`

## Rule of thumb

If a choice is ambiguous, ask:

> What is the one true process/session this worker is running in, and what is the one true repo for the UI surface?

Answer:
- process/session → live Claude worker in tmux `swarm-<workerId>`
- repo → `/Users/aurora/claude-workspace`
