glorp

Git Loop fOr Robot Patchers — a near automated loop for building. Open issues on GitHub, let the 🤖s handle the rest.

glorp runs a daemon that watches (push or poll) GitHub repositories or project boards for issues and spins up a coding agent for each detected issue with a configurable concurrency, tracking the issue to completion.

[!NOTE]
glorp launches agents non-interactively. Agent sandbox and permission controls remain enabled by default. --yolo disables those protections; use it only with repositories and issues whose contents you trust.

Prerequisites

Install and configure these tools before installing glorp:

• GitHub CLI (gh), authenticated with access to every repository glorp will watch.
• Node.js and npx. The installer uses npx to install the bundled gh-fix and gh-discuss skills through skills.sh.
• ngrok for the default webhook mode. Installing it is optional: glorp runs npx ngrok when no ngrok is on PATH, so the Node.js above is enough. Configure ngrok authentication before starting glorp either way. ngrok is not required with --poll.
• A Chromium-based browser (Chrome, Chromium, or Edge) for --browser mode. Only required with --browser, which needs no ngrok tunnel and no extra token. Safari cannot be used: it does not speak the DevTools Protocol. Browser mode reads GitHub as a signed-in user would, and glorp's browser profile starts signed out, so run glorp auth once before watching anything private; see glorp auth.
• At least one supported coding agent. glorp ships definitions for Codex CLI (codex), Claude Code (claude), Gemini CLI (gemini), Meta Muse Code (muse), opencode (opencode), and Cline (cline). Any other compatible CLI can be added without waiting for a glorp release by declaring it in .glorp.config.json; see the agent definitions reference.

The Unix installer also requires curl and standard archive tools. The Windows installer requires PowerShell.

Authenticate the GitHub CLI before running glorp:

gh auth login

Browser mode needs no gh scopes of its own, but its browser profile does need a GitHub session. Sign it in once, before the first glorp watch --browser against a private repository or board:

glorp auth          # opens a browser window; sign in there
glorp auth --status # confirm it took

The session is stored in the profile directory and survives later runs, so this is a one-time step per profile.

Repository targets require permission to read issues, manage glorp's labels, and manage webhooks unless --poll is used. GitHub Project targets require the read:project scope to list items and the project scope to update their status. Push mode for organization-owned Projects also requires organization-owner access and the admin:org_hook scope:

gh auth refresh -s read:project -s project
gh auth refresh -s admin:org_hook # organization Project push mode only

Installation

On macOS or Linux:

curl -fsSL https://github.com/lsegal/glorp/releases/latest/download/install.sh | bash

The script downloads the release for the current operating system and architecture, installs glorp into ~/.local/bin, and installs the repository's gh-fix and gh-discuss skills globally through skills.sh, for every agent glorp ships a definition for. The installer asks the binary it just installed for that list (glorp agents -skills), so an agent added to the registry is covered without the installer changing.

On Windows PowerShell:

irm https://github.com/lsegal/glorp/releases/latest/download/install.ps1 | iex

The PowerShell installer places glorp.exe in %USERPROFILE%\AppData\Local\glorp, adds that directory to the user PATH, and installs the same gh-fix and gh-discuss skills through skills.sh, for the same registry-derived agent list. Restart the terminal if glorp is not immediately found.

Installer behavior can be overridden with environment variables:

The public .agents/skills/gh-fix and .agents/skills/gh-discuss directories in this repository are the skills.sh package sources.

The installers cover the built-in agents only. An agent declared in --config may name its own skills.sh target with "skills": {"target": "ID"} -- a dedicated id such as opencode, cline, or gemini-cli, or universal for a CLI skills.sh has no dedicated id for -- and installs its own skills with the same command the installers use:

npx --yes skills add lsegal/glorp@gh-fix --global --agent ID -y
npx --yes skills add lsegal/glorp@gh-discuss --global --agent ID -y

glorp agents lists the agents in force, and glorp agents -skills lists the target ids they install skills for. The agent definitions reference documents the whole definition schema, field by field, with a tutorial for registering a CLI glorp does not ship.

Upgrading

glorp upgrade

The command re-runs the installer for the current platform, so it picks up the latest release along with the current gh-fix skill. GLORP_REPO and the other installer environment variables above still apply.

Quick start

Every glorp invocation starts with a subcommand:

Options must appear before the first target. A target can be an OWNER/REPO, a GitHub repository URL, a GitHub Project URL, or a GitHub Discussions board URL.

Watch a repository using the default Codex agent and webhook mode:

glorp watch owner/repo

By default, repository targets select open issues authored by the authenticated GitHub user. Watch all open issues instead:

glorp watch --all-issues owner/repo

Select issues using GitHub issue-search syntax:

glorp watch --filter "assignee:@me" --filter "-label:blocked" owner/repo

Run without ngrok or managed webhooks by polling every 30 seconds:

glorp watch --poll --interval 30s owner/repo

The browser dashboard is available at http://localhost:8765 by default. If that port is occupied, glorp uses the next available port and logs the selected URL. Choose a different starting port, switch to the terminal dashboard, or disable UI entirely:

glorp watch --web-ui-port 9000 owner/repo
glorp watch --ui tui owner/repo
glorp watch --ui none owner/repo

--no-ui remains available as an alias for --ui none:

glorp watch --no-ui owner/repo

Open a running dashboard in a browser without hunting for its URL. glorp ui scans localhost from port 8765 upward, and when several instances are running it shows an interactive picker (or opens the lowest port when stdout is not a terminal):

glorp ui
glorp ui --port 9000

Use Claude Code and run up to three agent jobs concurrently:

glorp watch --agent claude --concurrency 3 owner/repo

Load balance work evenly across Codex and Claude by repeating --agent:

glorp watch --agent codex --agent claude --concurrency 4 owner/repo

Pick the model and reasoning level per agent with --agent AGENT/MODEL:LEVEL:

glorp watch --agent codex/gpt-5.6:high --agent claude/opus:medium --concurrency 4 owner/repo

Allow agents to run without sandbox or permission checks:

glorp watch --yolo owner/repo

Watch several repositories and projects in one process:

glorp watch --concurrency 3 owner/first owner/second https://github.com/orgs/example/projects/3

The concurrency limit is shared across all targets. GitHub webhook deliveries cause an immediate refresh, while --interval controls the periodic synchronization cadence.

Only deliveries that can change which issues are dispatchable cause a refresh. Closing an issue or pull request triggers an immediate continuation sweep for same-repository issues mentioned as #123: work from this instance resumes through the existing agent session, while unowned work uses the cooperative handoff before it continues. Pushes, other pull request activity, pings, and ordinary comments are logged and ignored, as are issues actions that leave labels, state, and dependencies untouched (edited, assigned, locked, and similar). In push mode, --interval therefore controls only the immediate follow-up refreshes that outlast GitHub's issue index lag; the periodic reconciliation that recovers missed deliveries runs every 15 minutes.

How it works

In the default mode, glorp:

1. Starts a webhook listener on a randomly assigned available port.
2. Starts an ngrok tunnel for that listener.
3. Creates a GitHub webhook for each repository target or organization-owned Project and removes stale ngrok webhooks previously managed for it.
4. Queries GitHub for matching open issues and queues previously unhandled work.
5. Starts the selected agent with /gh-fix ISSUE_NUMBER and tracks its output and result.

For repository targets, opening an issue yourself and assigning it to yourself marks it eligible for pickup; glorp's default filter only dispatches open issues that the authenticated user both authored and is assigned to, so somebody else assigning you their issue cannot start a run. Ownership of a claimed issue is tracked entirely through the comment-based handoff protocol below rather than a label. Project items are moved through their configured status as work starts and finishes.

Organization-owned Projects use GitHub's projects_v2_item organization webhook event for immediate refreshes, plus a narrow issues/issue_comment webhook on each repository backing the board so a change to an issue an agent is already working reaches it straight away. GitHub does not provide that event for user-owned Projects, so personal project targets continue to refresh on --interval; use --poll to avoid starting an unused webhook tunnel for those targets.

--browser selects a different transport for the same loop. The default mode reaches GitHub through the API: webhook deliveries arrive over an ngrok tunnel for instant refreshes, and --interval polling through gh (30s by default) covers everything webhooks do not. Browser mode instead launches one headless Chromium-based browser for the whole run, gives each target a tab on it, and reloads those pages on a short loop, reading what a signed-in user would see. There is no webhook server, no ngrok tunnel, and no API rate limit to stay under, which is why the interval defaults to 20s rather than 30s. Reading the pages a signed-in user sees means the browser profile has to be signed in: it starts empty, and a private repository or board renders as a 404, a 403, or a login wall until it has a session. glorp auth opens a visible window on that same profile so you can sign in once; glorp watch itself never opens a window, and Chrome allows only one process per profile directory, so signing in is a separate step rather than something a running watch does on the side. glorp auth --status reports the profile's current state without opening anything. Because it always polls, --browser is rejected rather than silently ignored when combined with --listen, --webhook-path, --webhook-secret, or --ngrok-binary, and a browser that cannot be launched is a fatal error instead of a quiet fallback to the API path.

That profile has to be signed in to GitHub, once: --browser-profile defaults to a directory of glorp's own, and a fresh one is signed out. It matters more than it looks, because the default --filter is written in terms of @me. A signed-out session resolves @me to nobody, so GitHub answers with a real, correctly empty search result rather than an error, and the run would otherwise poll a repository full of ready work forever without dispatching any of it. glorp checks for this on any page that comes back with no rows and stops with the profile directory and a pointer to glorp auth, rather than reporting zero issues.

Reading a rendered page means depending on GitHub's markup, which can change. --browser-vision adds an opt-in safety net for that day: when the page extractor fails on a page that loaded fine, glorp hands a single screenshot to the configured agent and asks it for the issue numbers. It is bounded hard in code (one screenshot per target per 10 minutes, three per run, then off) and logs every call it makes, because the steady state is meant to be zero AI calls. Recovering a list this way is a signal that the extractor needs fixing, not a mode to run in.

When a browser-mode run is misbehaving, --no-headless shows you the browser instead of making you infer it from CDP traffic: the run is identical, on the same profile and the same interval, but its window is on screen so you can watch each poll navigate and see what GitHub actually served.

Handled issues and active sessions are stored in .glorp.json by default. This prevents duplicate work after a restart and allows glorp to resume an interrupted session with the original agent, even when the new process selects a different --agent. If the original working directory is gone, the resumed agent is told to regenerate its missing work. Two cases restart the work instead of resuming it. Work pinned to an agent the current configuration no longer dispatches to is not resumed with the retired agent: the persisted session is discarded, logged as discarded persisted agent "NAME"; it is no longer configured, and the issue is redispatched to a currently configured agent with a fresh session. Agents whose definition declares "session": {"assign": "none"} -- opencode and cline among the built-ins -- have no resumable session at all, so picking their work back up always restarts the agent with the recovery prompt; because gh-fix is re-entrant, the restarted run adopts the branch and draft pull request the previous one left open rather than starting the issue over. Issues that declare dependencies using depends on #123 or GitHub's issue-dependency relationship remain blocked until those dependencies close.

Each glorp instance gets a random in-memory identity used to cooperate with other instances (including ones on other machines) sharing the same repository. Before reaping an issue that has no local record of being this instance's own work, glorp posts a signed Does anyone have this? /glorp:<identity> comment on the issue (or its open draft pull request, if one exists) and waits at least two minutes before claiming it with a Starting work on this issue or Continuing work on this issue comment. If another instance answers first, glorp stands down and leaves the ticket alone; the last instance to post a claim always wins. An instance that already holds the newest claim on a ticket skips the handshake and picks the work back up silently, rather than re-asking a question it has already answered.

Repository webhooks also subscribe to GitHub's issue_comment event so this handshake does not depend on the polling interval: when a Does anyone have this? comment arrives for a ticket this instance is actively working on, glorp replies immediately with a signed I am working on this comment instead of waiting for the next poll.

glorp terminates every subprocess it starts — the ngrok tunnel, agent runs, and helper commands — when it shuts down, including on SIGINT, SIGTERM, and SIGHUP. It also arranges the same should glorp be killed outright and run no cleanup at all: on Linux each subprocess carries a parent-death signal, and on Windows each one joins a job object that is destroyed with glorp. macOS and the BSDs offer no kernel equivalent, so glorp there keeps a small reaper process that holds a pipe to glorp and records the process groups glorp owns; the kernel closes that pipe when glorp dies, and the reaper terminates whatever is left. A SIGKILL of glorp watch therefore leaves no tunnel or agent behind on any supported platform.

Glorp serves either a localhost-only browser dashboard or an interactive terminal dashboard, selected by --ui. The browser dashboard mirrors the terminal dashboard's agent cards, output viewports, scrolling behavior, daemon logs, job counts, quota, delivery mode, and target status. --ui web is the default, --ui tui enables the terminal dashboard when stdout is a terminal, and --ui none writes timestamped progress to stdout. --no-ui is equivalent to --ui none.

CLI reference

glorp <command> [arguments]

glorp --version and glorp -h are accepted as aliases for glorp version and glorp help. Running glorp with no command, or with a target instead of a command, prints the command list and exits with status 2.

glorp watch

glorp watch [options] [TARGET [TARGET ...]]

If no TARGET is given, glorp uses the current directory's origin git remote when it points to a GitHub repository.

glorp ui

glorp ui [options]

Finds glorp dashboards by probing 16 consecutive localhost ports and opens one in the default browser. A port only counts as a dashboard when it answers glorp's own state endpoint, so unrelated local servers are skipped. When exactly one instance is found it opens directly; with several, an interactive picker appears on a terminal and the lowest port is opened otherwise. Exits with status 1 when nothing is running.

glorp auth

glorp auth [options]

Signs the browser profile that glorp watch --browser reads GitHub with in to GitHub. The profile starts signed out, so private repositories and project boards render as a 404, a 403, or a login wall until it has a session.

glorp auth opens an ordinary, visible browser window on glorp's own profile at https://github.com/login and waits until the sign-in finishes, then closes it and prints the account it signed in as. The session lives in the profile directory, so it survives later glorp watch runs and only has to be done once per profile. glorp gives up after 5 minutes rather than leaving the window open indefinitely.

glorp watch --browser also does this for you. When a poll reads a page GitHub served to a signed-out session — a 404 or a 403 on a repository or board you asked it to watch, or a page carrying GitHub's own signed-out markers — the run logs what it saw, stops its headless browser, opens the same login window on the same profile, and resumes polling once you have signed in. A sign-in that is declined, times out, or cannot happen is not offered again on the next poll: the run backs off (10 minutes, doubling to an hour), keeps watching in the meantime, and leaves glorp auth available at any time.

Chrome allows only one process per profile directory, so stop a running glorp watch --browser (or point --browser-profile at a different directory) before signing in yourself. On Linux with no display server — DISPLAY and WAYLAND_DISPLAY both unset — the command refuses to open a window and says so instead of hanging; sign in on a desktop session and point --browser-profile at that profile directory.

Supported target forms are:

owner/repository
https://github.com/owner/repository
https://github.com/users/OWNER/projects/NUMBER
https://github.com/orgs/OWNER/projects/NUMBER
https://github.com/OWNER/REPOSITORY/projects/NUMBER
https://github.com/OWNER/REPOSITORY/discussions
https://github.com/OWNER/REPOSITORY/discussions/categories/CATEGORY
projects:OWNER/REPOSITORY/NUMBER
projects:NUMBER
discussions:OWNER/REPOSITORY/CATEGORY
discussions:OWNER/REPOSITORY
discussions:CATEGORY

The projects: and discussions: forms are shorthands for the URLs above. The OWNER/REPOSITORY prefix may be omitted inside a git checkout whose origin remote points at a GitHub repository, so glorp watch projects:3 discussions:q-a watches project 3 and the Q&A discussions category of the current repository. A discussions category is named by its URL slug (q-a) or its display name (Q&A); without one, every category is watched.

A Discussions board target (https://github.com/OWNER/REPOSITORY/discussions) is watched differently from repository and Project targets: instead of the gh-fix skill, glorp dispatches the read-only gh-discuss skill for each new top-level Discussion thread that has no replies yet. gh-discuss only reads the repository to answer the question and posts a single top-level reply when it can do so accurately and positively; otherwise it leaves the thread untouched. Discussions targets work in both push and poll mode: in push mode glorp subscribes the repository webhook to GitHub's discussion event so a new thread dispatches immediately, with the periodic synchronization interval as the fallback. They are not affected by --filter or --all-issues, and do not use issue assignment or the comment-based ownership handoff protocol described below.

Press q or Ctrl+C to exit the interactive dashboard. glorp waits for running agents during shutdown.