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 the architecture decision records for why each specific change was made.

Install

pipx install claudeloop

See the installation guide 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)

# Mid-run control (second terminal, same cwd):
claudeloop status
claudeloop snapshot              # handoff JSON under .claudeloop/runs/<id>/snapshots/
claudeloop logs -f --chatter
claudeloop prompt --now "Also cover the error path"
claudeloop preset high           # or: model / effort
claudeloop permission-mode plan  # mid-run; default at start is always bypass
claudeloop attach ./notes.md
claudeloop response retry
claudeloop watch --stream        # Textual live stream; --replay for history
claudeloop stop                  # soft-stop → stop-summary.md (exit 130)
claudeloop savepoints
claudeloop unwind --to 1         # after stop; git save-point restore

Ops surface (attachments, skills/MCP, memories, chat metadata, slash commands): run resources and chat ops.

Why it's different from just retrying on 429

See rate limits vs. credits and never blocking on a human for the full reasoning.

Documentation

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

Logging

claudeloop run / resume always log to stderr twice for the same events: a human-readable stream and a JSON line stream ("transport": "console_json"), controlled by --log-level. Per-run events.jsonl / audit.jsonl and optional --log-file are separate transports. Details: logging and observability.

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 the architecture roadmap.

Contributing

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

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

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.