claudeloop

Onion-architected, autonomous Claude Code session runner and full Anthropic SDK CLI — never blocks on a human, distinguishes an exhausted rate-limit window from exhausted credits, and resumes safely across usage windows.

What problem this solves

Claude Code sessions hit usage limits. A claude -p invocation ending doesn't tell you whether the task finished or just that turn did. And when a rate limit rejects you, you can't tell from the outside whether waiting will ever help — a five-hour window resets on its own; an exhausted credits balance never will, no matter how long you wait.

claudeloop exists to get all three of those distinctions right, automatically, so you can hand it a plan and walk away — including handling the case where you top up your account's credits while it's mid-wait, which it notices on the next probe rather than at some fixed deadline.

This project began as legacy/claude_autoresume.py, a single-file script that did this by shelling out to claude -p and regex-scraping its output. claudeloop replaces that with a tested, typed, onion-architected package built on the official claude-agent-sdk. See docs/architecture/decisions/ for why each specific change was made.

Install

pipx install claudeloop

See docs/getting-started/installation.md for requirements and a from-source setup.

Quickstart

claudeloop run handoff.md      # seed a session from a plan file and run to completion
claudeloop resume               # resume whatever you were last working on
claudeloop resume --session-id <id>
claudeloop doctor                # pre-flight checks before a long unattended run
claudeloop api models list       # any Anthropic SDK endpoint (generated; see docs)

Full walkthrough: docs/getting-started/quickstart.md.

Why it's different from just retrying on 429

See docs/guides/rate-limits-and-credits.md and docs/guides/never-blocking.md for the full reasoning.

Documentation

Full docs (built with MkDocs Material) live at https://adammatthewsteinberger.github.io/claudeloop/, and are also readable directly under docs/ in this repo:

Project status

Pre-1.0, but functional through milestone M5. The CLI above genuinely works — run/resume drive Claude Code through claude-agent-sdk, sessions and doctor run against your environment, and claudeloop api exposes a generated 1:1 Anthropic SDK REST surface with a CI drift gate. domain/application carry a CI-enforced 100% test-coverage gate, with a live test suite (tests/live/) exercising the installed console script. See docs/plans/architecture-and-roadmap.md.

Contributing

Contributions are welcome — see CONTRIBUTING.md for the gitflow branch model, Conventional Commits requirement, and how to run every quality gate locally. This repo also ships a set of Claude Code skills that make Claude itself an effective contributor to this specific codebase — see CLAUDE.md.

Security

This tool bypasses Claude Code's interactive permission prompts by design (that's what makes autonomous operation possible) and handles API credentials. See SECURITY.md for the threat model and how to report a vulnerability.

License

MIT — see LICENSE.