iterate

iterate

Monorepo for Iterate's Cloudflare Workers platform. apps/os is the main app — the product dashboard at os.iterate.com.

Agent instructions: AGENTS.md. Engineering requirements: no deviant system behaviour.

Environments

• The root envs.ts is the typed map of every deployed environment (hostnames, worker names, accounts, resource IDs); Doppler supplies only secrets, one config per env (prd, preview_N; dev/dev_<you> are fully local and never deploy).
• Each app deploys with its own small scripts: pnpm run deploy --env <name> (build → wrangler deploy with atomic secrets → smoke), ensure-resources, erase-data. Workers are never deleted.
• Details: DevOps: Cloudflare And Doppler.

Talking to OS

Run these from apps/os. Plain pnpm cli ... uses your local Doppler setup for apps/os. Wrap in doppler run --config <config> -- ... to target a specific environment; the config supplies URLs and secrets. More on this script pattern: Doppler-backed scripts.

itx API

OS exposes project capability handles through /api. The app CLI authenticates with the config's admin API secret and can run scripts against a project's itx surface:

# your local Doppler setup, normally shared dev
pnpm cli itx --help

# production
doppler run --config prd -- pnpm cli itx --help

# preview slot 3
doppler run --config preview_3 -- pnpm cli itx --help

# local dev server (while pnpm dev is running)
doppler run --config dev -- pnpm cli itx --help

Use pnpm cli itx run --help to run a script against a project.

Claude + project MCP

Open Claude Code against the OS MCP server for a deployment:

doppler run --config prd -- pnpm cli claude-mcp

The Doppler config picks the environment (prod, preview, or local dev). APP_CONFIG_PROJECT_HOSTNAME_BASES in the config sets the deployed project hostname base (e.g. iterate.app, iterate-preview-3.app); local dev project hosts use <slug>.localhost:<port>. Override with --base-host if needed.

More: apps/os README.

Quick start

pnpm install
doppler setup --config dev --no-interactive   # once per worktree; doppler.yaml scopes every app dir
pnpm dev                                      # attached local OS dev server (http://localhost:<port>)

Use pnpm dev <action> [flags] for dev server lifecycle controls (status, start --detach, attach, restart, kill). The shared dev config and personal dev_<you> configs are fully local and safe for parallel worktrees; use captun, preview, or production for public callbacks. Details: Dev environments.

Before PRs:

pnpm install && pnpm typecheck && pnpm lint && pnpm knip && pnpm format && pnpm test

How to open a PR (branch hygiene, body shape, screenshots that actually render, previews) — and after open: wait for Iterate Review / review bots, address every CI/review comment (fix or reply + resolve), never leave threads standing, never merge on red CI unless the human explicitly said so: Pull requests.

Browser testing: use Playwriter with an isolated headless session by default (or an authorized real-Chrome session when explicitly requested). Give every concurrent agent a unique Playwriter session id. See Browser testing. Keep the Playwriter CLI and skill current.

Repository map

Start here: apps/os/

Other Cloudflare apps (semaphore, …) are supporting services — see docs/architecture.md.

Common commands

doppler setup --config dev --no-interactive   # once per worktree (or --config dev_<you> for personal secrets)
pnpm dev                      # attached local OS dev server at http://localhost:<port> (see docs/dev-environments.md)
pnpm auth:mint                # mint a session as any user/admin (repo root; dev/preview; wrap in doppler run)
pnpm --dir apps/auth dev      # auth app only (when working on auth itself)
pnpm test && pnpm typecheck && pnpm lint && pnpm format

Review rules

Canonical code-review rules live in rules/**/*.md. Before changing or reviewing code, read the rules whose frontmatter files globs match the files in scope and honor their exclusions. The hosted GitHub linter reads these same files; keep shared review policy here, not in the config repo.

How do I…? — Dev environments answers: run local dev (fully local, random port, localhost plus project <slug>.localhost hosts), be any user or an admin (minting), point an isolated visible browser at local dev or a preview, create a preview environment from your machine, and when you need a public callback URL. Doppler/Cloudflare/deploy details: docs/devops-cloudflare-doppler.md.

Documentation

Platform & architecture

• Architecture
• DevOps: Cloudflare And Doppler
• Brand & tone

Development

• Pull requests — opening PRs, absolute screenshot URLs, previews, body hygiene; after open: wait for Iterate Review, address every thread, no merge on red CI
• Browser testing — isolated Playwriter sessions, and reusable test logins
• Dev environments — local dev, minting identities, opening project-scoped or platform-wide operator sessions, browsers for agents, preview-from-local
• Tunnels — public HTTPS URLs for local dev, webhooks, OAuth callbacks, and CI/e2e fixtures
• Coding style
• Depot CI — workflow editing, Depot CLI commands, monitoring/wait loops, logs, dispatch, metrics, secrets, and gotchas
• CLI scripts — how to write normal TypeScript scripts and expose them as CLIs
• Preview CI performance — how the preview deploy+e2e check stays ~2-3 min, the budget guardrail, and how to keep it fast without raising cost
• CI and test telemetry — one PostHog model and health-checked dashboards for Vitest/Playwright/Node tests, failures, retries, phases, GitHub Actions, Depot, and review bots
• TypeScript conventions
• Frontend development — the apps/os programming model: one capnweb capability tree over one WebSocket, the thin itx hooks (useIterateSession/useItx, useItxQuery/useIterateSessionQuery, useLiveState), and LiveView-style live state from Durable Objects
• Design system & React
• Slack testing — real Slack flows; SLACK_CI_BOT_TOKEN trigger actor; channel membership (#slack-agent-e2e-test); preview setup; duplicate-bot caveats
• GitHub production smoke testing — post-recreation config sync, authenticated requests, and webhook routing
• Slack preview OAuth clients — API-first creation and secret handoff for preview Slack apps
• Slack bot token migration — per-app bot token fallback links and Doppler shape
• Testing — test lanes, how to run them against any environment, the canonical env vars, and the retry/timeout policy (one retry layer, fail-fast watchdogs, retry telemetry)
• Vitest patterns
• Domain objects & stream processors
• Writing & testing stream processors — side-effect guarantees, the obligation/reconciler pattern, eviction recovery, staleness policy, and the node test harness
• Playwright specs - instructions for agents writing playwright tests

Tasks & agent docs

• Task system
• Task grooming
• Writing agent docs
• Debugging the OS worker — ITX, agents, scheduler alarms, dynamic workers, and error lookup

App-specific

• OS app
• Kit device installer
• Auth app — public OIDC/oRPC plus OS-only Workers RPC for the org/project directory
• itx — the /api surface and its public contract (types.ts)
• OS worker topology
• OS architecture & operations
• Debugging deployed OS workers
• Doppler-backed scripts
• Project seeds — capture and semantically restore selected projects across deliberate production erases