Skip to content

getting-started.md

Latest commit

 

History

History
158 lines (104 loc) · 3.22 KB

getting-started.md

File metadata and controls

158 lines (104 loc) · 3.22 KB
Raw

Getting started

This guide walks you through installing Loops, saving your Cursor API key, and running your first workflow.

Prerequisites

Install

npm install -g @dresnite/loops

Verify the install:

loops --help

Help output includes the provider roadmap (cursor supported, claude-code planned).

Authenticate

Save your Cursor API key once. Loops stores it in ~/.loops/credentials.json (file mode 600).

loops key set cursor cursor_...

Confirm it was saved:

loops key list

Service account keys from Cursor Team settings also work.

CURSOR_API_KEY still works as an override, but the recommended flow is loops key set.

Define your first loop

loops add structure-agent --description "Improve codebase structure"

For interactive setup:

loops add structure-agent --interactive

Definitions are stored globally in ~/.loops/definitions/.

Run the loop

Start a continuous run against a repository:

loops run structure-agent \
  --repo ./my-app \
  --prompt "improve structure" \
  --budget 10 \
  --tasks 25

The command prints a run id and returns immediately. The worker keeps running in the background.

Budget and tasks

Flag Meaning
--budget <usd> Stop when estimated model spend reaches this dollar amount
--tasks <n> Stop after this many completed agent turns

Both are optional. Examples:

  • --budget 10 only — spend cap, no turn limit
  • --tasks 25 only — stop after 25 turns, no spend cap
  • --budget 10 --tasks 25 — stop when either limit is hit first
  • neither — run continuously until you stop it with loops stop

Budget is estimated from token usage reported by the Cursor SDK. See Configuration for details.

For a single execution:

loops run structure-agent --repo ./my-app --once

Monitor and stop

loops ls

Example output:

structure-agent → running (run-id: a1b2, budget used: 30%, tasks: 7/25)

Check if a loop failed

Active runs disappear from loops ls when they finish or error. Use:

loops ls --all
loops logs structure-agent

Failed runs show status: error with an error snippet. loops logs prints the full activity log.

Follow a running loop

loops logs structure-agent --follow

View or change the prompt

loops prompt show structure-agent
loops prompt set structure-agent --prompt "focus on error handling"

On a continuous run, prompt changes apply on the next agent task.

View or change the model

loops model show structure-agent
loops model set structure-agent --model composer-2.5

On a continuous run, model changes apply on the next agent task.

Stop by loop name or run id:

loops stop structure-agent
loops stop a1b2

Clean up

loops rm structure-agent

You cannot remove a definition while a run for that loop is still active.

Next steps