English · 中文
Stoker
Keep your Claude Code & Codex usage windows lit — on a schedule you choose.
Website · Download · Install · Configuration · Reference
▶ Watch the 40-second film · MP4
What it does
Many Claude and Codex plans limit how much you can use within a 5-hour window. The window
starts with your first message and resets 5 hours later.
Say you start work at 9:00. Your limit resets at 14:00. If a tiny message had gone out at
7:00, it would reset at 12:00, and you would have a fresh window for the afternoon.
Stoker sends that tiny message for you, at the times you pick. This page calls it a
check-in.
- It runs on your Mac. macOS
launchd fires the schedule. Nothing is sent to the author.
- Each tool has its own schedule. Claude and Codex each get their own times and days.
- Check-ins are tiny and read-only. Claude replies
READY. Codex reads one small file in
its own folder. Your real projects are never opened.
- Everything is logged. Each run, its token use, and your quota before and after.
- It skips when there is no point. A tool whose quota is used up is not sent a check-in.
You can use it from the terminal, from the menu bar app, or both. They share one engine and
one config file.
Does your plan need it?
Not every plan has a 5-hour window. Stoker reads the windows your account reports and
recommends a schedule for them. As of November 2026:
| Tool | Plan | 5-hour window | Weekly limit |
|---|
| Claude | Free, Pro, Max, Team*, Enterprise (seat-based) | Yes | Yes, resets at a fixed time |
| Claude | Ultra | No (a temporary one until the account is verified) | Yes, resets at a fixed time |
| Codex | Plus, Business (standard seat) | Yes* | Yes |
| Codex | Pro, Business (premium seat)* | No | Yes, starts on first use* |
* Not confirmed by an official page. Plans change often, so treat the table as a guide.
A window starts when you first use it. A limit that resets at a fixed time does so whatever
you do. What this means for you:
- You have a 5-hour window. Stoker is most useful here. The default schedule
(
07:00, 12:00, 17:00, 22:00) keeps a window open through the day.
- You only have a Codex weekly window. It starts on first use, so one check-in a day is enough.
- You only have a Claude weekly limit. It resets at a fixed time, so check-ins change
nothing. Stoker tells you so, and leaves the choice to you.
To see what Stoker detected for your account, open the app's Settings or run
./install.sh recommend. Stoker only recommends. It never changes or turns off a schedule
by itself.
Requirements
- macOS 14 or later.
- The Claude Code CLI, the Codex CLI, or both, signed in with your subscription.
jq. The menu bar app includes it. For the command line, brew install jq.- Optional, for quota tracking: Node.js (Codex) and the oh-my-claudecode plugin (Claude).
Without the plugin, set
CLAUDE_STATUS_SOURCE=native.
The Claude and ChatGPT desktop apps do not include these CLIs. Install them separately:
curl -fsSL https://claude.ai/install.sh | bash # then run `claude` once to sign in
curl -fsSL https://chatgpt.com/codex/install.sh | sh # then run `codex` once to sign in
Using only one tool? Set ACTIVATION_TOOL=claude or ACTIVATION_TOOL=codex.
Install
Menu bar app
- Download
stoker-gui-<version>.dmg from the
latest release.
- Drag
Stoker.app into Applications and open it from there.
- macOS blocks the first launch because the app is not notarized. Approve it once in
System Settings › Privacy & Security › Open Anyway. On macOS 14, right-click the app
and choose Open instead. INSTALL.md has the exact steps.
- Open Settings... from the menu bar icon, pick your times, and click Save.
- In Settings › Background auth, click Configure token. Scheduled Claude runs need
it. Why.
The schedule keeps running when the app is closed.
Command line
git clone https://github.com/hakupao/stoker.git
cd stoker
cp .env.example .env
./install.sh check # are the tools installed?
./install.sh dry-run # show what would be sent, send nothing
./install.sh install # load the schedule
Then set up sign-in for scheduled Claude runs.
Sign-in for scheduled Claude runs
By default a scheduled run reuses the sign-in from your own Claude Code sessions. That
sign-in is short-lived, so a scheduled run can fail with
401 Invalid authentication credentials. A long-lived token fixes this:
claude setup-token # opens a browser and prints sk-ant-oat01-...
Put the token in .env as CLAUDE_CODE_OAUTH_TOKEN="sk-ant-oat01-...". It uses your existing
subscription and adds no API charges. The app's Configure token button does all of this
for you.
Upgrading
Replace the app or pull the new code. Then run ./install.sh install once, or turn the
schedule off and on in the app. CHANGELOG.md says when a release needs more.
This is the beginning of the README. Read the rest at the original. Read the full README ↗
