thirdshift

A factory that turns a GitHub issue into a ready-for-review pull request, or on request a merged one, by running unattended agent sessions. The humans are the day shift; the agents work the third shift, overnight, while you do something else.

Quality over quantity: a pull request marked ready for review is one the factory stands behind. When it can't stand behind the work, it preserves the work and leaves a draft.

Read the user manual here on GitHub or on thirdshift.app. Both come from the same Markdown. For a visual introduction, see How thirdshift works.

Install

curl -LsSf https://github.com/JacobStephens2/thirdshift/releases/latest/download/thirdshift-installer.sh | sh

The installer puts a single binary in ~/.local/bin; no Rust toolchain or checkout of this repo is needed. Supported: x86_64 Linux (Rocky, Ubuntu and WSL2) and Apple Silicon macOS. See supported versions and other installation methods.

Have git and authenticated gh and a Harness installed: Claude Code by default, or Codex, Antigravity CLI, Grok Build, Muse Code or OpenCode. Set git's user.name and user.email and make sure it can push. Prerequisites and permissions covers setup and access: sessions run unattended as your user, with access to that account's files, credentials and tools.

thirdshift setup     # choose defaults
thirdshift update    # update a shell-installer copy

Usage

From a clone of the issue's repository, on the branch you want the pull request to target:

cd ~/repos/widgets
thirdshift https://github.com/acme/widgets/issues/7

The Run works in its own worktree, implements and reviews the issue, opens a pull request, and keeps it mergeable and green. It leaves the pull request ready for your review; thirdshift merge <Issue URL> also merges it. Your checkout's uncommitted changes stay out of the Run. Push any Base branch commits first.

Use thirdshift help for the command reference, or read Run behavior, command options and failure recovery.

Workflows

Start with	Workflow and details
One GitHub issue	Run and Merge run
An issue with sub-issues	Spec run: works through Tickets in dependency order
Architecture improvements	Architect run: reviews, publishes a plan and builds it
An issue marked ready	Pickup run: takes the lowest-numbered Ready issue
A security audit	Security run: records findings privately; can fix one reproduced finding

The operating system schedules Architect, Pickup and Security runs. See scheduling, Weeding and Fencing.

Console on a server

Set the machine's address, fixed localhost port and sign-in allowlist in ~/.thirdshift/config.toml:

[console]
address = "https://console.example.com" # a DNS name, with or without https://; no port or path
port = 8711
allowed_emails = ["you@example.com"]

Point that DNS name at the machine, then run these commands as the owner:

thirdshift console password --email you@example.com
thirdshift console install > install-console.sh
# Read the script, then install it:
sudo sh install-console.sh

console install only prints a script. On Linux it prefers a running Caddy or Apache service; otherwise it checks for caddy, apache2ctl or httpd on PATH. The script writes thirdshift-console.service, running the installed binary as you with your HOME and automatic restarts. Only the script needs root. It enables the service, then restarts the proxy.

For Caddy it writes /etc/caddy/sites/thirdshift-console.caddy, imports the sites folder from /etc/caddy/Caddyfile if needed, and disables proxy buffering with flush_interval -1. Caddy handles HTTPS. It restarts, rather than reloads, Caddy to preserve HTTP/3 on Android. For Apache it writes the port-80 site under /etc/apache2/sites-available or /etc/httpd/conf.d, preserves Host, forwards the request protocol and disables gzip on the Console's event streams. Install certbot with its Apache plugin first; the script runs certbot --apache -d <name>. Debian's module/site helpers are included. On an httpd machine, enable proxy, proxy_http, headers, ssl and setenvif and permit proxy connections in the host's SELinux policy first.

With neither proxy, the script installs a localhost-only service with --no-sign-in and prints an SSH tunnel command. No address or accounts are needed for that mode. Run the tunnel on your computer and open the printed http://localhost:<port> address. On other operating systems, run thirdshift console --no-sign-in directly and use the same tunnel; only the Linux installer assumes systemd.

nginx

For nginx, use the generated service but remove --no-sign-in from its ExecStart before installing it. Configure the allowlist and password above. Obtain an HTTPS certificate for your DNS name, then add a site like this, adjusting the name, certificate paths and port:

server {
    listen 443 ssl;
    server_name console.example.com;
    ssl_certificate /etc/letsencrypt/live/console.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/console.example.com/privkey.pem;

    location / {
        proxy_pass http://127.0.0.1:8711;
        proxy_http_version 1.1;
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header Connection "";
        proxy_buffering off;
        proxy_cache off;
        gzip off;
        proxy_read_timeout 1h;
    }
}

Run sudo nginx -t, then sudo systemctl restart nginx on a systemd host. The Console still binds only to 127.0.0.1; nginx terminates HTTPS and passes live updates without buffering.

Documentation

• Configuration, Harness, Model and Effort, and email notifications.
• Machine status, showing Commands and reading logs, and stopping a Command.
• The local Console: thirdshift console --no-sign-in serves the Inbox on localhost.
• Building and testing and releasing.
• Exact prompts and Factory skills, also readable on the site.
• Domain vocabulary and architectural decisions.
• Open issues for known gaps and planned work.

Credits and license

Released under the MIT License. Factory skills include work by Matt Pocock, Dex Horthy and Cloudflare. See full credits and license notices.

Links from the former README manual

These section links keep older bookmarks useful. The complete explanations now live in the user manual.

• What a Run does
• The Claim
• When the Claim ends
• Status
• Machine status
• Show and read one Command
• Updating
• Supported platforms
• Prerequisites
• Unattended sessions
• What sessions leave behind
• Usage and cost
• User config
• Harness, Model and Effort
• Email
• Run notifications
• Stopping a Command
• Logs
• Foreign commits in a Merge run
• Base fix
• One Base fix per Base branch
• Continuation
• Failed runs
• An Inherited failure links the Base branch's checks
• Spec runs
• Architect runs
• One Run notification
• No Strong candidate
• An Architect idea waits for triage
• A Ready issue goes first
• One at a time
• One Architect plan at a time
• On a schedule
• Weeding
• Security runs
• Security review
• Fencing
• Pickup runs
• The Claim limit
• The Sweep
• Why an issue was passed over
• One Run notification for the issue taken
• A Pickup run on a schedule
• Building from source
• The Rust version
• Releasing