Looper — Autonomous AI Dev Team for Your GitHub Repos

Looper monitors GitHub repositories, and when an issue is labeled looper:plan, it coordinates a team of AI agents to implement the feature end-to-end: planning, reviewing, fixing, and iterating until every check passes.

Unlike CI/CD pipelines that only veto broken code, Looper writes and fixes code. It is a persistent daemon that lives alongside your repos, handling the grunt work of feature implementation so you can focus on architecture and decisions.

Built in Rust (tokio async). Ported from a Go original (166K LOC -> 37K LOC — 78% smaller).

Quick Start

Install with one command

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

This installs three binaries to ~/.local/bin/:

Or with Homebrew

# Coming soon — tap not yet published
# brew install quangdang46/tap/looper

Manual build

git clone https://github.com/quangdang46/looper.git
cd looper
cargo build --release
# Binaries in target/release/{looper,looperd,loopernet}

Start the daemon

# Start in foreground (default)
looperd

# Or start as a background service
looper daemon install
looper daemon start

The daemon opens a REST API on http://127.0.0.1:7391.

Architecture

Looper is a Cargo workspace of 16 crates organized in a dependency chain, topped by three binaries:

                    ┌──────────────────────┐
                    │     GitHub Issues     │
                    │  (labeled looper:plan)│
                    └──────────┬───────────┘
                               │ webhook / poll
                               ▼
┌─────────────────────────────────────────────────────┐
│                   looperd (daemon)                   │
│                                                      │
│  ┌──────────┐  ┌──────────┐  ┌──────────────────┐   │
│  │ Scheduler │─▶│  Runner  │──▶  Agent Executor  │   │
│  │ (tick)    │  │  (5 roles)│  │  (5 vendors)    │   │
│  └──────────┘  └──────────┘  └──────────────────┘   │
│         │            │                │              │
│         ▼            ▼                ▼              │
│  ┌──────────┐  ┌──────────┐  ┌──────────────────┐   │
│  │ Storage   │  │ Service  │  │ GitHub / Git     │   │
│  │ (SQLite)  │  │ (logic)  │  │ Gateway          │   │
│  └──────────┘  └──────────┘  └──────────────────┘   │
│         ▲                                            │
│  ┌──────┴──────┐                                     │
│  │  REST API   │  port 7391                          │
│  │  + SSE      │                                     │
│  └─────────────┘                                     │
└─────────────────────────────────────────────────────┘
         │                              │
         ▼                              ▼
┌─────────────────┐          ┌─────────────────────┐
│  looper (CLI)   │          │  loopernet (cloud)  │
│  status / queue  │          │  multi-node coord.  │
│  logs / config   │          │  claim routing      │
└─────────────────┘          └─────────────────────┘

Crate dependency graph

looper-types           (domain types, state machines, zero deps)
  └── looper-config    (config loading, validation, disclosure)
  └── looper-storage   (SQLite repositories, migrations, event log)
        └── looper-service  (loop/run/project business logic)
              ├── looper-github   (GitHub gateway via gh CLI)
              ├── looper-git      (git worktree management via git2)
              ├── looper-agent    (agent executor, 5 vendors)
              ├── looper-scheduler (tick loop, queue, claim)
              └── looper-runner   (5 agent roles, ~20K lines)
                    ├── looper-api       (axum REST server, auth, SSE)
                    ├── looper-webhook   (webhook forwarding)
                    └── looper-infra     (bootstrap, runtime, notif)
                          ├── looperd    (daemon binary)
                          ├── looper-cli (CLI binary)
                          └── looper-net (cloud server binary)

How It Works

1. Issue Detection

The daemon polls GitHub or receives webhooks. When an issue is labeled looper:plan, the loop begins.

2. Agent Loop

Looper runs a multi-agent workflow on every accepted issue:

┌─────────┐    ┌──────────┐    ┌────────┐    ┌────────────┐
│ Plan    │───▶│ Review   │───▶│ Work   │───▶│ Review     │
│ Agent   │    │ Agent    │    │ Agent  │    │ / Fix      │
└─────────┘    └──────────┘    └────────┘    └────────────┘
     │              │              │               │
     ▼              ▼              ▼               ▼
  Writes        Checks        Implements       Iterates
  a spec        the plan      the code         until green

Each step runs a disposable agent process — the agent is invoked, given a prompt context, and its output is captured and committed. If the review fails, a fixer agent patches the PR and the loop repeats.

3. Agent Vendors

Looper supports 5 agent backends, selected per run or globally:

4. Priority Queues

Issues and PRs are slotted into three queues:

5. Persistence

All state is stored in a local SQLite database: queue entries, run history, agent outputs, event logs, and configuration. The daemon is stateless enough to restart safely — interrupted runs can be resumed.

CLI Usage

# Status & health
looper status                          # Daemon health, queue depth, agent status
looper status --json                   # Machine-readable output

# Run management
looper run <issue-url>                 # Start a loop on a GitHub issue
looper run cancel <run-id>             # Cancel a running loop
looper run list                        # List recent runs and their states
looper run logs <run-id>               # Tail agent output for a run

# Queue inspection
looper queue list                      # Show queued items (auto/planned/manual)
looper queue clear                     # Clear pending queue entries

# Configuration
looper config get <key>                # Read a config value
looper config set <key> <value>        # Write a config value
looper config view                     # Dump full config (with secrets masked)

# Daemon lifecycle
looper daemon start                    # Start the background daemon
looper daemon stop                     # Graceful shutdown
looper daemon restart                  # Restart the daemon
looper daemon logs                     # Follow daemon logs (SSE stream)

# Network mode (multi-node)
looper network join <url> --name <name> --key <key>
looper network leave
looper network status
looper network members

# Webhook management
looper webhook enable                  # Enable webhook forwarding
looper webhook disable                 # Disable webhook forwarding
looper webhook status                  # Show webhook configuration

# Git worktree management
looper worktree cleanup                # Clean up orphaned worktrees

# Diagnostics
looper inspect <run-or-loop-id>        # Deep inspection of a loop/run
looper failures                        # Show recent failures with diagnostics
looper upgrade                         # Self-upgrade to latest release

Output formats

Every command supports --json for machine-readable output. The default format is human-friendly tables and trees.

Configuration

Looper uses a layered configuration system: embedded defaults -> config file -> environment variables -> CLI overrides.

Config file discovery

The daemon searches for looper.toml (or .yaml, .json) in order:

1. $LOOPER_CONFIG/<file> (explicit, highest priority)
2. $XDG_CONFIG_HOME/looper/<file>
3. Platform config dir (~/.config/looper/ on Linux, ~/Library/Application Support/com.looper.looper/ on macOS)
4. ~/.looper/<file> (legacy fallback)

Security features

• Config files with world-readable permissions trigger a warning on Unix
• Secrets in config values are masked in looper config view output
• Sensitive environment variables are stripped before agent subprocess execution
• API authentication via Bearer tokens

Minimal example

[server]
host = "127.0.0.1"
port = 7391

[daemon]
data-dir = "~/.looper"
poll-interval-secs = 30

[storage]
db-path = "~/.looper/looper.db"

[github]
gh-path = "/usr/local/bin/gh"

[agent]
vendor = "claude-code"
timeout-secs = 300

See docs/configuration.md for the full reference (897 lines, every option documented with defaults).

Network Mode (Multi-Node)

LooperNet provides a central cloud coordination server that allows multiple daemon instances to share work across a network.

┌──────────────┐       ┌──────────────┐
│ Daemon A     │       │ Daemon B     │
│ (macOS)      │       │ (Linux x86)  │
│              │       │              │
│ 3 workers    │       │ 5 workers    │
└──────┬───────┘       └──────┬───────┘
       │                      │
       └──────────┬───────────┘
                  │
         ┌────────▼────────┐
         │   loopernet     │
         │  (cloud coord)  │
         │                 │
         │ Claim routing   │
         │ Peer discovery  │
         │ State sync      │
         └─────────────────┘

• Node types: coordinator (leader, one per network) and workers
• Claim policy: configurable strategies (earliest-idle, round-robin, affinity)
• State sync: periodic heartbeat with full state reconciliation
• Security: mutual TLS, join keys, identity management

See docs/network-mode.md for the full protocol and deployment guide.

Development

Prerequisites

• Rust 1.85+ (stable) — see rust-toolchain.toml
• Cargo (included with Rust)
• A GitHub CLI (gh) binary for gateway tests
• SQLite (libsqlite3-dev on Linux, bundled crate on macOS)

Building

cargo build                    # Debug build
cargo build --release          # Release build (4 targets via rust-toolchain.toml)
cargo check --workspace        # Fast type-check (preferred during development)

Testing

cargo test --workspace         # Full test suite (unit + integration)
cargo test -p <crate>          # Single crate
cargo test <name>              # Single test by name
cargo test --workspace -- --nocapture  # With output

Linting

cargo fmt                      # Auto-format
cargo fmt --check              # Format check
cargo clippy --workspace -- -D warnings  # Full lint

CI/CD

Crate summary

FAQ

Does Looper need API keys for every vendor? No. You provide the agent binary (Claude Code, Codex CLI, etc.) and its own auth; Looper only invokes it.

Can I run Looper on a single repo? Yes. Looper works on any number of repos — you configure which repos to watch.

What happens if an agent hangs or crashes? Agent processes are wrapped with a configurable timeout (default 5 min per role). On timeout/crash, the run is marked as failed and the error is logged. The daemon continues normally.

Is the SQLite database safe to delete? Yes — it stores run history and queue state. Deleting it loses that history, but the daemon re-creates it on next start.

Does Looper modify my local git state? Looper uses git worktrees (via git2) for all operations. Your primary checkout is never touched.

How is this different from CI/CD? CI/CD rejects broken code. Looper fixes it — it writes code, pushes PRs, and iterates until checks pass. It is a development teammate, not a gate.

License

MIT — see LICENSE.

Built with clap, tokio, axum, rusqlite, serde, tracing, and 30+ other Rust crates.