RemainderBot’s default trigger is a weekly subscription reset less than four hours away, with at least 10% of the allowance still available. It puts that expiring coding-agent quota to work.
The open-source project uses the remaining capacity to choose one task, commit a plan, work against a deadline, and open a pull request for human review. It supports Anthropic’s Claude Code and the Codex CLI through their logged-in subscriptions, without a separate API-based workflow.
There is a significant safety qualification: RemainderBot runs coding agents with permission checks disabled. Its README requires a dedicated machine or VPS and explicitly treats that machine as the sandbox. A private repository protects the collected inputs and logs from public publication, while the pull request provides a review gate for the output. Neither safeguard makes unrestricted execution on a personal workstation safe.
The Reset Deadline Determines When Work Starts
Despite the daemon-like behavior, the documented deployment is an hourly cron job. Each tick reads the coding CLIs’ own quota information and decides whether a provider qualifies for a run.
Both default conditions must be met: fewer than four hours before the weekly reset and at least 10% of quota remaining. RemainderBot schedules work around expiring capacity; it does not continuously work through a backlog.
Once triggered, the agent works against a hard deadline derived from the reset time. The project describes sizing the work according to the quota left, with possible outputs including a document, a feature with tests, or a prototype. A task that would be sensible at the start of a subscription week may be a poor choice shortly before reset. The workflow asks the agent to produce something bounded enough to finish and explain, not simply consume the remaining allowance.
If the main run ends without a completion marker, a short finalization pass may reduce scope and document what works. According to the README, that pass cannot add new work, a useful constraint against turning an unfinished task into another open-ended development session.
It is still a workflow rule, not evidence that every task will finish correctly or use the remaining quota efficiently.
One Task Comes From Sources, Goals, and Past Feedback
RemainderBot separates the material that supplies possible work from the instructions that decide its importance.
Configured sources provide a fresh snapshot of task lists, GitHub issues, repository documentation, notes, and other material. Supported adapters include Google Tasks and Docs, local files, selected Markdown content, and commands whose output can supply source material.
Priorities live in GOALS.md: which work matters, what should be delegated, and which activities should stay out of scope. An explicit open request in its manual-goals section takes priority over the other candidates.
Before starting, the agent also reads previous approvals and rejections. It then selects one task, checks whether it is already done, and commits a plan before building.
This gives the user more control than an instruction to “find something useful.” A developer could prioritize customer issues while excluding billing changes. Someone using the tool for business work could favor preparation documents and drafts while reserving final communication for themselves.
The README’s default instructions include no errands, drafts that are never sent, no repeated tasks, and no work requiring the user’s credentials to verify. These are behavioral instructions to the agent, not operating-system access restrictions. Their value depends on the agent following them, so the host must not contain resources it should never touch.
The Pull Request Is a Delivery Record, Not Automatic Deployment
Each published run is meant to explain what exists, how it was verified, and the single next step needed to use it.
The output may live inside the RemainderBot instance as an artifact. Work intended for another repository can be delivered as a patch. The next action could therefore be merging the pull request, applying a patch, pasting a draft, or running a command. Opening a PR does not necessarily mean the bot has directly changed the application where the work will eventually land.
Alongside the output, the run branch preserves a copy of what the agent read and its full log. Reviewers can inspect more than a code diff: the selected task, the plan, the source context, and the execution history are all part of the record.
Feedback is simple. Merging means approval; closing means rejection. The last PR comment or review becomes the note read by a subsequent run, and INBOX.md maintains the status ledger.
A rejection can steer the next attempt without a fresh prompt, provided the reviewer leaves useful feedback. Closing a weak result without explaining the problem gives less direction than identifying an incorrect assumption or excessive scope.
The review gate arrives after execution. A person can withhold adoption of the result, but cannot undo everything an unrestricted agent might have done on its host.
The Machine Is the Security Boundary
RemainderBot’s security model is unusually explicit about its tradeoff: unattended agents need to proceed without stopping for permission prompts, so the operator must isolate the environment in advance.
The README’s setup requirements call for a dedicated machine, such as a small VPS. This is a requirement of the operating model, not an optional deployment preference.
Disabling permission checks removes the interactive opportunity to inspect and reject individual actions. A sensible deployment would keep unrelated personal files, production credentials, and other sensitive resources off the host. The repository also directs users toward least-privilege GitHub authentication.
Private-repository enforcement addresses a separate risk. Every run branch carries source snapshots and logs, so the code refuses to publish to a public repository. Inputs may include private notes, internal issues, or documents that were never intended for publication.
Each control has a distinct role:
- The dedicated machine limits what resources are exposed to unrestricted execution.
- The private repository limits public disclosure through the documented publishing path.
- The pull request lets a human assess the output before adopting it.
A private repository does not restrict the agent’s local execution rights, and a reviewable patch does not establish that the preceding session was harmless. The deadline limits how long a run should continue, not which files or credentials it can access.
Connecting more sources brings another tradeoff. Broader context can improve task selection, but it increases the sensitive material copied into snapshots and retained in run branches. Operators should choose sources deliberately instead of assuming that more context is always better.
Trying It Starts With Observation, Not Automation
RemainderBot is an MIT-licensed Python 3.11-or-newer package with no Python dependencies outside the standard library. Deployment still requires external tools: Git, GitHub’s gh CLI, and Claude Code and/or Codex, authenticated with a subscription. Google-source integrations additionally require gws.
The documented setup creates a new private repository from a clone of the project, retaining the original as an upstream remote. It specifically advises against creating a public-project fork or using a template copy.
On the dedicated host, the initial checks are:
python3 -m remainderbot doctor
python3 -m remainderbot snapshot
python3 -m remainderbot decide --dry-run
Sources
- open-source projectgithub.com
- launch accountariwilson.com
