Getting Started with CueLoop

Status: Active Owner: Maintainers Source of truth: this document for guided human onboarding Parent: CueLoop Documentation

This guide is for humans who want enough context to run CueLoop safely for the first time. If you only need the shortest command path, use the Quick Start. If you are an already-running coding agent using CueLoop as a ledger, use the Agent Usage Guide instead.

What CueLoop does

CueLoop keeps AI-agent work in repo-local files instead of hidden chat state:

active work: .cueloop/queue.jsonc
completed/rejected work: .cueloop/done.jsonc
project settings: .cueloop/config.jsonc
optional prompt overrides: .cueloop/prompts/*.md

A typical loop is:

write task → inspect queue → run supervised phases → validate locally → archive result

1. Install

From crates.io:

cargo install cueloop

From this repository:

git clone https://github.com/fitchmultz/cueloop cueloop
cd cueloop
make install

On macOS, install GNU Make with brew install make and use gmake if Apple make is first on PATH.

Check the binary:

cueloop version
cueloop --help

2. Initialize a project

Run this from the repository where you want CueLoop state:

cd your-project
cueloop init

Interactive init helps choose a runner, workflow mode, queue tracking policy, and optional first task. For scripts or CI fixtures:

cueloop init --non-interactive

After init, run:

cueloop queue validate
cueloop queue list

3. Add one task

cueloop task "Add regression tests for webhook delivery failures"
cueloop queue list
cueloop queue show <TASK_ID>

Use the task ID printed by cueloop task or cueloop queue list.

Good first tasks are small, specific, and easy to verify. Avoid asking the first run to redesign the whole repo.

4. Inspect before running

Before starting an agent, check what CueLoop will select and whether your runner setup is ready:

cueloop queue next --with-title
cueloop run one --dry-run
cueloop runner list
cueloop doctor

If no runner is configured yet, stop at the dry run and use the Local Smoke Test to verify the CLI and queue model without invoking an external model.

5. Run supervised work

Run one task:

cueloop run one

Or cap a loop explicitly:

cueloop run loop --max-tasks 1

Useful variants:

# Single-pass mode for simple work
cueloop run one --quick

# Full plan → implement → review flow
cueloop run one --phases 3

# Select and explain without executing
cueloop run one --dry-run

Do not start with an unlimited loop. Learn queue state, runner behavior, and local validation first.

6. Review and validate

After a run, inspect both Git and CueLoop state:

git status --short
cueloop queue validate
cueloop queue list

In this repository, the normal branch gate is:

make agent-ci

For another project, use that project’s local CI/test command.

7. Choose deeper docs by question

Question	Read
What are all the commands?	CLI Reference
How do queue files work?	Queue
What fields can a task have?	Task Schema and Field Reference
How do statuses and priorities work?	Task Lifecycle and Priority
How do dependencies work?	Task Relationships and Dependencies
What happens in each execution phase?	Phases
How do I configure runners and models?	Runners and Configuration
How do CI gates and review safeguards work?	Supervision
How do I recover interrupted work?	Session Management
How do I use the macOS app?	App (macOS)
How do I debug setup problems?	Troubleshooting

Daily operator checklist

cueloop queue validate
cueloop queue list
cueloop queue next --with-title
cueloop run one --dry-run when unsure
cueloop run one or a capped cueloop run loop --max-tasks <N>
Review Git diff and queue state
Run the project’s local validation gate

Next step

If you are evaluating CueLoop, run the Evaluator Path. If you are adopting it in a project, complete the Local Smoke Test before wiring up a real runner.

Legacy deep links

The previous version of this page was a long combined tutorial. These headings remain as lightweight redirects so old links and search results still land on useful current guidance.