cursorloop

Onion-architected, autonomous Cursor Agent session runner — Composer-first (composer-2.5; Grok is a secondary model profile, not a product). Never blocks on a human, distinguishes a waitable rate-limit window from non-waitable exhausted credits, and resumes safely across usage windows.

What problem this solves

Cursor Agent sessions hit usage limits. A single agent turn ending doesn't tell you whether the task finished or just that turn did. And when Cursor rejects you, you can't tell from the outside whether waiting will ever help — a rate-limit window resets on its own; an exhausted credits balance never will, no matter how long you wait. Cursor does not publish a stable credits discriminator on its RateLimitError, so cursorloop keeps a configurable billing lexicon and, when a signal is ambiguous, biases toward CreditsExhausted — the failure mode is a spurious "top up" notification, never a hang past a fabricated reset.

cursorloop exists to get all three of those distinctions right, automatically, so you can hand it a plan and walk away.

It is a deliberate transplant of the claudeloop design — same state machine, same ports, same run-directory layout — retargeted onto the Cursor Agent SDK (cursor-sdk). There is no Anthropic dependency and no foreign vendor auth env fallback.

Install

Requires Python 3.12+, macOS or Linux, and a Cursor account with CURSOR_API_KEY set for live runs. Windows is not a supported target.

pipx install cursorloop
cursorloop doctor            # --offline skips the live me / models calls

See the installation guide for a from-source setup.

Quickstart

cursorloop doctor                          # fail-fast preflight before a multi-hour unattended run
cursorloop run --plan plan.md              # seed a Cursor Agent from a plan and run to completion
cursorloop resume --agent-id <id>          # continue an existing agent
cursorloop models                          # composer-fast → composer → grok-4.5 → grok → grok-xhigh, plus router-* aliases
cursorloop agents                          # local agents for a workspace (needs a live client)
cursorloop whoami                          # authenticated Cursor account

# Mid-run control (second terminal, same cwd):
cursorloop status
cursorloop logs
cursorloop prompt "Also cover the error path"   # queued for the next turn
cursorloop watch                                # plain-text tail; --ui opens the Textual view
cursorloop hooks status                         # install | restore | diff the autonomy fragment
cursorloop stop                                 # soft stop
cursorloop wind-down                            # finish the turn, write a handoff marker, exit 75
cursorloop savepoints
cursorloop unwind --to <sha-or-ref>
cursorloop reset                                # restore managed hooks after a crashed run

cursorloop cloud me|models|create|get|cancel is a partial Cloud Agents REST surface (ADR-0006); full generation waits on a digest-stable published OpenAPI document.

Why it's different from just retrying on 429

See rate limits and credits and never blocking for the full reasoning.

Documentation

Full docs (built with MkDocs Material) live at https://adammatthewsteinberger.github.io/cursorloop/. The same content is in the docs/ directory on GitHub.

Project status

Pre-1.0, but functional through the M5 milestone: Typer CLI (run / resume / doctor / mid-run control), bootstrap that auto-launches CursorClient.launch_bridge, a full offline-capable doctor checklist, a deterministic pytest -m system harness (scripted agent, no Cursor account), a partial-but-live Cloud Agents surface, a CLI-fallback gateway, and mirrored agent skills. Later releases added the -v/-q verbosity ladder, --run-id, wind-down, and capacity forecasting (measurement only, off by default). Coverage floor is 100% on every layer — domain, application, infrastructure, and CLI.

Contributing

Contributions are welcome — see CONTRIBUTING.md for the gitflow branch model, Conventional Commits requirement, and how to run every quality gate locally.

The GitHub default branch is develop. Open feature PRs into develop. By contributing you agree that your work is licensed under the same MIT License as the rest of this repository, and that you will follow the Code of Conduct.

Agent guidance is mirrored across:

• CLAUDE.md + .claude/skills/ (Claude Code)
• CURSOR.md + .cursor/rules/ (Cursor)
• AGENTS.md + .agents/skills/ (Codex)
• GEMINI.md + .agent/rules/ (Antigravity)

Getting help

See SUPPORT.md for the same map.

Security

This tool merges an autonomy fragment into .cursor/hooks.json for the duration of a run (restored afterward, hash-verified), edits the working tree without waiting on a human, and handles CURSOR_API_KEY. See SECURITY.md for the threat model and how to report a vulnerability.

Related projects

Same contract, different vendor. The four *loop runners share one domain state machine, one set of application ports, and one .<name>loop/runs/<id>/ layout — pick the one that matches the agent you pay for:

Around them:

• vibey — queue-based, six-phase conductor (spec interview → design → build → review → deploy) that drives the four runners as interchangeable engines. PostgreSQL-backed.
• vibey-bootstrap — Azure Functions cross-cutting layer: App Config + Key Vault + App Insights bootstrap, Service Bus plumbing, scaffold CLI.
• vibey-skills — versioned Agent Skills marketplace and deterministic context-packet engine.
• homebrew-tap — brew tap adammatthewsteinberger/tap.

License

MIT — see LICENSE.

Built by Adam Matthew Steinberger · more open source