# RemainderBot

> Open-source Python tool that spends unused weekly Claude or Codex subscription quota on reviewable pull requests in a private repo.

RemainderBot is an open-source Python tool by Ari Wilson (arimwilson). It watches the weekly quota of Claude Code and the Codex CLI and, when a reset is near and quota remains, runs an agent that opens a pull request in the user's own private repository. It is released under the MIT license.

## What It Is

RemainderBot is an unattended task runner for coding-agent subscriptions. An hourly cron job reads each CLI's quota numbers. When the weekly reset is less than 4 hours away and at least 10% remains (both are configurable), it starts a run. Each run produces a finished, reviewable piece of work such as a document, a feature with tests, or a prototype.

## How a Run Works

The agent reads a fresh snapshot of the user's sources, a user-written GOALS.md that ranks priorities, and the verdicts on past runs. It picks one task, commits a plan, and builds against a deadline derived from the reset time. If the run ends without a done marker, a finalize pass may only cut scope and write up what works. Every run opens a PR whose body explains what was built, how it was verified, and the one step that ships it. Merging means approval; closing with a comment means rejection, and the next run reads that comment.

## Sources and Setup

Sources are declared in sources.toml. Supported types are Google Tasks, Google Docs, GitHub issues, GitHub roadmaps, GitHub Markdown repos, local files, and arbitrary commands. Each instance is a private repo cloned from upstream, and the code refuses to publish to a public repo unless overridden. It requires Python 3.11+, git, and gh, plus Claude Code and/or the Codex CLI logged in with a subscription. A `doctor` command checks readiness.

## Security Model

The agent runs with permission checks disabled, so the README says to use a dedicated machine and non-root user, a fine-grained GitHub token, and read-only Google scopes. The prompt forbids pushing elsewhere, sending mail, deploying, and spending money, but the README notes the machine is the real sandbox.

## Features
- Hourly cron trigger based on weekly quota reset proximity and remaining percentage
- Reads Claude Code and Codex CLI quota
- GOALS.md-driven task prioritization
- Source snapshots from Google Tasks, Google Docs, GitHub issues, roadmaps, Markdown repos, files, and commands
- Deadline-bound runs with a finalize pass
- Opens pull requests in a private instance repo with verification notes
- PR merge/close feedback read by later runs
- INBOX.md ledger of runs
- Public-repo push guard
- doctor command for readiness checks

## Integrations
Claude Code, Codex CLI, GitHub CLI (gh), Google Workspace CLI (gws), Google Tasks, Google Docs, GitHub

## Platforms
MACOS, LINUX, API, CLI

## Pricing
Open Source

## Links
- Website: https://github.com/arimwilson/openremainderbot
- Documentation: https://github.com/arimwilson/openremainderbot
- Repository: https://github.com/arimwilson/openremainderbot
- EveryDev.ai: https://www.everydev.ai/tools/remainderbot