Free  ·  open-source  ·  runs locally

Automatically start your Codex & Claude Code 5-hour windows on your schedule.

Stop sleeping through the quota you paid for.

TokenKick tracks your 5-hour and weekly usage limits, shows when each window resets, and, once you opt in, sends a tiny request (a kick) to start the next window before you sit down to work. Provider logins stay with the official CLIs on your machine.

$ pipx install tokenkick
See how it works View on GitHub
tk
sample 
~/projects/zoo on main % tk

[->|] token kick

  ____                 _  ___       ____        
 |  _ \ ___  ___  ___ | ||__ \     / ___| ___   
 | |_) / _ \/ __|/ _ \| __|/ /    | |  _ / _ \  
 |  _ <  __/\__ \  __/| |_ |_|    | |_| | (_) | _
 |_| \_\___||___/\___| \__|(_)     \____|\___/ (_)

? What would you like to do? (↑↓ to move, enter to select)
❯ Status        View cached or live provider status
  Kick          Anchor a ready window
  Setup         Discover accounts and configure basics
  Auto-kick     Enable or disable automatic kicks
  Schedule      Configure smart kick windows
  Notifications Configure or test notifications
  Diagnostics   Doctor, history, reset log, Codex buckets
  Daemon        Start, stop, restart, or inspect daemon
  Exit

❯ Status
  ACCOUNT    STATE             RESET       USED       ACTION
  ─────────────────────────────────────────────────────────────
  personal   ● Weekly ready    w ready     w 0% · s 1%   Kick
  work       ● Session ready   s ready     w 18% · s 0%  Kick
  backup     ● Active          s 2h 14m    w 18% · s 41% Use
  agency     ● Weekly spent    w 2d 06h    w100% · s12% Wait

→ Kick-ready windows: personal, work · run tk kick --all to anchor them.

Run tk to open this interactive menu.

MIT licensed · free CLI · TUI · Mac app beta Local-first · provider credentials stay local MCP · agent planning and orchestration Codex · Claude support macOS · Linux · self-host friendly
How it works

Observe. Recommend. Act.

TokenKick reads local Codex and Claude Code rate-limit data for your 5-hour and weekly windows, shows which windows are ready, and helps you decide what to do next. If you opt in, it can send one minimal provider-client request to anchor a fresh window on your schedule.

01Observe

Read local quota state.

Reads local Codex and Claude state, plus CodexBar fallbacks where available. No new auth, no token relay. Each account gets a state: Weekly ready, Session ready, stale, or unknown. Global Reset Detection needs 2+ local accounts from one provider.

$ tk status
● personal · Weekly ready
● work · Session ready
● backup · Weekly ready (stale)
02Recommend

Recommend the next account.

Status names the next useful action. With scheduling on, the daemon defers the kick until it lands inside your deep-work block, so no window spills past the end of your day.

$ tk schedule show
→ next kick personal
11:00 (Europe/Berlin)
optimal for 14:00–21:00
03Act

Anchor only after opt-in.

After approval, TokenKick sends one minimal provider-client request per account, records it in the kick log, and can notify your phone. Run it once or as a local service; ntfy and Telegram surface the result wherever you are.

$ tk kick personal
→ kicked "personal" at 14:32 CEST
→ codex weekly window anchored
→ ntfy → topic "tokenkick-yours"
Timing

Time windows for your workday.

A 5-hour window starts counting at your first request, not when you sit down. TokenKick can wait until the right moment, so more of the window lands inside your work block.

Schedule kicks around deep work.

Set work hours per account. TokenKick can defer approved kicks until they line up with your day, and pending kicks survive daemon restarts.

Naive: 14:00 kick → 19:00 reset → 24:00 expiry  (3h post-work waste)
Smart: 11:00 kick → 16:00 reset → 21:00 expiry  (0h post-work waste)

$ tk schedule set --account personal --weekdays 14:00-21:00 --weekends 10:00-16:00

09 11 13 15 17 19 21 23 DEEP WORK · 14:00–21:00 Naive · kick on availability window 1 · 14:00→19:00 window 2 · 19:00→24:00 3h post-work waste Smart · aim the kick kick @ 11:00 window 1 · 11:00→16:00 window 2 · 16:00→21:00 0h post-work waste · both windows fully utilized

Keep coverage across accounts.

With multiple accounts, TokenKick can stagger approved kicks so a fresh window is available across your workday. Use recurring schedules for normal hours, or preview a one-off plan for today before anything changes.

$ tk plan --work-window 11:00-22:00 → preview first; nothing changes yet $ tk plan --work-window 11:00-22:00 --apply → apply after review $ tk schedule show → fresh window coverage: 11:00 → 22:00
Reclaim calculator

See how much window time you could reclaim.

AI coding plans have 5-hour and weekly windows. Estimate how much paid window time drifts unused, with your own assumptions.

Your accounts : example values, edit them

Assumptions

Average drift per fresh window 6 h

How long after a window goes fresh before you'd naturally start using it. Reset at 4 a.m., first prompt at 10 → 6 hours of drift.

Share of that drift TokenKick reclaims 90%

Status reads are best-effort, and TokenKick won't catch literally every window. This is the honest haircut.

Window length (for value estimate) 168 h

Session window = 5 h. Weekly window = 168 h (confirmed for Anthropic; not fully confirmed for OpenAI, adjust if you prefer). Drives the dollar estimate only.

What you'd reclaim

FRESH · est. monthly
0hrs / mo

of paid window time that would otherwise drift unused

Estimated paid-window value $0 /month
▲ estimate, derived from the assumptions you set above

how this is calculated
// per account
hours = missed × drift × (reclaim ÷ 100)
value = $/month × (drift ÷ window) × missed × (reclaim ÷ 100)
// totals = sum across accounts

No multiplier, no hidden constant. Move any control and watch every number update live.

By account

Estimates only. TokenKick does not increase quota, bypass limits, resell access, or pool accounts. "Value" is pro-rated paid window time, not extra quota or guaranteed savings.
Local-first trust
Trust model
Your credentials stay local.

Not "encrypted at rest." Not "securely stored." TokenKick does not transmit your provider credentials to us. It runs where the official CLIs already run: your laptop, Mac mini, home server, or VPS.

Your ~/.codex, your ~/.claude, OAuth tokens, and cookies stay where the provider CLIs already put them, on hardware you control. TokenKick reads local state, writes local logs, and runs provider-client commands locally. Optional ntfy or Telegram notifications send only the status messages you configure.

Local state
Status, schedules, history, daemon logs, notification routes, and provider homes live on your machine.
Opt-in actions
Approved kicks run through provider-client commands on your machine. Auto-kick requires explicit consent; no token relay, no cloud-held provider login.
Self-hosting
Run the daemon on a server you own if you want always-on coverage. The shipped open-source tool is the runner.

Local stays free. The current CLI, beta Mac app, and local daemon are MIT-licensed and free to use. A hosted TokenKick Cloud tier for cross-machine coordination is planned and may have separate terms; provider credentials still stay on hardware you control.

// laptop, Mac mini, home server, or VPS: same local runner
$ tk setup
$ tk status
$ tk daemon --background

TokenKick does not increase quota, bypass rate limits, resell access, or pool accounts.
Automated kicking is opt-in and may violate provider terms.

CLI

CLI first. TUI when you want it.

Run tk for the interactive TUI. Use commands for scripts and agents; JSON output is available where machines need it. Full reference: tk --help.

install & open
$ pipx install tokenkick $ tk # interactive TUI $ tk setup # discover accounts $ tk update # check / restart daemon
see state
$ tk status $ tk status --refresh # live re-fetch $ tk calendar # upcoming resets $ tk calendar --ics # calendar export $ tk doctor # diagnose wiring
manual kick
$ tk kick "personal" $ tk kick --all # fresh enabled accts $ tk wake "personal" # bootstrap dormant $ tk run # one-shot daemon pass
opt-in automation
$ tk auto enable "personal" # shows ENABLE consent prompt first $ tk daemon --background $ tk poll 5 # poll every 5 min
schedule
$ tk schedule set --account "personal" \ --weekdays 14:00-21:00 \ --weekends 10:00-16:00 $ tk schedule show
notify · audit
$ tk notify --ntfy tokenkick-yours $ tk history # every kick, audited $ tk reset-log # detected resets
▸ For AI agents

Set it up with your coding agent.

Hand your coding agent the prompt below. TokenKick can run headless with TK_NO_INTERACTIVE=1 and return JSON via --json-output, so agents do not get stuck in the menu.

Install and configure TokenKick from tokenkick.dev: run `pipx install tokenkick`, then `TK_NO_INTERACTIVE=1 tk setup`, then show me `tk status --json-output`.
Machine-readable docs live at /llms.txt. For agents, see the Agent playbook. JSON is available on status, calendar, run, history, doctor, update, and reset-log.
▸ MCP

Talk to your agent in normal language.

TokenKick ships a local MCP server. Your agent can read quota state, preview a plan, configure schedules, and apply approved orchestration through guarded commands. Codex and Claude Code can install it directly; other MCP-capable agents can use the same local server. See the MCP setup guide.

Tell it
Say when you will work: "I will be home from 18:30 to midnight" or "I am at the office 09:00 to 17:00."
Preview it
Your agent reads cached status, runs tk plan, and shows the proposed account timeline before anything changes.
Apply it
After approval, the agent can create pending kicks or recurring schedules through TokenKick's guarded commands. Quota-consuming actions require explicit confirmation.
// install MCP into Codex or Claude
$ tk mcp install --client codex --yes
$ tk mcp install --client claude-code --yes

// example request to your agent
"I'll be home at 18:30 and want coverage until midnight. Check TokenKick and make the best plan."

Voice can work through your agent intake. TokenKick's own Telegram listener stays read-only for lightweight checks: /status, /refresh, and /ping.

FAQ

Honest answers.

Does TokenKick bypass rate limits or get me more quota?
No. TokenKick does not increase quota, bypass rate limits, resell access, pool accounts, or evade provider restrictions. It helps you start the windows you've already paid for on your schedule instead of the provider's. Providers may treat automated or scheduled requests differently from manual use; automated kicking is opt-in and may violate provider terms.
Can TokenKick start my Codex or Claude Code 5-hour window automatically?
Yes, after you opt in. Codex and Claude Code limit usage in 5-hour and weekly windows, and where the countdown starts at your first request, a window you don't touch is time you don't get back. Run tk setup, then tk auto enable "<label>" (it asks for provider-specific risk consent first). TokenKick sends one tiny request (a kick) when a window is fresh. Add tk schedule set --account "<label>" --weekdays 09:00-17:00 to aim kicks at your work hours instead of firing at 3 a.m. Guides: how the Codex 5-hour window works and scheduling Claude Code around your workday.
How is TokenKick different from a cron job or a simple auto-activate script?
A cron job or a keep-alive script fires on a timer or the instant a window resets, which can start your 5-hour window while you sleep and burn it before you work. TokenKick reads each account's actual window state, kicks only when a window is fresh, lets you set work-hour schedules, handles Codex and Claude Code across several accounts, logs every kick in tk history, and keeps automation off until you opt in per account.
Which providers are supported?
Auto-kick targets Codex and Claude accounts, and both require explicit risk consent before automation is saved. Antigravity and Gemini are monitor-only: observed where data is available, never kicked. Gemini's daily RPD reset at midnight Pacific means a kick cannot anchor a useful rolling window. TokenKick reads rate-limit data from Codex app-server, CodexBar, and local session files where available.
Is TokenKick only a command-line tool?
No. The CLI includes an interactive TUI when you run bare tk, and the native Mac app beta gives the same local-first model a desktop surface. The CLI is the recommended install path; Mac app beta DMGs are published through GitHub Releases when available and may show a macOS security warning if not notarized. The current CLI, Mac app beta, and local daemon are MIT-licensed and free to use. Future hosted services may have separate terms, without moving provider credentials into TokenKick's cloud.
What is a "kick"? Is it suspicious activity?
A kick is a single minimal provider-client request, the same kind of tiny action a human could do manually. For providers with first-use-anchored windows, that's the moment the new countdown starts. The kick log is auditable: tk history --json-output shows user-meaningful attempts, confirmations, failures, timestamps, and available token evidence.
Does a kick spend tokens or quota?
Yes, a tiny amount. A kick is real provider work, intentionally small, because a fake request would not anchor anything. TokenKick keeps the action bounded, records token evidence when the provider exposes it, and lets you decide which accounts are allowed to auto-kick.
Does TokenKick ever see my provider login?
No. TokenKick does not transmit your provider credentials to us. It runs locally and talks to the official CLIs already installed on your machine. Your ~/.codex, your ~/.claude, OAuth tokens, and cookies stay where the official CLIs already put them, on hardware you control.
What happens if my laptop is asleep?
Nothing magic. A sleeping laptop cannot run the daemon, read status, or fire a kick. TokenKick will catch up when the machine wakes, but always-on coverage needs an always-on machine: a Mac mini, home server, VPS, or any box where your official CLIs can run.
Can I run TokenKick on my own server?
Yes. Install the same free tool on a VPS, Mac mini, home server, or any machine that can run the official provider CLIs. Run tk setup, enable the accounts you want, then start tk daemon --background. That self-hosted daemon is the always-on runner.
Can I audit what TokenKick did?
Yes. tk history shows user-meaningful kick attempts, confirmations, failures, timestamps, and token evidence where available. tk history --json-output is there for scripts, and the daemon log explains why TokenKick acted, skipped, deferred, or notified.
Can I turn automation off?
Yes. Setup keeps new accounts auto-kick disabled until you opt in. Use tk auto disable "<label>" to stop automation for an account, tk daemon --stop to stop the background loop, and tk notify or account notification settings to change alerts without touching provider logins.
Does TokenKick "catch every reset"?
No, and we won't claim it does. Status reads are best-effort. The reclaim calculator lets you set the honest haircut yourself (default: 90%). TokenKick watches for fresh windows and kicks when fresh; it helps you aim, it doesn't guarantee zero misses. Separate from normal fresh-window tracking, Global Reset Detection is local and correlational: it needs at least two monitored accounts from the same provider. With one account, TokenKick can record a provider reset observation, but it cannot prove a global reset. Real numbers, real assumptions, in the open.
tokenkick
Reset? Go.
your machine executes · your login stays yours · MIT licensed