Skip to content
wrktrdocs

For agents

If you’re a coding agent working in a wrktr repo, this is the contract. wrktr skill install puts the same guidance where Claude Code and other agents look for skills, and wrktr skill show prints it.

The loop. Work in the worktree you were given. You don’t need git commit or git push, the daemon does both; they’re harmless, but don’t rewrite pushed history (rebase, push --force, commit --amend).

  1. Edit files in .wrktr/worktrees/<branch>/. The daemon commits after 30 seconds of quiet and pushes.
  2. wrktr ci show --wait blocks until the head’s checks finish, and exits 1 unless they passed.
  3. Read .wrktr/FEEDBACK.md (or wrktr feedback show): open review threads and failing checks.
  4. Fix, then wrktr feedback reply <id> "<what you did>", and wrktr feedback resolve <id> when it’s done.
  5. wrktr land --when-ready, and the server lands the branch once it’s ready.
  6. wrktr env wait dev --branch <name>: once it exits 0, open the url it prints and check your change is there. If it exits non-zero, tell the user what it printed (1: didn’t go out or isn’t served; 2: dev isn’t set up).
  7. If .wrktr/BEHIND.md appears, merging the default branch in conflicted: git fetch wrktr && git merge wrktr/<default>, resolve, commit.

Rules that don’t change.

  • --json prints exactly one JSON value on stdout; a failure prints {"error": {"tag", "message"}} on stderr.
  • Exit code 0 means the command did what it was asked; non-zero means it didn’t (wrktr env wait uses 2 for an environment that isn’t set up). Act on the exit code, not the wording.
  • --project <org>/<name> works without a clone; name the branch too (--branch, or the branch argument).
  • WRKTR_TOKEN signs the CLI in without login, for CI and sandboxes.
  • Every command takes --help, and every command and flag is in the CLI reference.
Terminal window
wrktr status --branch fix-login --json | jq -r '.review.verdict'   # approve, changes or comment
wrktr status --project nope/nope --branch x --json                   # exit 1
# stderr: {"error":{"tag":"ProjectNotFound","message":"Project Not Found"}}

The same guidance ships inside the CLI, matched to its version: wrktr skill show prints it, and wrktr skill install puts it where Claude Code and other agents look for skills.