Quickstart

This assumes you’ve installed the CLI and run wrktr setup. To try wrktr without a repo of your own, start from the starter instead: wrktr setup wrktr/starter.

1. Put a repo on wrktr

In the repo you want to work on:

wrktr init

init creates a wrktr project for the repo and pushes it (or links the repo to an existing project). It registers the repo with the daemon and sets up wrktr credential, so plain git pull and git push work against the remote. --name and --org pick the project’s name and organization.

To work on a project that’s already on wrktr, clone it instead:

wrktr clone acme/api

2. Tell wrktr what to check

Add a wrktr.json at the repo root and commit it. The ci block is what every push runs:

{
  "install": "npm ci",
  "ci": {
    "setup": "npm ci",
    "cacheKeyFiles": ["package-lock.json"],
    "checks": [
      { "name": "test", "run": "npm test" },
      { "name": "typecheck", "run": "npm run typecheck" }
    ]
  }
}

install runs in each new worktree; ci.setup runs once per checkout in CI, before the checks. See Checks and the wrktr.json reference.

3. Start a branch and hand it to an agent

wrktr branch new fix-login

This makes a branch in its own worktree, .wrktr/worktrees/fix-login, from the latest default branch, runs install there, and pushes it. Open your coding agent in that directory and give it the task. Start a second branch for a second agent at the same time: each has its own worktree.

The agent just edits. The daemon commits after 30 seconds of quiet and pushes, and each push runs the checks and then the review agent.

4. Follow it

wrktr status --branch fix-login     # head, checks, the review, open threads, conflicts
wrktr ci show --wait                # wait for the checks; exits 1 unless they passed
wrktr feedback show                 # what the review asked for

Review threads and failing checks also land in the worktree, in .wrktr/FEEDBACK.md, where the agent reads them, fixes the code, and replies:

wrktr feedback reply <id> "Fixed: the token now refreshes before it expires."

Or watch it all in the browser, on the project’s page at wrktr.com.

5. Land it

wrktr land --when-ready

The server lands the branch, as a merge commit on the default branch, as soon as its checks pass, the review approves its head and no blocking thread is open. Nothing has to keep running. wrktr land lands now if it’s ready, and says what’s missing if it isn’t. See Landing.

Next

• Give an agent a task: the same loop on the starter, step by step.
• Environments: deploy every landing to dev, and promote to production.