{"id":51325894,"url":"https://github.com/fitchmultz/cueloop","last_synced_at":"2026-07-01T18:03:45.733Z","repository":{"id":342656549,"uuid":"1134308632","full_name":"fitchmultz/cueloop","owner":"fitchmultz","description":"Rust CLI and macOS app for queue-driven, auditable AI coding agent work.","archived":false,"fork":false,"pushed_at":"2026-06-22T15:33:31.000Z","size":124513,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-22T17:09:22.208Z","etag":null,"topics":["agentic-workflows","ai","automation","cli","developer-tools","rust","swiftui","task-queue"],"latest_commit_sha":null,"homepage":null,"language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/fitchmultz.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":"docs/support-policy.md","governance":null,"roadmap":"docs/roadmap.md","authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-01-14T14:44:25.000Z","updated_at":"2026-06-22T15:33:56.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/fitchmultz/cueloop","commit_stats":null,"previous_names":["fitchmultz/ralph","fitchmultz/cueloop"],"tags_count":16,"template":false,"template_full_name":null,"purl":"pkg:github/fitchmultz/cueloop","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fitchmultz%2Fcueloop","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fitchmultz%2Fcueloop/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fitchmultz%2Fcueloop/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fitchmultz%2Fcueloop/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/fitchmultz","download_url":"https://codeload.github.com/fitchmultz/cueloop/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fitchmultz%2Fcueloop/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35017091,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-01T02:00:05.325Z","response_time":130,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agentic-workflows","ai","automation","cli","developer-tools","rust","swiftui","task-queue"],"created_at":"2026-07-01T18:03:44.885Z","updated_at":"2026-07-01T18:03:45.727Z","avatar_url":"https://github.com/fitchmultz.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# CueLoop\n\nCueLoop is a Rust CLI and macOS app for queue-driven, auditable AI coding agent work. Tasks and run state live in plain `.cueloop/` files, so work can be inspected, diffed, resumed, and gated with local commands.\n\n[![crates.io](https://img.shields.io/crates/v/cueloop.svg)](https://crates.io/crates/cueloop)\n[![docs.rs](https://img.shields.io/docsrs/cueloop)](https://docs.rs/cueloop)\n[![GitHub release](https://img.shields.io/github/v/release/fitchmultz/cueloop)](https://github.com/fitchmultz/cueloop/releases/latest)\n\n![CueLoop three-phase agent workflow](docs/assets/images/2026-02-07-workflow-3phase.png)\n\n## What you are seeing\n\nCueLoop is first a durable task ledger for agent work: tasks, status, notes, evidence, handoff state, and done history stay in repo-local files instead of disappearing into chat history. If you want CueLoop to execute work too, the same queue can also move through supervised planning, implementation, review, and local validation phases. Human-runner automation is additive; the plain task ledger remains useful on its own.\n\nYou can inspect the current CLI without configuring an external model runner. Core commands include:\n\n```text\nCommands:\n  queue     Inspect and manage the task queue\n  agent     Track queue work from an already-running agent without spawning runners\n  config    Inspect and manage CueLoop configuration\n  run       Run CueLoop supervisor (executes queued tasks)\n  task      Create and build tasks from freeform requests\n  scan      Scan repository for new tasks and focus areas\n  ...\n\nCommon first commands:\n  cueloop init                         Bootstrap CueLoop in this repo\n  cueloop queue list                   See queued work\n  cueloop agent overview               Compact context for active agents\n  cueloop task \"Fix the flaky test\"    Create a task from a request\n  cueloop run one                      Run the next task\n  ...\n```\n\n## Who this is for\n\nCueLoop is for developers and small teams who already use AI coding agents but need the surrounding workflow to be repeatable:\n\n- evaluators who want a queue-driven AI-agent workflow they can verify quickly\n- maintainers who want AI-generated work to move through the same queue, review, and CI path as human work\n- agent-heavy teams that want to swap runners without rewriting their repo workflow\n- macOS users who want a local app view over the same CLI behavior\n\n## The problem\n\nAd-hoc AI coding works until the team needs to answer basic delivery questions:\n\n- What work is queued, blocked, running, or done?\n- Which agent ran it, with which local checks, and what happened next?\n- Can another developer resume the work from files in the repo?\n- Can we run more than one task without corrupting the branch?\n- Can we change from one agent runner to another without changing the process?\n\nCueLoop’s answer is a plain-file task queue, a supervised runner loop, and local validation gates that remain visible to Git and normal developer tools.\n\n## What CueLoop does\n\n| Problem | Capability | Proof / where to inspect |\n| --- | --- | --- |\n| AI work gets trapped in chat history | Stores active and completed work in repo-local `.cueloop/queue.jsonc` and `.cueloop/done.jsonc` JSONC files | `cueloop queue list`, `cueloop queue validate`, [Queue docs](docs/features/queue.md) |\n| Already-running agents need durable progress state | Provides `cueloop agent ...` commands for compact context, claim/release, notes, evidence, handoff, validation, and evidence-required completion without spawning nested runners | `cueloop agent overview`, `cueloop agent complete --help`, [Agent Usage Guide](docs/guides/agent-usage.md) |\n| Different agent CLIs have different knobs | Normalizes runner selection across `codex`, `opencode`, `gemini`, `claude`, `cursor`, `kimi`, and `pi` when you opt into CueLoop-runner execution | `cueloop runner list`, [CLI reference](docs/cli.md) |\n| “Agent finished” is not enough quality control | Supports one-, two-, and three-phase execution: plan, implement, review/complete | `cueloop run one --phases 3`, [Architecture overview](docs/architecture.md) |\n| Local CI and queue state drift out of sync | Runs configured gates before completion and validates queue/done state after runs | `make agent-ci`, [CI strategy](docs/guides/ci-strategy.md) |\n| Parallel agent work can damage the base repo | Uses isolated worker workspaces for parallel execution and an integration loop for completed workers | `cueloop run loop --parallel \u003cN\u003e`, [Architecture overview](docs/architecture.md#sequence-parallel-worker-lifecycle) |\n| A GUI can become a second source of truth | The SwiftUI macOS app shells out to the same `cueloop` CLI and machine contract | `apps/CueLoopMac/`, [Machine contract](docs/machine-contract.md) |\n\n## Why not just use Codex or Claude Code directly?\n\nCueLoop does not replace agent CLIs. It wraps them in a local task loop: queue, phase, validate, review, and archive work so agent output does not disappear into chat history or hidden SaaS state.\n\n## Fastest way to see it work\n\n### 1. Install the CLI\n\nFrom crates.io:\n\n```bash\ncargo install cueloop\n```\n\nFrom this repository:\n\n```bash\ngit clone https://github.com/fitchmultz/cueloop cueloop\ncd cueloop\nmake install\n# macOS/Homebrew GNU Make users: gmake install\n```\n\n### 2. Run the no-runner smoke path\n\nThis path verifies the CLI and queue model without first wiring up Codex, Claude, Gemini, or another runner:\n\n```bash\ncueloop init\ncueloop --help\ncueloop queue validate\ncueloop queue explain\ncueloop run one --help\n```\n\nExpected result: CueLoop creates or refreshes `.cueloop/` runtime files, command help is available, and queue commands print the current local task state.\n\nFor a reviewer-friendly script, use [docs/guides/local-smoke-test.md](docs/guides/local-smoke-test.md). For a short evaluation route through the repo, use [docs/guides/evaluator-path.md](docs/guides/evaluator-path.md).\n\n### 3. Try one real task-ledger loop\n\nThis path uses CueLoop only for durable task tracking while you or an already-running agent do the work:\n\n```bash\ncueloop task \"Add retry coverage for webhook delivery failures\"\ncueloop agent overview\ncueloop agent start \u003ccreated-task-id\u003e --note \"Started in current session\"\n# do the work with your current tools/agent\ncueloop agent evidence \u003ccreated-task-id\u003e \"make agent-ci passed\"\ncueloop agent complete \u003ccreated-task-id\u003e --evidence \"make agent-ci passed\"\ncueloop agent validate\n```\n\nUse the task ID printed by `cueloop task` or `cueloop queue list`. That demonstrates the ledger loop: request → queue item → active work state → evidence → done archive.\n\nIf you want CueLoop to dispatch and supervise a runner instead, choose a runner/profile and run:\n\n```bash\ncueloop run one --profile safe --phases 3\ncueloop queue validate\n```\n\n## How it works\n\nCueLoop centers on an operator-started loop over repository-local tasks.\n\n```mermaid\nflowchart LR\n  APP[\"macOS App\u003cbr\u003eSwiftUI\"] --\u003e|shells out| CLI[\"cueloop CLI\u003cbr\u003eRust\"]\n  CLI --\u003e|reads/writes| QUEUE[\".cueloop/queue.jsonc\"]\n  CLI --\u003e|reads/writes| DONE[\".cueloop/done.jsonc\"]\n  CLI --\u003e|reads| CONFIG[\".cueloop/config.jsonc\"]\n  CLI --\u003e|spawns| RUNNERS[\"Runner CLIs\u003cbr\u003eCodex / Claude / Gemini / OpenCode / Cursor / Kimi / Pi\"]\n```\n\n1. Tasks live in `.cueloop/queue.jsonc`; terminal tasks are archived to `.cueloop/done.jsonc`.\n2. An already-running agent can use `cueloop agent ...` to claim, start, annotate, hand off, validate, and complete tasks without spawning another runner.\n3. A human can optionally start `cueloop run one`, `cueloop run loop`, or `cueloop run loop --parallel \u003cN\u003e` when they want CueLoop to dispatch and supervise runner CLIs.\n4. CueLoop resolves config, selected profile, runner overrides, queue state, and safety checks for runner-backed execution.\n5. The runner executes one, two, or three supervised phases only in runner mode.\n6. CueLoop runs the configured local gate before runner-mode completion and before any configured publish behavior.\n7. Queue/done state is validated, archived, and finalized according to config.\n8. The macOS app uses the same CLI/machine surfaces rather than a separate workflow engine.\n\nDeeper design notes live in [docs/architecture.md](docs/architecture.md), and command behavior lives in [docs/cli.md](docs/cli.md).\n\n## Current limits and safety posture\n\n- CueLoop stores workflow state in local project files; it is not hosted SaaS. Runner CLIs may still send prompts/context to external services depending on your runner configuration.\n- The safe onboarding path avoids automatic git publishing. Higher-blast-radius profiles such as power-user automation are opt-in.\n- Parallel execution is available but experimental; use it only when branch policy and workspace isolation are understood.\n- macOS UI tests are intentionally outside the default `make macos-ci` gate because they require headed interaction.\n- CueLoop does not replace your existing test/build tools; it calls your configured local gate.\n\nSecurity references: [SECURITY.md](SECURITY.md) and [docs/security-model.md](docs/security-model.md).\n\n## Project map\n\n| Path | Purpose |\n| --- | --- |\n| `crates/cueloop/` | Primary Rust 2024 crate and `cueloop` executable |\n| `crates/cueloop/src/` | CLI, queue, runner, config, migration, plugin, redaction, and support modules |\n| `crates/cueloop/tests/` | Rust integration tests and shared test support |\n| `apps/CueLoopMac/` | SwiftUI macOS app that delegates behavior to the bundled CLI |\n| `docs/` | Product docs, architecture, CLI reference, configuration, security, release, and evaluator guides |\n| `schemas/*.schema.json` | Generated JSON schemas; refresh with `make generate` when sources change |\n| `.cueloop/` | Repo-local task queue, done archive, config, prompt overrides, and runtime artifacts |\n| `Makefile`, `mk/` | Canonical local build, test, release, and verification entrypoints |\n\n## Development and verification\n\nRun commands from the repository root. GNU Make \u003e= 4 is required; on macOS install Homebrew Make and use `gmake` if Apple `make` is first on `PATH`.\n\n```bash\n# Required everyday gate for normal changes\nmake agent-ci\n\n# Fast docs/community gate\nmake ci-docs\n\n# Full Rust release-shaped gate\nmake ci\n\n# macOS app gate\nmake macos-ci\n\n# Final release/platform gate\nmake release-gate\n```\n\n`make agent-ci` routes based on the current local diff. Use [docs/guides/ci-strategy.md](docs/guides/ci-strategy.md) for the full gate map.\n\n## Documentation\n\nStart at [docs/index.md](docs/index.md) for the full map. Common entry points:\n\n- [Evaluator path](docs/guides/evaluator-path.md) — fastest reviewer-friendly route\n- [Quick start](docs/quick-start.md) — install, initialize, and inspect queue state\n- [Feature guides](docs/features/README.md) — queue, tasks, phases, runners, app, plugins, and automation\n- [CLI reference](docs/cli.md) and [Configuration](docs/configuration.md)\n- [Architecture](docs/architecture.md) and [Troubleshooting](docs/troubleshooting.md)\n- [Contributing](CONTRIBUTING.md) and [Changelog](CHANGELOG.md)\n\n## Versioning and license\n\nCueLoop follows semantic versioning for the product and the `cueloop` crate/package. Breaking CLI or config behavior changes are called out in the changelog and migration notes.\n\nLicense: MIT.\n\n## Next action\n\nIf you are evaluating CueLoop, run the [Evaluator Path](docs/guides/evaluator-path.md). If you are ready to try it in a repo, install the CLI and run the no-runner smoke path above first.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffitchmultz%2Fcueloop","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffitchmultz%2Fcueloop","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffitchmultz%2Fcueloop/lists"}