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

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. Milestone M2 is complete: the CLI above genuinely works — run/resume drive a real Claude Code session through claude-agent-sdk, sessions and doctor run against your real environment, and domain/application carry a CI-enforced 100% test-coverage gate, verified further by a live test suite (tests/live/) that exercises the actual installed console script against a real account. Milestone M4 (the generated 1:1 REST surface, claudeloop api ...) and M5 (final polish) are still roadmap. 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.