Skip to content
OpenLoop

Quickstart

This guide takes you from a fresh install to a running daemon with your first promoted change. If you prefer a guided flow, openloop setup walks through the same steps interactively.

Section titled “1. Link a repository”
Terminal window
openloop project add myapp ~/code/myapp --init

This does two things:

  • Registers the alias myapp in the global registry (~/.openloop/projects.json).
  • Materializes the per-repo control plane into ~/code/myapp/.openloop/, task ledger, policy, config, plus agent prompt files (.pi/SYSTEM.md, .agents/skills/openloop/SKILL.md) and an OpenLoop section in AGENTS.md.

During --init, OpenLoop detects your stack and fills in validation commands. Verify the result:

Terminal window
openloop config project-show myapp

Look at the validation block; it should reflect your real commands:

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

Stack detection covers Node (npm/pnpm/yarn/bun), Python (ruff/pytest/mypy), Go (golangci-lint/go test/go vet), Rust (cargo clippy/test/check), Gradle, Maven, Ruby (rubocop/rspec), and .NET. Edit .openloop/project.json directly to override.

2. Enqueue work

Section titled “2. Enqueue work”
Terminal window
openloop task add -p myapp \
  --title "Add pagination to the /orders endpoint" \
  --kind feature --risk low \
  --scope src/api/ tests/api/

What you just did:

  • --kind and --risk drive scheduling and the promotion decision.
  • --scope constrains which paths the agent may touch, enforced by policy.
  • The task id is a slug of the title (add-pagination-to-the-orders-endpoint).

Or pull work from your tracker: label a GitHub issue openloop, configure issue sync, and it becomes a task automatically.

3. Try one iteration

Section titled “3. Try one iteration”

Before handing control to the daemon, run a single scheduler iteration:

Terminal window
openloop run-once -p myapp --dry-run    # shows selected task + built prompt, runs nothing
openloop run-once -p myapp              # actually runs it

The output summarizes the run: prompt, agent result, validations, and the promotion decision.

4. Start the daemon

Section titled “4. Start the daemon”
Terminal window
openloop service start
openloop status        # per-project queue counts + daemon/budget state

One daemon manages all linked projects; one active worker per repo at a time. From here on, OpenLoop cycles through queued tasks on its own.

5. Review the results

Section titled “5. Review the results”
Terminal window
openloop task list -p myapp --status done
openloop promotion list -p myapp
openloop digest            # fleet-wide: activity, spend, review queue
  • Low-risk tasks with green validations land as auto-merge promotions (applied on a branch and merged); see promotion apply if you prefer to apply them yourself.
  • Everything else queues a pull request or waits for manual review.
  • openloop approval list -p myapp shows the human-review packets: risk, attempts, cost, branch.

6. Keep an eye on it

Section titled “6. Keep an eye on it”
  • openloop watch: live, 1-second-refreshing dashboard in your terminal.
  • openloop events --since 2h: the append-only audit log.
  • openloop report: a human-readable activity summary.
  • openloop dashboard enable: a local web dashboard (guide).

When you’re done for the day: openloop service stop (or pause to stop scheduling without killing the daemon).

Where to go next

Section titled “Where to go next”