• For this repo, a “test run” can mean 3 different things. Configure based on which one you want.

  1. npm run verify (typecheck + tests + build)

  - Required:
      - Node + npm
      - Dependencies installed: npm install
  - Not required:
      - API keys
  - Command:
      - npm run verify

  2. UI dry run (no external model calls, safest first run)

  - Required:
      - npm install
      - topologies, personas, relationships, topologyConstraints
      - pipeline with entryNodeId, nodes, edges

  3. Provider-backed run (Codex/Claude via CLI or UI executionMode=provider)

  - Required:
      - Everything in #2
      - Auth for chosen provider:
          - Codex/OpenAI: OPENAI_AUTH_MODE + (CODEX_API_KEY or OPENAI_API_KEY) or existing Codex login
          - Claude: CLAUDE_CODE_OAUTH_TOKEN (preferred) or ANTHROPIC_API_KEY or existing Claude login
      - git available and workspace is a valid git repo (runtime provisions git worktrees)
  - Optional:
      - mcp.config.json (default missing file is allowed if path is default)
  - Important:
      - If you set custom MCP_CONFIG_PATH, that file must exist.

  Environment groups you can tune (defaults already exist)

  - Provider/auth: keys, auth mode, base URL, model, MCP path
  - Limits: AGENT_MAX_*, AGENT_TOPOLOGY_*, AGENT_RELATIONSHIP_MAX_CHILDREN
  - Provisioning: worktree root/base ref, port range/locks, discovery relative path
  - Security: violation mode, allowlisted binaries, timeout, audit path, env inherit/scrub
  - Telemetry/UI: runtime event log + Discord settings, AGENT_UI_HOST/PORT
  - Do not set runtime-injected vars manually (AGENT_WORKTREE_PATH, AGENT_PORT_RANGE_START, etc.).

  Practical first-run sequence

  1. npm install
  2. cp .env.example .env
  3. npm run verify
  4. npm run ui
  5. Start a run in mock mode with a valid manifest
  6. Switch to provider mode after auth is confirmed