Keep the fire lit.

Keep your Claude Code & Codex usage windows lit.

A tiny macOS launchd scheduler that sends low-cost check-ins at the times you choose — then logs every run, token, and quota snapshot. Runs entirely on your Mac.

Download for macOS View on GitHub

v0.4.0 · macOS 14+ · Free & open source (MIT)

Default schedule · per tool Default schedule for both Claude and Codex: 07:00, 12:00, 17:00 and 22:00 — set each tool's own times and days.
Stoker activity dashboard

Stoker in 40 seconds.

What it does, how the schedule works, and what you see in the app.

Usage windows reset on a clock — not on your schedule.

If the first prompt of a window lands late, the whole window shifts late. Stoker fires a tiny check-in at fixed times so your windows open when you actually start working.

Fixed start times

Pick the hours and days that match your week — separately for Claude and Codex; each time fires independently.

Quota you can see

The windows your plan has (5-hour, weekly, or both), recorded after every run.

Skips when exhausted

Quota preflight skips a tool gracefully instead of wasting a call.

How it works

Every run is the same calm, four-beat loop.

  1. 1

    Load & lock

    Reads .env, then takes a lock — a trigger that fires at the same moment waits its turn.

  2. 2

    Quota preflight

    Checks quota before sending. Exhausted tools are skipped and logged.

  3. 3

    Send a tiny prompt

    Each CLI gets a tiny check-in, kept to its own folder — no tools run, your real projects never touched.

  4. 4

    Record & release

    Appends usage + quota snapshots, then releases the lock for next time.

Small tool, fully accountable.

Scheduled activation

Triggers Claude Code and Codex through macOS launchd — each tool on its own times and days.

Minimal, safe prompt

Each check-in stays tiny and read-only, kept to its own folder — never your real projects.

Readable run history

Every activation in plain text at logs/activation.log.

Per-run usage records

Structured token and cost rows in logs/usage.jsonl.

Quota snapshots

Whichever windows your plan has (5-hour, weekly, or both), in logs/status.jsonl.

Quota preflight

Skips activation gracefully when a known quota is exhausted.

Fits your plan

Detects the usage windows your plan has and recommends a schedule for them. You decide whether to use it.

Honest about cost. About a quarter of a cent.

Stoker sends real prompts, so it uses real quota. Here is exactly how much.

Claude ~1.6K input tokens · ≈ $0.0025 per activation
Codex ~38K input tokens per activation (~55% cache reads)

≈ $0.30 / month for Claude at 4 activations a day.

The bottleneck is the system prompt each CLI injects — Stoker keeps its own prompt under ~300 tokens.

Built to be watched, not babysat.

A native menu bar app over the same engine — bilingual, light or dark.

Stoker menu bar app
Independent & unofficial 100% local — no data sent to the author Open source · MIT

Not affiliated with, endorsed, or sponsored by Anthropic, OpenAI, or Apple. Stoker uses your real quota; you are responsible for complying with each provider's terms.

Questions, answered plainly.

How much does it cost to run?

About $0.0025 per Claude activation (~1.6K tokens). Roughly $0.30/month at four runs a day. Codex uses your plan quota.

Does it consume my quota?

Yes. It sends real prompts, and that is the point. A tool whose quota is used up is skipped. How much check-ins help depends on your plan. Open Settings in the app, or run ./install.sh recommend, to see.

Is it safe? Does it touch my projects?

No. It runs in its own folder with a tiny read-only check-in, and never reads or modifies your real projects. dry-run and quota send nothing.

Is this official?

No. Stoker is an independent open-source project, not affiliated with Anthropic, OpenAI, or Apple. You are responsible for following their terms.

How do I uninstall?

Run ./install.sh uninstall (or use the menu bar app) to unload and remove the LaunchAgents.

macOS says Stoker can’t be opened — what do I do?

That’s expected on first launch: the app is open source and ad-hoc signed, not notarized. Click Done, then open System Settings › Privacy & Security and click Open Anyway (on macOS 14, right-click the app ▸ Open). If it says the app is damaged, run xattr -dr com.apple.quarantine /Applications/Stoker.app in Terminal. You only do this once.

Light the pilot.

Two ways to install — same scheduler underneath.

CLI / launchd

For terminal users who want the lightest install and direct shell control.

git clone https://github.com/hakupao/stoker.git
cd stoker && cp .env.example .env
./install.sh
View install steps

First launch on a new Mac

Stoker is open source and only ad-hoc signed (no paid Apple notarization), so macOS blocks it the first time. It runs entirely on your Mac and the full source is on GitHub. Approve it once:

  1. 1

    Drag it to Applications

    Open the DMG and drag Stoker.app onto the Applications folder. Launch it from there, not from the DMG.

  2. 2

    Double-click, then click Done

    macOS shows “Stoker” Not Opened — Apple could not verify… Click Done (on macOS 14: Cancel) — not Move to Trash.

  3. 3

    macOS 15 Sequoia / 26 and later

    Open System Settings › Privacy & Security, scroll to Security, and click Open Anyway next to “Stoker” was blocked… Confirm with Touch ID or your password, then click Open Anyway once more. The button only shows for about an hour — if it’s missing, double-click the app again.

  4. 4

    macOS 14 Sonoma

    Right-click (or Control-click) Stoker.app ▸ Open, then click Open in the dialog.

  5. 5

    Still blocked, or “damaged”?

    Run this in Terminal, then open the app again. It only removes the download quarantine flag from this one app.

    xattr -dr com.apple.quarantine /Applications/Stoker.app

Only needed once. Later launches open normally — after updating to a newer version, macOS may ask you to approve it once more.

Keep the fire lit.