Development
Plugin
iterate
Monorepo for Iterate's Cloudflare Workers platform. apps/os is the main app — the product dashboard at os.iterate.com.
Plugin Signal68/100Solid
maintained100
capable37
documented75
adopted49
Stats
198
Stars
19
Forks
Active
Maintenance
TypeScript
Language
AGPL-3.0
License
2m ago
Last commit
10mo ago
Created
Repo: iterate/iterate
What's inside
README
1iterate
Monorepo for Iterate's Cloudflare Workers platform. apps/os is the main app — the product dashboard at os.iterate.com.
Irrevocable engineering principle: no deviant system behaviour
We do not accept unexplained, unbounded, or silently tolerated system behaviour. An error is either an explicitly modelled and correctly classified expected outcome, or it is a product defect. The same rule applies to retry storms, stuck work, silent data loss, unexplained latency, state drift, and resource leaks.
- Never normalize an error counter merely because it is noisy or longstanding. Classify every contributing outcome, remove expected outcomes from error telemetry, and fix the rest.
- Never swallow, endlessly retry, or hide failures behind fallbacks or compatibility shims. Recovery must be bounded, observable, and preserve a durable explanation of what happened.
- A healthy request is not enough if it leaves corrupt, stalled, or divergent state behind. Verify the resulting state and the relevant production-shaped telemetry.
- Green tests are necessary but not sufficient. For operational changes, the acceptance proof includes a preview deployment and evidence that its traces, logs, metrics, and state transitions are coherent, correctly classified, and free of new unexplained errors.
Treat any unexplained error volume as a release blocker until evidence proves that each outcome is expected and correctly represented outside the error signal. "Unavoidable error spam" is not a category.
Environments
- The root
envs.tsis 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/itx. 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 format && pnpm test
How to open a PR (branch hygiene, body shape, screenshots that actually render, drafts/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.
Draft PRs don't get a preview deployment (or preview e2e). If you open a
PR as a draft and want a preview environment, add the preview label; marking
the PR ready for review also starts previews. Lease model details:
Dev environments.
Repository map
Start here: apps/os/
| Path | What |
|---|---|
apps/os/ | Main app — product dashboard (os.iterate.com; local dev: localhost:<port>) |
apps/kit/ | Browser installer for supported devices (k.iterate.com) |
packages/iterate/ | iterate CLI — delegates to local source when run inside this repo |
docs/ | Detailed documentation |
tasks/ | Work tracking (markdown + frontmatter) |
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
Development
- Pull requests — opening PRs, absolute screenshot URLs, drafts/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_TOKENtrigger 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
- Cloudflare trace queries — MCP dataset selection, correlation, and span-tree audits
- 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/itxsurface 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
File tree
1755iterate/iterateView on GitHub
.agents/
skills/
adding-a-new-durable-object-mixin/
SKILL.md
cloudflare-traces/
EXAMPLES.md
SKILL.md
code-review/
SKILL.md
creating-an-app/
SKILL.md
debug-mcp-server/
SKILL.md
debug-os-worker/
SKILL.md
fix-stream/
SKILL.md
new-doppler-project/
SKILL.md
os-web-performance/
references/
playbook.md
tanstack-start.md
tooling.md
SKILL.md
recreate-production/
SKILL.md
shadcn/
agents/
openai.yml
assets/
shadcn-small.png
shadcn.png
cli.md
customization.md
evals/
evals.json
mcp.md
rules/
base-vs-radix.md
composition.md
forms.md
icons.md
styling.md
SKILL.md
.bun-version
.claude/
settings.json
skills/
shadcn
.cursor/
environment.json
mcp.json
skills/
debug-os-worker
example-skill
.cursorignore
.depot/
workflows/
autofix.yml
build-preview-ci-image.yml
ci-telemetry.yml
cloudflare-preview-cleanup.yml
cloudflare-preview-gc.yml
cloudflare-previews.yml
deploy-auth.yml
deploy-docs.yml
deploy-kit.yml
deploy-os.yml
deploy-semaphore.yml
deploy-streams-example-app.yml
deploy-tunnels.yml
lint-typecheck.yml
loc-report.yml
mobile-eas-update.yml
mobile-pr-preview-cleanup.yml
mobile-pr-preview.yml
nag.yml
pr-dashboard.yml
pullfrog.yml
release.yml
test.yml
.dockerignore
.gitattributes
.github/
dependabot.yml
workflows/
claude-assistant.yml
pkg-pr-new.yml
.gitignore
.grok/
config.toml
.husky/
pre-commit
prepare-commit-msg
.mcp.json
.nvmrc
.oxfmtrc.json
.oxlintrc.json
.pnpmfile.cjs
.prettierignore
.superset/
config.json
.vscode/
extensions.json
launch.json
settings.json
.vscodeignore
AGENTS.md
apps/
auth/
auth-contract/
package.json
src/
index.ts
worker.ts
tsconfig.json
auth-example/
.env.example
.gitignore
index.html
package.json
README.md
src/
App.tsx
frontend.tsx
index.css
worker.ts
tsconfig.json
vite.config.ts
worker-configuration.d.ts
wrangler.jsonc
AGENTS.md
docs/
cloudflare-access-oidc.md
login-and-bundle-debugging.md
relying-party-auth.md
e2e/
oauth-code-exchange.e2e.test.ts
vitest.config.ts
package.json
README.md
scripts/
deploy.ts
ensure-resources.ts
erase-data.ts
generate-route-tree.ts
generate-wrangler-config.test.ts
generate-wrangler-config.ts
render-admin-seed.ts
seed-oauth-clients.test.ts
seed-oauth-clients.ts
sqlfu.config.ts
src/
components/
auth-redirect-error.test.ts
auth-redirect-error.tsx
config.ts
lib/
client.test.ts
client.ts
relying-party-behavior.test.ts
relying-party-test-support.ts
relying-party.test.ts
server-public.ts
server.ts
session.ts
single-flight.test.ts
single-flight.ts
router.tsx
routes/
__root.tsx
_auth/
_auth.tsx
-projects-data.ts
-projects-shared.tsx
admin/
admin.tsx
clients.tsx
index.tsx
consent.tsx
index.tsx
invitations.$invitationId.tsx
project-access.tsx
projects.{-$organizationSlug}.tsx
-login-account-chooser.tsx
device.tsx
login.tsx
routeTree.gen.ts
server/
auth-jwt.test.ts
auth-jwt.ts
auth-plugins.ts
auth.schema-only.ts
auth.ts
bootstrap-admin.ts
browser-origin.test.ts
browser-origin.ts
db/
definitions.sql
helpers.ts
index.ts
migrations/
.generated/
migrations.ts
0000_create_table_user.sql
0001_oauth_project_selection.sql
queries/
.generated/
index.ts
oauth-client.sql.ts
oauth-project-selection.sql.ts
organization.sql.ts
project.sql.ts
queries.ts
session.sql.ts
tables.ts
user.sql.ts
index.ts
oauth-client.sql
oauth-project-selection.sql
organization.sql
project.sql
session.sql
user.sql
email.test.ts
email.ts
env.ts
id.ts
logout.ts
oauth-metadata.test.ts
oauth-metadata.ts
oauth-project-selection.ts
oauth-resources.ts
oauth-storage.ts
oauth-token-introspection.test.ts
oauth-token-introspection.ts
organization-seed.test.ts
organization-seed.ts
orpc/
index.ts
orpc.ts
routers/
_shared.ts
admin.ts
internal.ts
organization.ts
project.ts
user.ts
platform-admin.ts
project-app-session.test.ts
project-app-session.ts
project-directory.test.ts
project-directory.ts
refresh-token-reuse-grace.test.ts
utils/
hono.ts
worker.ts
styles.css
utils/
auth-app-origin.ts
auth-client.ts
auth-query-options.ts
auth-redirect-error.test.ts
auth-redirect-error.ts
info-row.tsx
initials.ts
login-hint.test.ts
login-hint.ts
query.tsx
tsconfig.json
vite.config.ts
browser-extension/
index.html
package.json
public/
manifest.json
README.md
src/
App.tsx
auth.ts
background.ts
browser-capability.ts
main.tsx
style.css
tsconfig.json
vite.config.ts
docs/
.gitignore
package.json
public/
favicon.svg
README.md
scripts/
deploy.ts
ensure-resources.ts
erase-data.ts
generate-wrangler-config.ts
src/
components/
app-sidebar.tsx
board-header.tsx
board-home.tsx
board-settings.tsx
board.tsx
close-mobile-sidebar-on-navigate.tsx
commit-controls.tsx
deep-link-empty-state.tsx
document-error.tsx
html-document-preview.tsx
stream-events-sheet.tsx
tag-picker.tsx
task-comments.tsx
view-button.tsx
workspace-board-page.tsx
workspace-document-page.tsx
workspace-task-editor.tsx
workspace-task-preview.tsx
workspace-task-sheet.tsx
config-bridge.test.ts
config-bridge.ts
env.ts
health.test.ts
health.ts
lib/
board-engine.test.ts
board-engine.ts
board-model.ts
board-shared.test.ts
board-shared.ts
docs-api.ts
docs-client.ts
project-label.ts
project-rpc.ts
sidebar-state.ts
tasks-api.ts
use-task-commit.ts
use-workspace-board.test.ts
use-workspace-board.ts
package-artifact.test.ts
router.tsx
routes/
__root.tsx
index.tsx
w.$boardId.tsx
w.index.tsx
routeTree.gen.ts
rpc-api-lifecycle.test.ts
rpc-api.test.ts
rpc-api.ts
state.ts
styles.css
tasks-model.test.ts
tasks-model.ts
tasks-rpc-api.ts
test/
cloudflare-workers-shim.ts
worker.ts
tsconfig.json
tsconfig.package.json
vite.config.ts
vitest.config.ts
dummy-petshop/
.dev.vars.example
e2e/
petshop.e2e.test.ts
vitest.config.ts
package.json
scripts/
deploy.ts
ensure-resources.ts
generate-wrangler-config.ts
src/
gateway.test.ts
gateway.ts
generate-wrangler-config.test.ts
github-app.test.ts
github-app.ts
graphql-login.test.ts
graphql-login.ts
mcp.test.ts
mcp.ts
pets.ts
rpc.test.ts
rpc.ts
seal.test.ts
seal.ts
state.ts
test/
cloudflare-workers-shim.ts
worker.test.ts
worker.ts
tsconfig.json
vitest.config.ts
kit/
.gitignore
package.json
public/
favicon.svg
README.md
... 1600 moreShowing a partial view of a very large repo.
FAQ
iterate is a Claude Code plugin with hand-picked skills for development work, indexed on Flowy. Install it with the command on its page. Its skills do not fire on their own yet. Request auto-invocation to have Flowy route them as you prompt. Free and open source.
- What is iterate?
- Monorepo for Iterate's Cloudflare Workers platform. apps/os is the main app — the product dashboard at os.iterate.com.
- How do I install iterate?
- Run these in Claude Code: . Then prompt normally.
- Does iterate auto-invoke its skills?
- Not yet. It is indexed on Flowy as a plain plugin. Request auto-invocation on its page and Flowy will route its skills for you as you prompt.
- Is iterate free?
- Yes. Flowy is free and open source, with nothing gated. You can read every skill in full before you install.