# TokenKick

> A free, open-source CLI, TUI, beta Mac app, and MCP surface for developers juggling multiple AI coding subscriptions (Codex, Claude Code). It shows which quota windows are *fresh* and can send minimal provider-client "kicks" after opt-in so a new countdown starts on your schedule - without ever touching your provider login.

TokenKick does not increase quota, bypass rate limits, resell access, or pool accounts. It reads existing local rate-limit state (Codex app-server, CodexBar, local session files) and runs provider-client actions on hardware you control. The shipped CLI, beta Mac app, daemon, and self-hosted runner workflow are free and MIT licensed; a hosted TokenKick Cloud tier for cross-machine coordination is planned.

TokenKick is an independent open-source tool and is not affiliated with, endorsed by, or sponsored by any provider. Provider names and trademarks are used only to describe compatibility. It does not increase quota or bypass limits; it tracks windows you've already paid for. Automated kicking may violate provider terms. Use at your own risk.

## Install

- `pipx install tokenkick` (or `pip install tokenkick`)

## Agent / non-interactive usage

Bare `tk` opens an interactive TUI and will block an automated agent. For scripted, MCP, or agent use:

- Set `TK_NO_INTERACTIVE=1` to disable the menu - e.g. `TK_NO_INTERACTIVE=1 tk status`.
- Add `--json-output` for machine-readable output. Supported on: `status`, `calendar`, `run`, `history`, `doctor`, `update`, `reset-log`.
- Recommended first run: `pipx install tokenkick` -> `TK_NO_INTERACTIVE=1 tk setup` -> `TK_NO_INTERACTIVE=1 tk status --json-output`.
- `tk status` reads a local cache (cheap; fresh within ~2x the daemon poll interval). Use `tk status --refresh` for a live provider read, but sparingly - for Claude a refresh can run `/usage`, which is low-cost but not free. Don't poll `--refresh` in a tight loop.
- Do not touch the user's provider logins; TokenKick reads existing local Codex/Claude state only.

## Core commands

- `tk` - interactive TUI for humans.
- `tk status [--refresh] [--json-output]` - provider state per account (fresh / active / waiting / unknown). `--refresh` forces a live re-fetch.
- `tk setup [--dry-run]` - discover and save accounts from existing Codex homes, CodexBar, and Claude session files.
- `tk kick "<label>" [--force]` / `tk kick --all` - anchor a fresh window via a minimal provider-client request.
- `tk wake "<label>"` - one-time bootstrap kick for an account that was dormant before setup.
- `tk run [--dry-run] [--json-output]` - one-shot: refresh, then kick eligible auto-enabled accounts.
- `tk auto enable "<label>"` - authorize automatic weekly + session kicks after the provider-specific risk consent gate.
- `tk schedule set --account "<label>" --weekdays HH:MM-HH:MM [--weekends HH:MM-HH:MM]` - aim kicks at your work hours.
- `tk calendar [--days N] [--json-output] [--ics]` - upcoming reset windows; `--ics` exports iCalendar.
- `tk daemon --background` / `tk poll <minutes>` - continuous local polling.
- `tk notify --ntfy <topic>` / `tk notify --telegram <token> <chat_id>` - notifications.
- `tk history [--json-output]` - audit log of every kick TokenKick has made.
- `tk doctor [--repair] [--json-output]` - diagnose config, cache, daemon, and providers.
- `tk update [--check] [--json-output]` - compare installed vs running-daemon version.
- `tk mcp serve` / `tk mcp install --client codex --yes` - expose safe TokenKick tools to agents for status reads, plan previews, schedules, and approved orchestration.

## Providers

- Codex (OpenAI Codex CLI / ChatGPT Codex) - monitored and kickable.
- Claude Code (Anthropic) - monitored and kickable.
- Antigravity and Gemini - monitor-only in this release. They are observed where local state is available, but never kicked.

## Links

- GitHub: https://github.com/noriworks/tokenkick
- README: https://github.com/noriworks/tokenkick#readme
- Roadmap: https://github.com/noriworks/tokenkick/blob/main/docs/README.md#roadmap
- Mac app beta DMGs: https://github.com/noriworks/tokenkick/releases