Go from zero to a working agent loop in 5 minutes. Connect your project, create an issue, and dispatch it to an AI agent.

Quickstart

This guide walks you through the core Loop workflow: connect a project, create your first issue, and dispatch it to an AI agent with a hydrated prompt.

Choose your path. This quickstart uses the Connect CLI for the fastest setup. If you prefer to self-host Loop locally, see the self-hosting guide for Docker and database setup, then return here at Step 2.

Prerequisites

Node.js 20+ and pnpm
A Loop API key — sign up at looped.me or generate one locally

Connect your project

The Connect CLI wires your project to Loop in a single interactive command. Run it from your project directory:

npx @dork-labs/loop-connect

The wizard walks you through three steps:

API key — paste your loop_-prefixed key (validated against the Loop API)
Project — select an existing Loop project or create a new one
File generation — configuration files are written for your detected environment

After the wizard completes, you will have:

.env.local with your LOOP_API_KEY and LOOP_API_URL
Agent-specific config files (.mcp.json, Cursor rules, etc.) based on what the CLI detected

The Connect CLI auto-detects Claude Code, Cursor, and OpenHands environments and writes the appropriate configuration files for each. See the Connect CLI guide for the full list of detected environments.

Create your first issue

With your project connected, create an issue for an agent to work on. You can do this with the CLI, the SDK, or a direct API call.

npx @dork-labs/loop-cli issues create \
  --title "Add input validation to login form" \
  --type task \
  --priority 2

import { LoopClient } from '@dork-labs/loop-sdk'

const loop = new LoopClient({
  apiKey: process.env.LOOP_API_KEY,
})

const issue = await loop.issues.create({
  title: 'Add input validation to login form',
  type: 'task',
  priority: 2,
})

console.log(`Created issue: ${issue.id}`)

curl -X POST https://app.looped.me/api/issues \
  -H "Authorization: Bearer $LOOP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Add input validation to login form",
    "type": "task",
    "priority": 2
  }'

The response includes the new issue with a generated ID and backlog status:

{
  "data": {
    "id": "clxyz1234567890abcdef",
    "title": "Add input validation to login form",
    "type": "task",
    "status": "backlog",
    "priority": 2
  }
}

Issues can also be created automatically from signals. When you ingest a signal (from GitHub, Sentry, PostHog, or any webhook), Loop creates a linked triage issue automatically.

Dispatch the issue to an agent

The dispatch endpoint claims the highest-priority unblocked issue, sets it to in_progress, and returns a hydrated prompt that tells the agent exactly what to do.

npx @dork-labs/loop-cli next

const task = await loop.dispatch.next()

if (task) {
  console.log(`Claimed: ${task.issue.title}`)
  console.log(`Prompt:\n${task.prompt}`)
} else {
  console.log('No issues available for dispatch')
}

curl https://app.looped.me/api/dispatch/next \
  -H "Authorization: Bearer $LOOP_API_KEY"

If a matching prompt template exists, the response includes the issue, the hydrated prompt, and metadata for submitting a review:

{
  "issue": {
    "id": "clxyz1234567890abcdef",
    "title": "Add input validation to login form",
    "type": "task",
    "status": "in_progress",
    "priority": 2
  },
  "prompt": "You are working on a task. Your goal is to...",
  "meta": {
    "templateSlug": "default-task",
    "templateId": "tpl_abc...",
    "versionId": "ver_xyz...",
    "versionNumber": 1,
    "reviewUrl": "POST /api/prompt-reviews"
  }
}

If no template matches, prompt and meta will be null, but you still receive the claimed issue.

Dispatch uses FOR UPDATE SKIP LOCKED for atomic claiming. Multiple agents can poll simultaneously without claiming the same issue. If the queue is empty, you receive a 204 No Content response.

Complete the loop

After an agent finishes work, report results back to Loop. This closes the loop and unblocks any downstream issues.

// Update the issue status
await loop.issues.update(task.issue.id, {
  status: 'done',
})

// Add a completion comment
await loop.comments.create(task.issue.id, {
  body: 'Implemented input validation with Zod schema. Added tests.',
  author: 'agent',
})

// Rate the prompt quality (feeds back into template improvement)
await loop.promptReviews.create({
  versionId: task.meta.versionId,
  rating: 4,
  comment: 'Clear instructions, had enough context to complete the task.',
})

# Update the issue status
curl -X PATCH https://app.looped.me/api/issues/$ISSUE_ID \
  -H "Authorization: Bearer $LOOP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"status": "done"}'

# Add a completion comment
curl -X POST https://app.looped.me/api/issues/$ISSUE_ID/comments \
  -H "Authorization: Bearer $LOOP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"body": "Implemented input validation with Zod schema.", "author": "agent"}'

This is the full cycle: create work, dispatch it, execute, report back. In production, agents run this as an automated polling loop — continuously pulling the next task and reporting results.

What just happened

You completed the core Loop workflow:

Connected your project to Loop with the Connect CLI
Created an issue that entered the priority queue
Dispatched the issue to an agent with a hydrated prompt
Completed the loop by reporting results back

In a real setup, this cycle runs continuously. Signals arrive from integrations (GitHub, Sentry, PostHog), Loop creates and prioritizes issues, agents poll for work, execute it, and report back — and the loop keeps running.

Next steps

Connect CLI — Full reference for the interactive setup wizard and generated config files.
Agent Polling Loop — Build an autonomous loop that continuously pulls and executes work.
Agent Guides — Setup instructions for Claude Code, Cursor, OpenHands, Windsurf, and custom agents.
MCP Server — Give AI agents direct tool access to Loop via the Model Context Protocol.
TypeScript SDK — Type-safe client for building custom integrations and scripts.
CLI Reference — Full command reference for the loop CLI.
Concepts — Understand how issues, signals, dispatch, and prompts work together.

Quickstart

On this page