OpenLoop

Ship while you sleep. OpenLoop turns Pi into a tireless developer that works across all your repositories — planning tasks, writing code, running validations, and promoting changes — on a loop, without manual intervention.

One CLI. One daemon. Every linked repo gets its own control plane, task ledger, and safety policy. You define the work; OpenLoop handles the rest.

Quick Start

1. Install

git clone <repo-url> && cd openloop
npm install
npm run build
npm link        # makes `openloop` available globally

2. Link a project

openloop project add myapp ~/projects/my-app --init

This registers the project and materializes its control-plane files into ~/projects/my-app/.openloop/.

You can also split the two steps (project add then project init) if you want to review config before initialization.

3. Configure validation (recommended)

OpenLoop auto-detects lint, test, and typecheck commands from package.json during init. Verify they look right:

openloop config project-show myapp

To override, edit ~/projects/my-app/.openloop/project.json:

{
  "validation": {
    "lintCommand": "npm run lint",
    "testCommand": "npm test",
    "typecheckCommand": "npm run check"
  }
}

4. Add a task

openloop task add --project myapp --title "Add input validation to the signup form"

Or enqueue from an issue reference:

openloop enqueue --project myapp --ref "https://github.com/org/repo/issues/42"

5. Run

Run a single scheduler iteration to try things out:

openloop run-once --project myapp

Or start the daemon for continuous, unattended operation:

openloop service start
openloop service status   # check progress
openloop service stop     # shut down

6. Review and promote

Check what was done and land the results:

openloop task list --project myapp
openloop task show --project myapp --task <task-id>
openloop promotion list --project myapp
openloop promotion apply --project myapp --task <task-id>

Low-risk tasks with passing validations can auto-merge. Everything else waits for your review.

Requirements

• Node.js 20+
• pi available on PATH
• git available on PATH

Development

npm run check     # type-check
npm test          # run tests
npm run build     # build CLI

How It Works

OpenLoop cycles through three modes automatically:

1. Active development — picks the next eligible task, runs Pi with a role-specific prompt, validates the output, and decides whether to auto-merge or create a review branch.
2. Self-healing — detects and fixes lint errors, type errors, and localized test failures without being asked.
3. Continuous improvement — when idle, discovers gaps like missing validations or loose scope policies and proposes tasks to address them.

Each run is labeled with a worker role that shapes Pi's behavior:

Runtime Model

• Pi runs as a subprocess via the pi binary.
• Model resolution is deterministic: CLI flag > project config > global config.
• A single resident daemon manages scheduling across all linked projects.
• One active worker per project at a time; the daemon sleeps between iterations.
• Daemon state persists under ~/.openloop/run/.

Worker Roles

| Role | When | |------|------| | sdd-planner | A task needs planning before code changes | | implementer | A task is ready for implementation | | repo-improver | The scheduler is doing discovery or idle improvement work | | ci-healer | The scheduler is handling ledger-driven self-healing |

Self-Healing

V1 supports automatic fixes for:

• lint-fix — linter violations
• type-fix — type-checker errors
• localized-test-fix — isolated test failures

Anything outside these categories is blocked rather than attempted unattended.

Risk and Promotion

| Risk | Auto-merge | Human review | |------|------------|--------------| | low-risk | Allowed when policy permits and validations pass | Optional | | medium-risk | Not allowed | Required | | high-risk | Never | Required |

Tasks can declare scope.paths, and the runtime enforces project policy:

• allow — allowGlobs whitelist
• block — denyGlobs blacklist
• escalate — highRiskAreas require human review
• default — unknown scope is classified conservatively

Safety Guardrails

| Guard | Default | Details | |-------|---------|----------| | Budget ceiling | $25/day | Daemon pauses when exhausted | | Max attempts | 3 per task | Task is blocked after repeated failures | | Run timeout | 30 min | Hard cap per Pi invocation | | No-progress detection | On | Blocks tasks with ineffective diffs or repeated errors | | Scope policy | Per-project | allowGlobs, denyGlobs, highRiskAreas in .openloop/policy.yaml | | Auto-merge | Low-risk only | All validations must pass; medium/high-risk always requires review |

CLI Reference

Project Management

| Command | Description | |---------|-------------| | project add <alias> <path> [--init] | Register a repository | | project init <alias> | Materialize control-plane templates | | project list | List linked projects | | project show <alias> | Show project details |

Tasks

| Command | Description | |---------|-------------| | task add --project <alias> --title <text> | Add a task (accepts --kind, --risk, --scope) | | task list --project <alias> | List tasks (accepts --status, --risk filters) | | task show --project <alias> --task <id> | Show task detail with promotion history | | enqueue --project <alias> --ref <ref> | Create a task from an issue or external reference |

Execution

| Command | Description | |---------|-------------| | run --project <alias> --prompt <text> | Run Pi directly with a prompt | | run-once --project <alias> | Execute one scheduler iteration | | service start\|stop\|status\|restart | Manage the resident daemon | | pause / resume | Pause/resume the daemon globally |

Promotion

| Command | Description | |---------|-------------| | promotion list --project <alias> | List promotion artifacts | | promotion show --project <alias> --task <id> | Show promotion detail | | promotion history --project <alias> --task <id> | Chronological promotion log | | promotion apply --project <alias> --task <id> | Apply a pending promotion (merge or checkout) | | promotion reject --project <alias> --task <id> | Reject a pending promotion |

Configuration

| Command | Description | |---------|-------------| | config show | Show global configuration | | config set-model <model> | Set default Pi model | | config project-show <project> | Show project-local config | | config project-set-model <project> <model> | Set project Pi model |

Project Structure

~/.openloop/              # global state
  config.json             # model, budgets, runtime limits
  projects.json           # linked project registry
  run/                    # daemon pid, state, logs

<project>/.openloop/      # per-project control plane
  project.json            # project runtime config
  policy.yaml             # scope and risk policy
  tasks.json              # task ledger
  specs/                  # planning artifacts
  runs/                   # run summaries
  promotions/             # promotion decision artifacts
  promotion-results/      # promotion outcome records

<project>/.agents/skills/openloop/
  SKILL.md                # agent instructions inside linked repositories

<project>/.pi/
  SYSTEM.md               # base Pi system prompt
  APPEND_SYSTEM.md        # runtime-specific Pi rules

Release

Before publishing:

npm run release:verify    # validates tarball contents
npm run release:pack      # verify + pack

The npm tarball includes README.md, dist/, and templates/project/ only. Internal docs and source maps are excluded.

Roadmap (Post-V1)

• Cron / timer-triggered execution
• git worktree support
• Webhook-driven CI self-healing
• Direct spec-file generation
• Broader heuristic backlog discovery