CueLoop is a local-first AI coding workflow tool with a Rust CLI and a SwiftUI macOS app, both built around a structured task queue stored in your repository.
The primary executable and Cargo package are both cueloop. Repositories use .cueloop/ for runtime state.
Teams use CueLoop when ad-hoc AI coding stops being enough and they need a repeatable way to turn requests into queued work, run that work through Codex/Claude/Gemini-style agents, and keep the result reviewable with local files, local CI, and explicit task history instead of hidden SaaS state.
If you are evaluating the repo quickly and want the fastest high-signal path:
- Read the product overview in this README.
- Run the no-runner-required verification flow in docs/guides/local-smoke-test.md.
- Skim the command map in docs/cli.md.
- Use docs/guides/evaluator-path.md for a short "what to try, what to expect" walkthrough.
That path is intentionally local-first and does not require configuring Codex/Claude/Gemini before you can validate the repo.
CueLoop is designed for engineering teams that want repeatable, auditable AI-assisted development workflows.
It provides:
- A structured task queue with explicit lifecycle and dependency links
- Multi-runner execution (
codex,opencode,gemini,claude,cursor,kimi,pi) - Supervised 1/2/3-phase execution (plan, implement, review)
- Parallel execution with workspace isolation
- Guardrails around queue validity, retries, session recovery, and local CI gates
- Hosted SaaS orchestration (CueLoop is local-first)
- Hidden black-box state (queue and done files are plain JSONC in
.cueloop/) - Replacing your existing developer tooling; CueLoop integrates with it
CueLoop centers on an operator-started run loop over repo-local tasks:
- Tasks live in
.cueloop/queue.jsoncand completed work is archived to.cueloop/done.jsoncby default. - A human starts
cueloop run one,cueloop run loop, orcueloop run loop --parallel <N>. - CueLoop invokes the configured runner through supervised one-, two-, or three-phase execution.
- In three-phase mode, Phase 3 reviews the implementation, resolves issues, and records completion.
- The configured CI gate runs before task completion and before automatic publish behavior.
- Post-run supervision validates queue state, archives the task, and commits or pushes according to
git_publish_mode. - Parallel mode applies the same task-sized workflow in isolated worker workspaces, then integrates completed workers back to the target branch.
flowchart LR
APP["macOS App<br>SwiftUI"] -->|shells out| CLI["cueloop CLI<br>Rust"]
CLI -->|reads/writes| QUEUE[.cueloop/queue.jsonc]
CLI -->|reads/writes| DONE[.cueloop/done.jsonc]
CLI -->|reads| CONFIG[.cueloop/config.jsonc]
CLI -->|spawns| RUNNERS["Runner CLIs<br>Codex / Claude / Gemini / OpenCode / Cursor / Kimi / Pi"]
From crates.io:
cargo install cueloopThis installs the cueloop executable.
From source:
GNU Make >= 4 is required for project targets. On macOS, install via
brew install makeand usegmakeunless GNU Make is already your defaultmake.
git clone https://github.com/fitchmultz/cueloop cueloop
cd cueloop
make install
# macOS/Homebrew GNU Make users: gmake install- Supported OS: macOS and Linux
- Rust toolchain: pinned by
rust-toolchain.toml(for deterministic fmt/clippy/test behavior) - SwiftUI app: macOS only (
apps/CueLoopMac/)
# 1) Initialize in your repo
cueloop init
# 2) Inspect the default-safe profile
cueloop config profiles
# 3) Add a task
cueloop task "Stabilize flaky queue integration test"
# 4) Execute one task with the recommended safe profile
cueloop run one --profile safe
# 5) Inspect queue state
cueloop queue listcueloop init defaults to the safe path: non-aggressive approvals, no automatic git publish, parallel execution kept opt-in, and local repo trust created in .cueloop/trust.jsonc.
Interactive init also lets you choose shared-vs-local queue tracking and opt into additional ignored local files for parallel worker sync; non-interactive init keeps the deterministic .env* sync default only.
Use --profile power-user only when you explicitly want the higher-blast-radius behavior, including commit_and_push automation.
On macOS, app-launched runs remain noninteractive: the app can supervise and disclose safety posture, but interactive approvals are still terminal-only.
If you do not want to configure a runner yet, use the smoke-test flow instead of cueloop run one.
That gives you a deterministic way to verify the CLI and repo health without any external model setup.
Here is a concrete repo workflow for a team using Codex or Claude Code in a normal feature branch:
# install CueLoop in your application repo
cargo install cueloop
cd your-service
cueloop init
# turn a real request into queued work
cueloop task "Add retry coverage for webhook delivery failures"
# inspect the task CueLoop just created
cueloop queue list
cueloop queue show RQ-0001
# let your configured runner plan, implement, and review the task
cueloop run one --profile safe --phases 3
# verify the repo is still healthy and the task moved forward
cueloop queue list
cueloop doctorWhat this gives the team: one tracked queue, one explicit task lifecycle, one local verification path, and the flexibility to swap runners without changing the repo workflow.
No external runner setup required:
cueloop init
cueloop --help
cueloop help-all
cueloop run one --help
cueloop scan --help
cueloop queue list
cueloop queue graph
cueloop queue validate
cueloop doctor
make agent-ciExpected signals:
- Help and queue commands succeed
cueloop doctorexits successfullymake agent-cicompletes with passing checks for the current dependency surface- Source snapshots without
.git/fall back tomake release-gate(macos-cion macOS with Xcode, otherwiseci)
Full scripted version: docs/guides/local-smoke-test.md
CueLoop is local-first, but selected runner CLIs may transmit prompts/context to external APIs depending on your runner configuration.
- Do not place secrets in task text, notes, or tracked config
- Keep runtime artifacts local (
.cueloop/cache/,.cueloop/logs/,.cueloop/workspaces/,.cueloop/undo/,.cueloop/webhooks/) - Use
make pre-public-checkbefore public release windows
Security references:
- Quality/speed depend on selected runner model and prompts
- UI tests are intentionally not part of default
make macos-ci(headed interaction) - Parallel execution is experimental and introduces additional branch/workspace complexity in very large repos
CueLoop follows semantic versioning for the product and the cueloop crate/package.
- Minor/patch releases preserve existing behavior unless explicitly documented
- Breaking CLI/config behavior changes are called out in changelog and migration notes
Details: docs/versioning-policy.md
Start here:
- Documentation Index
- Evaluator Path
- Architecture Overview
- Quick Start
- Local Smoke Test
- CLI Reference
- Configuration
- Project Operating Constitution
- Decisions
- Troubleshooting
- CI and Test Strategy
- Public Readiness Checklist
Policies:
This repository may keep small sanitized runtime state for reproducible examples and documentation.
In most consumer repositories, .cueloop/ is project-local runtime state managed by cueloop init, including the generated .cueloop/README.md guidance file that is intended for agents and operators. Use cueloop migrate runtime-dir --check before applying supported runtime-state migrations.
# Required everyday gate
make agent-ci
# Heaviest final gate before release/publication
make release-gate
# Public-readiness audit
make pre-public-checkmake agent-ci is the command most contributors and agents should use by default. The lower-level targets (ci-docs, ci-fast, ci, macos-ci) still exist, but they are mainly the implementation details behind that router and explicit power-user escape hatches.
MIT