Owlshift Owlshift

Adopt a project on GitHub Issues

This page takes you from an installed owlshift to a first pull request made by agents on your repository, with the tickets kept as the repository's own GitHub issues, then to the background service that works the issues you admit. It takes about fifteen minutes, plus the time the agents work.

The outputs below come from real runs. Paths and some long lines are shortened, marked …; your repository's name, paths and numbers will differ.

Before you start

1. Prepare the repository

Little is needed on GitHub itself; owlshift init does the rest.

Everything Owlshift writes on GitHub, comments and labels included, is written through your own account, marked by GitHub as made with owl-shift. GitHub does not notify you of your own comments, so Owlshift shows a desktop notification when an issue waits for you.

2. Write the project file: owlshift init

In your clone, at the repository's root:

cd ~/code/shop
owlshift init

At a terminal, init asks for what no flag gave: answer 2 (or github) when it asks where the tickets live, or pass --tracker github to skip the question. In a script nothing is asked, and the tracker is Linear unless --tracker github says otherwise. init does five things, in this order:

  1. It reads the repository's root files (Cargo.toml, package.json, pyproject.toml, Makefile) to suggest a gate: your lint, formatter and test commands. It never runs them. It shows the gate found: press Enter to keep it, or type your own commands, one per line, an empty line ending them; with --gate, one per command, as in owlshift init --tracker github --gate "make lint" --gate "make test", nothing is asked.
  2. It signs you in to GitHub through Owlshift's GitHub App. It prints a code and asks you to open https://github.com/login/device and enter it. If the app is not installed on the repository, it prints the install link and waits until you have installed it. If the code expires before you enter it, init says so and exits with an error: run it again for a new code.
  3. It asks for the token agent runs log in to Claude Code with. Make it in another terminal with claude setup-token, then paste it. It is asked once per machine. Owlshift never asks for a model API key.
  4. It checks that the repository's issues answer, creates the labels that are missing, one line each, and reads your GitHub account's numeric id, which it writes as the one admitter: the person whose agent:ready label admits an issue.
  5. It writes a commented owlshift.toml.

The secrets go to the system keychain, never to a file. If the issues do not answer, init says why and writes no file. On a repository that had none of the labels, it printed:

Created the label "agent:ready" on GitHub.
Created the label "agent:working" on GitHub.
Created the label "agent:needs-input" on GitHub.
Created the label "agent:review" on GitHub.
Created the label "agent:proposed" on GitHub.
Wrote ~/code/shop/owlshift.toml: review it, then commit it.

and the [tracker] table of the file it wrote reads, its comments and commented-out keys left out:

kind = "github"
admit = "ready"
admitters = ["24303327"]

[tracker.states]
ready = "agent:ready"
working = "agent:working"
needs_input = "agent:needs-input"
review = "agent:review"

Read owlshift.toml: it lists every setting, each with a comment above it that says what it decides, its values and its default; a setting commented out with its default value changes nothing once uncommented. The configuration reference lists the same settings, and those of your personal file. Check the gate under [stack], which every agent's work must pass, and admitters under [tracker]: add the numeric ids of the other people whose label should admit an issue (gh api users/<login> --jq .id prints one). Then commit the file and push it to your default branch: the background service reads the project file of the default branch, and each run the file of the commit its branch starts from.

3. Check the machine and the project: owlshift doctor

owlshift doctor

Each line is marked ✓ (fine), ! (a warning, which never blocks owlshift do) or ✗ (a problem to fix first); the end of the report says why each problem matters and how to fix it. Run it again until it ends with Ready. The lines about the tracker, on a project whose file was written before the labels existed:

  ✓ tracker access      the GitHub credential reads the issues of
                        github.com/…
  ! tracker labels      github.com/… has no label
                        "agent:ready", "agent:working", "agent:needs-input",
                        "agent:review", "agent:proposed"
                        Does not block `owlshift do`: a stage whose label is
                        missing does not show, and a priority's never reads. Run
                        `owlshift init`, which creates the stage labels and
                        "agent:proposed"; create a priority's label on GitHub
                        (Issues > Labels).
  ! drain admission     `admitters` is not set under `[tracker]`
                        Does not block `owlshift do`: `owlshift watch --drain`
                        refuses to start, and would admit nothing, until it is
                        fixed. List under `admitters` the numeric ids of the
                        GitHub accounts whose label admits an issue; with none,
                        no issue is ever admitted. `owlshift init` writes the
                        account it signs in as.

tracker access must be ✓: a ✗ there says whether the app's installation has not accepted Issues, the repository is not in the installation, or issues are turned off. The sandbox line must be ✓ too: it says that agent runs are confined, with sandbox-exec on macOS or bwrap on Linux.

4. Check the gate: owlshift gate

owlshift gate

This runs the gate once, the way it runs on an agent's work: in a fresh worktree of your default branch, confined, with nothing of your environment but what the project declares. A gate that passes on your laptop can fail here, because a tool is missing from the PATH, a test reads your home folder, or the dependencies were never installed; fixing it now saves an agent's run. The output names each command, its status and time:

The gate of 2fe46e01ea43 (origin/main), from your owlshift.toml, the commit having none, in a fresh worktree, confined as a Build's gate:
  test -f README.md
Its whole output goes to ~/Library/Application Support/owlshift/projects/github.com/…/gate/run/gate.log.
$ test -f README.md
  ok, 0.0 s
Gate green on 2fe46e01ea43: 1 command in 2.2 s.

When a gate needs its dependencies installed first, list the install commands under stack.setup in owlshift.toml (the file's comments show how), and the caches they read under stack.caches. The gate runs with your home folder closed: a package manager reaches its cache only through stack.caches, read-only, and only on a machine whose personal configuration lists that folder in allow_caches. Until it does, every run and gate refuses the project, and owlshift doctor gives the lines to add.

If the gate fails here though it passes on your laptop, or npm fails with EPERM, see Troubleshooting.

5. Run a first ticket: owlshift do

Open an issue for something small and clear, such as a typo to fix or a line to add to the README, and assign it to yourself. An issue's ticket id is its number without the #:

owlshift do 12

owlshift do works in the foreground and says what it does. It runs the issue through design, design review, build and verify, each step by a fresh agent run, with the gate run on the result; it prints each step as it goes. It works in its own clone and worktrees under Owlshift's data folder, never in your checkout. It pushes a branch owlshift/12 and opens a pull request whose description ends with Closes #12, so merging it closes the issue. The issue's labels move as it goes, and Owlshift comments on it: the plan, then the delivery report.

A ticket can also wait rather than run. Owlshift never builds two changes to the same files at once: while one of its pull requests that touches those files is open, a new ticket that would touch them waits, and owlshift do says so and stops. An issue whose plan touched the README, run while an earlier pull request on the README was open, ended with:

Not run: 102 waits: pull request #101 holds zone `README.md`, which its Build would take: its Build is admitted once pull request #101 no longer holds it. `owlshift why 102` says why it waits.

Merge or close that pull request, then run owlshift do 102 again. Under owlshift watch --drain or the service, Owlshift also posts a [owlshift] WAITING comment on the issue saying what it waits for, and goes on by itself once that is gone.

Review the pull request and merge it yourself: Owlshift never merges unless you turn merge on green on for the project ([forge] merge in owlshift.toml).

6. Answer a question

When a run needs a decision only the assignee can make, Owlshift comments on the issue with the questions, under a title [owlshift] QUESTIONS · round 1, moves the issue to agent:needs-input, and shows a desktop notification.

Answer in a comment on the issue, as its assignee, one answer per question. An answer counts once you have left it unedited for 10 minutes (the project's policy.quiet_window_minutes changes that), or at once when it ends with go. Then, while the background service does not serve the project:

owlshift continue 12

Once the service serves the project (below), it picks your answer up by itself. Either way your answers are checked first: if one is missing or unclear, Owlshift asks again; otherwise the work goes on to a pull request. Answer as many rounds as it takes: there is no limit.

If an issue stops for a reason it cannot settle itself, such as a run that fails twice, it is parked: a comment marked PARKED says why. Fix what it names, then reply continue on the issue as its assignee, alone in the comment, or run owlshift continue 12.

7. Let the service work the backlog: owlshift start

With a first pull request through, let Owlshift take issues as you admit them:

owlshift start

start registers the project and starts the background service for this login session; owlshift start --at-login also starts it at each login. On a clean Debian 12 machine it printed:

acme/shop is served from /home/dev/shop. Started the daemon for this session (pid 8671): its output is in /home/dev/.local/share/owlshift/service/daemon.log; `owlshift stop` stops it.

The service reads the project file of your default branch, never your checkout's, so push owlshift.toml first. Otherwise owlshift status says so, and the service tries again every minute:

acme/shop (from /home/dev/shop)
  not served: origin/main (7fd1a60b01f9) holds no owlshift.toml

From then on:

103 [ready] in acme/shop
  2026-11-13T13:23:13.899429Z waits: the project's slot is held by 102
now: the project's slot is held by 102

Priorities are labels too, optional: name them under [tracker.priorities] in owlshift.toml and create them on GitHub; without them every issue has the same priority.

How much Owlshift decides alone

Out of the box Owlshift asks rather than guesses, works one issue at a time and never merges. These keys of owlshift.toml, each explained in the file, let it do more alone:

Whatever they say, a question on security or on an irreversible action always reaches a person, and so do the categories listed in policy.always_human. Under merge on green, an issue that asked a security question is never merged by Owlshift, nor one whose other such question no person settled.

Next