Skip to content
wrktr docs

The starter

wrktr/starter is the smallest project to try wrktr on: a palette generator on a Cloudflare Worker, with two checks. Press Space for five colors in harmony, picked in OKLCH so they look even to the eye. It’s live at wrktr-starter.wrktr.workers.dev.

Start your own

Section titled “Start your own”

The CLI needs only git. The app needs Node 24 or later, for its tests and Wrangler.

Terminal window
curl -fsSL https://wrktr.com/install | sh   # or: npm i -g @wrktr/cli
wrktr setup wrktr/starter                   # sign in, run the daemon, teach your agents, fork the starter
cd starter

wrktr setup wrktr/starter signs this machine in, runs the daemon, installs the agent skill, and forks the starter into your personal organization, cloned into ./starter. Your fork is a private project that remembers where it came from, with the starter as its upstream remote, so git pull upstream main brings in later changes.

What’s in it

Section titled “What’s in it”
File What it is
public/ The page: index.html, styles.css and app.js, served as static assets. No build step.
src/palette.ts Palettes: harmonies in OKLCH, converted to sRGB hex, from a seed.
src/app.ts The API the page calls: GET /api/palette?seed=&mode=.
src/*.test.ts Tests with node:test: the API, the palettes, and the page itself in happy-dom. No browser.
src/index.ts The Worker’s entry point.
wrktr.json What wrktr runs: npm ci in each new worktree, the two checks, and two environments.
AGENTS.md How agents should work here.
wrangler.jsonc The Worker’s config, for npm run dev and npm run deploy.
Terminal window
npm test              # the tests
npm run typecheck     # TypeScript
npm run dev           # the app on http://localhost:8787

Its wrktr.json

Section titled “Its wrktr.json”
{
  "install": "npm ci",
  "ci": {
    "setup": "npm ci",
    "cacheKeyFiles": ["package-lock.json"],
    "checks": [
      { "name": "test", "run": "npm test" },
      { "name": "typecheck", "run": "npm run typecheck" }
    ]
  },
  "environments": {
    "dev": {
      "on": "land",
      "url": "https://wrktr-starter-dev.wrktr.workers.dev",
      "secrets": ["CLOUDFLARE_API_TOKEN"],
      "steps": [{ "name": "deploy", "run": "WRANGLER_SEND_METRICS=false npm run deploy:dev" }]
    },
    "production": {
      "on": "promote",
      "from": "dev",
      "url": "https://wrktr-starter.wrktr.workers.dev",
      "secrets": ["CLOUDFLARE_API_TOKEN"],
      "steps": [{ "name": "deploy", "run": "WRANGLER_SEND_METRICS=false npm run deploy" }]
    }
  }
}
  • install runs in every new worktree, so an agent’s worktree is ready to test from the start.
  • ci installs once per checkout (setup), reuses that install while package-lock.json is unchanged (cacheKeyFiles), then runs test and typecheck on every push. Both are required to land.
  • environments deploys every landing to dev, and a promote ships what dev has to production. Both deploy with Wrangler and need a Cloudflare API token, which your fork doesn’t have yet: see Deploy your fork.

Its AGENTS.md

Section titled “Its AGENTS.md”

The starter tells agents how to work there, in a few lines: work in the worktree you were given, don’t commit or push, run npm test and npm run typecheck before calling a change done, read .wrktr/FEEDBACK.md, and land with wrktr land --when-ready. wrktr skill show prints the full guide the agent skill installs. A short AGENTS.md like this is worth adding to any repo you put on wrktr.

Next: give an agent a task.