🎼 watchloop

Tickets in. Reviewed pull requests out. Nobody watching.

A Claude Code skill that runs your Linear board
overnight and hands you a morning of pull requests to read.

What makes it different

The whole interface is two surfaces. A ticket in Linear, and a comment on a
pull request. There is no chat window to steer, no label to remember, no plan to
approve inside the tracker. To change the direction of the work you comment on the
PR, and the loop reads it, answers it by name, and acts on it. That works on a
merged PR too, which is where it earns its keep: merge, note the follow-up work
the PR spotted but left out of scope, and the loop turns your note into the next
ticket by itself. Teammates can steer it the same way, on purpose.

Draft means something. A PR leaves draft only on evidence — a review, a fix
pass over that review, a screenshot when a user can see the change, no merge
conflict, and CI green on the head commit. It never leaves draft on an agent's
say-so. So what is not a draft in the morning is what is actually ready, and the
drafts are the pile you can ignore until you have time.

Idle costs nothing. Nothing runs until there is work. The gate probes
capacity, your open PRs and the Linear ready column every 60 seconds in pure
shell — no model call, no turn started. A night with an empty board costs
nothing at all, not "not much".

It runs on your machine, on the Claude you already pay for. No hosted sandbox,
no per-session credit, no repo access granted to a third party. That also means it
uses whatever the machine has: it measures free memory every probe and runs as many
agents as will really fit — one per LO_RAM_PER_AGENT gigabytes — so parallelism
is bounded by your laptop rather than by a plan.

A person decides every merge. Author and reviewer are the same model, so "no
blockers left" is evidence about care, not proof of correctness. The loop stops at
a reviewed, non-draft PR. It merges only when a person on the merge list
(LO_SLACK_MERGE_EMAILS) names that PR in Slack. The one standing order is the fix
of a small break of the base branch build: a type, lint or test failure with one
cause and no change a user sees. The loop never merges into the default branch.

What it does, in order

1. The gate blocks until there is work — capacity, your PRs, the Linear ready
   column.
2. An agent takes the ticket, moves it to In Progress, branches, opens the
   draft PR before it writes any code, writes the code, tests it in a real browser,
   and stops.
3. A second agent reviews that PR in a fresh context — it has the diff, the
   ticket and your repo's agent guide, and none of the reasoning the author talked
   itself into. It logs the review as one entry in the PR's single log comment, makes exactly
   one fix pass over what it found, and corrects the PR body where the diff moved past it.
4. The PR leaves draft on the five gates, or stays a draft.
5. Your comment re-opens any of it. An unanswered comment on one of its PRs
   outranks every other kind of work on the next tick.

Every agent gets its own repo clone, Terminal window and real Chrome, which is
why front-end tickets work here: the screenshots on the PR come from driving the
actual screen, not from a headless guess.

The mechanics — the shell gate, and how the loop tells your comments from its own —
are in HOW-IT-WORKS.md.

Who this is for

People who already run coding agents locally and would rather spend a machine than
a per-seat credit. The install is honestly longer than "connect GitHub", and the
constraints are real:

• macOS or Linux, and Claude only. It drives Claude (Opus) agents through
  multiclaude and reads Linear
  through agent-codemode, which
  reads Claude Code's OAuth from the macOS Keychain, or from
  ~/.claude/.credentials.json on Linux.
• A Linux server has no real Chrome. Its agents run in screen sessions
  without Claude in Chrome, so they test front-end work with headless Playwright.
• One machine. Parallelism caps at what one laptop's memory holds.
• --dangerously-skip-permissions is required. The agents run unattended with
  permission prompts off. That is the point, and it is also the risk — give the
  loop a repo where the worst an agent can do is open a bad PR.
• Your repo needs its own agent guide (CLAUDE.md). The prompt handed to each
  agent is short because the guide supplies branching, local checks, the PR
  template, testing and security.

Install and run

You also need gh (authenticated), jq, and the
Linear MCP server connected to the session that runs
the loop.

git clone https://github.com/janwilmake/watchloop.git \
  ~/.claude/skills/watchloop
cd ~/.claude/skills/watchloop
cp .env.example .env && $EDITOR .env

Installed it before 15 Oct 2026, as linear-orchestrator? Move both
folders, point the remote at the new name, and start it with /watchloop:

mv ~/.claude/skills/linear-orchestrator ~/.claude/skills/watchloop
mv ~/.claude/linear-orchestrator ~/.claude/watchloop
git -C ~/.claude/skills/watchloop remote set-url origin https://github.com/janwilmake/watchloop.git

Then start it from your repo:

cd /path/to/your/repo
claude --dangerously-skip-permissions

/watchloop

status reports what is running; stop ends the loop and lists the PRs it
produced.

Run it on a Linux server

The loop also runs on a Linux server (tested on Ubuntu 24.04), which keeps it
running when the laptop sleeps. On the server:

• Install git, gh, jq, screen, Node and Claude Code, and log in to gh,
  Claude Code and the Linear MCP (claude mcp login linear) as the account the
  loop acts as. agent-codemode reads the Linear login from
  ~/.claude/.credentials.json.
• Mark the agent slot folders ~/.claude/agents/agent-N as trusted in
  ~/.claude.json, and accept the Bypass Permissions warning once. Otherwise
  each new agent stops at a question nobody answers.
• Optional, for front-end work: Chrome on a virtual display (Xvfb), with the
  Claude extension signed in and x11vnc serving that display on localhost:5900.
  cca passes --chrome only when Chrome is installed; without it, agents test
  with headless Playwright.
• Start the loop in a screen session, so it outlives your ssh connection:
  screen -dmS orchestrator bash -lc 'cd /path/to/repo && claude --dangerously-skip-permissions "/watchloop start"'.

To watch it from a Mac or a Linux desktop, set LO_REMOTE_HOST (and, for the
browser view, LO_REMOTE_VNC_PASSWORD_FILE) in .env and run
./watch-remote.sh. It opens one terminal window per agent and the
orchestrator, adds windows for new agents, closes a window when its agent ends,
and opens a VNC view of the server's Chrome: Screen Sharing on a Mac; TigerVNC's
vncviewer, else Remmina, on Linux. On Linux, LO_REMOTE_TERMINAL picks the
terminal (for example kitty or gnome-terminal --); without it the script
takes the first one it finds. Ctrl-C, or ./watch-remote.sh stop, closes every
view; the loop keeps running. Close a single window with the window manager,
never Ctrl-C: keys typed in a window reach that agent.

Configure with .env, not the skill file

All the values that change per user live in .env beside SKILL.md. It is
gitignored, so your paths and names never reach the repo — which is what lets the
skill be a symlink to a checkout:

LO_REPO="/path/to/your/repo"   # local checkout the agents clone from
LO_BASE="dev"                  # base branch
LO_TEAM="Your Team"            # Linear team name
LO_PREFIX="ENG"                # ticket id prefix
LO_TIER1="Preferred Assignee"  # display name. ONLY these assignees are taken
LO_TIER2="Fallback Assignee"   # display name
LO_ALLOW_UNASSIGNED="0"        # 1 = also take unassigned tickets (default off)
LO_ALLOW_BACKLOG="0"           # 1 = fall to Backlog when Todo is empty (default off)
LO_OWNER=""                    # this instance's tag; required if two share a repo
LO_RAM_PER_AGENT="2.5"         # GB per agent (claude + vite + chrome)
LO_MAX_AGENTS="0"              # ceiling on concurrent agents; 0 = unlimited
LO_FEEDBACK_SINCE="2026-08-18T17:00:00Z"   # the day you installed this

LO_RAM_PER_AGENT is the one people get wrong: it is a divisor, not a threshold.
Every tick spawns free memory / LO_RAM_PER_AGENT agents — all of them, not one,
so the loop reaches full capacity on its first tick with work. LO_MAX_AGENTS
defaults to 0, meaning memory is the only ceiling; set a positive number to
hold part of the machine back. The default divisor assumes one Claude session,
one dev server and one Chrome — a stack with Docker or a local database costs far
more, and the probe cannot detect that.

What it takes is narrow on purpose. Only tickets in Todo assigned to
LO_TIER1 or LO_TIER2. Unassigned tickets and the Backlog column are each
one switch away (LO_ALLOW_UNASSIGNED, LO_ALLOW_BACKLOG) and both default to
off — a name on a ticket in a ready column is somebody deciding it is ready, and
that decision is the signal the loop runs on.

Running two orchestrators against one repo — say one per laptop — needs
LO_OWNER set to a different tag in each. Splitting by assignee separates them
on the tracker, but not on GitHub: every instance writes the same 🌙 marker,
and that marker is what decides which PRs a loop reviews, promotes and answers
comments on. With LO_OWNER the marker becomes 🌙 lo:<owner> and the two stop
overlapping. Both instances must run this version for the split to hold — an
older one matches the bare marker and still adopts everything.

Both gate.sh and the tick read these, so there is nothing to edit inside
SKILL.md.