Skip to content

installation.md

Latest commit

 

History

History
114 lines (88 loc) · 4.53 KB

installation.md

File metadata and controls

114 lines (88 loc) · 4.53 KB
Raw

Installation

Quick install

curl -fsSL https://raw.githubusercontent.com/ngthluu/loope/main/install.sh | sh

This downloads the prebuilt binary for your OS/arch from the latest release, verifies its checksum, and installs it to /usr/local/bin (override with LOOPE_INSTALL_DIR, pin a version with LOOPE_VERSION=v0.1.0). Binaries are published for macOS and Linux on amd64 and arm64.

Prefer to do it yourself? Grab an archive from the releases page, or build from source. Check the installed version with loope --version.

Release candidates

Tags with an -rc.N suffix (e.g. v0.2.2-rc.1) are published as GitHub prereleases: they ship the same binaries and images as a real release, but the default install path never picks them up — install.sh resolves releases/latest, which GitHub only ever points at stable releases.

To try one, pin the tag explicitly:

curl -fsSL https://raw.githubusercontent.com/ngthluu/loope/main/install.sh \
  | LOOPE_VERSION=v0.2.2-rc.1 sh

Add LOOPE_INSTALL_DIR=$HOME/.local/bin to keep the candidate side-by-side with a stable install. Going back is the same command with the stable tag (or no LOOPE_VERSION at all).

The telemetry-server image follows the same rule: an rc pushes only its versioned GHCR tags and leaves :latest on the last stable release — see running an rc image.

Prerequisites

loope is a wrapper around your local toolchain — these must be present at run time:

  • Go 1.25+ to build.
  • git, with the target repo cloned locally.
  • gh (GitHub CLI), authenticated (gh auth login) with permission to edit issues, push branches, and open PRs on the target repo.
  • claude (Claude Code CLI), logged in.
  • The superpowers plugin installed in the Claude profile loope runs under (claude plugin install superpowers@claude-plugins-official) — the pipeline prompts are superpowers slash commands and are inert text without it.
  • curl (optional) — used to download issue image attachments; without it those are skipped.

Warning: pipeline sessions run with --dangerously-skip-permissions so they can work unattended. Only point the loop at repositories where you are comfortable with an autonomous agent reading, running, and committing code.

Doctor

loope verifies this toolchain at startup and refuses to run when a required piece is missing, printing what is missing and the command that fixes it. Run the same checks standalone:

./loope --doctor --config loope.json

--doctor prints the full report even when everything passes and exits non-zero when a required check failed. Missing labels and a missing curl are warnings: they are reported but never block the run.

Create the labels

The state labels and the eligible label must exist in the repo before the loop can apply them — the labels preflight check warns with exactly these commands when any are missing:

gh label create ai-agent      --repo your-org/your-repo
gh label create ai-wip        --repo your-org/your-repo
gh label create ai-done       --repo your-org/your-repo
gh label create ai-rework     --repo your-org/your-repo
gh label create ai-needs-info --repo your-org/your-repo
gh label create ai-stopped    --repo your-org/your-repo
gh label create ai-resolve-merge --repo your-org/your-repo

ai-stopped is what Stop on the dashboard swaps ai-wip for; without it the stop cannot land and the ticket keeps running. ai-resolve-merge is the human-applied trigger for the merge-resolve flow: only you ever add it, but a label that doesn't exist on the repo can't be applied at all, so without it the flow is unreachable. See the status state machine for what each label means.

Build from source

go -C worker build -o loope .
cp worker/loope.json.example loope.json   # then edit repoPath / repoSlug / workDir
./loope --config loope.json        # daemon: poll every pollIntervalSec, serve the dashboard

--config is required — there is no default config path. The daemon shuts down gracefully on Ctrl-C / SIGTERM, draining in-flight pipelines first; a run killed outright is re-queued by the next startup's orphan sweep, with its worktree intact. To validate a new config without starting the loop, run ./loope --doctor --config loope.json.

See Configuration for every config field.