Skip to content
wrktr docs

The daemon

The daemon is what lets agents just edit. It runs on your machine and keeps every worktree of every registered repo in sync:

  • Commits a worktree once it’s been quiet for a moment: 30 seconds with no file changes, by default (quietMs in wrktr.json, or --quiet-ms). Its commits are titled checkpoint: <n> files (<paths>).
  • Pushes each commit, which runs the branch’s checks and then the review agent.
  • Merges the default branch in as it moves, so the branch stays current.
  • Writes the files agents read into each worktree (below).

It never commits .env files (anything named .env or .env.*), or files larger than maxFileBytes (5 MB by default); it logs them once instead.

You don’t need git commit or git push. They’re harmless, but don’t rewrite pushed history (git rebase, git push --force, git commit --amend on pushed commits): that fights the daemon.

Running it

Section titled “Running it”
Terminal window
wrktr daemon install     # run it as a login service (macOS), from a stable copy of the CLI
wrktr daemon status      # what it's syncing, repo by repo and worktree by worktree, with any errors
wrktr daemon logs -f     # follow its log
wrktr daemon restart
wrktr daemon upgrade     # move the service to this CLI's build, and restart it

wrktr setup installs it for you. The service is a macOS LaunchAgent; elsewhere, run wrktr daemon in the foreground under your own supervisor (systemd, a container’s entrypoint).

wrktr init, wrktr clone and wrktr fork register a repo with the daemon.

The files it leaves in .wrktr/

Section titled “The files it leaves in .wrktr/”

Each appears in a worktree when it applies, and is removed once it no longer does.

File Meaning What to do
.wrktr/FEEDBACK.md Open review threads and failing checks Fix each in the code, then reply or resolve
.wrktr/BEHIND.md Merging the default branch conflicted (the daemon aborted) git fetch wrktr && git merge wrktr/<default>, resolve, commit
.wrktr/CONFLICT.json A rebase onto the remote stopped on conflicts Resolve the files, then git rebase --continue
.wrktr/DAEMON.md The daemon can’t sync this worktree Fix the reason it gives
.wrktr/LANDED.md The branch landed, but this worktree has newer work Carry on (it’s a new change), or wrktr branch rm <name>

The web app shows when a worktree is stopped on a conflict or failing to sync, from what the daemon reports.