tokenkick 1.0.0__tar.gz

tokenkick-1.0.0/.gitignore

@@ -0,0 +1,45 @@
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+dist/
+build/
+.eggs/
+*.egg
+.venv/
+venv/
+.env
+.env.*
+!.env.example
+!.env.sample
+.mypy_cache/
+.ruff_cache/
+.pytest_cache/
+.coverage
+htmlcov/
+coverage.xml
+*.sqlite
+*.sqlite3
+*.db
+*.log
+*.pid
+*.pem
+*.key
+*.p8
+*.p12
+*.crt
+*.cer
+*.token
+*.secret
+.tokenkick/
+codex-homes/
+claude-homes/
+*.jsonl
+!macos/TokenKickKit/Tests/TokenKickKitTests/Fixtures/*.jsonl
+.build/
+ROADMAP.md
+docs/private/
+docs/internal/
+docs/*PRIVATE*.md
+.DS_Store
+.codex-pet-runs/

tokenkick-1.0.0/CONTRIBUTING.md

@@ -0,0 +1,49 @@
+# Contributing
+
+Thanks for taking the time to improve TokenKick.
+
+## Before You Start
+
+- Keep TokenKick local-first and explicit: no telemetry, hidden network calls,
+  or automatic provider requests without a saved user setting.
+- Auto-kick must remain off by default. Enabling it must go through the
+  consent gate for kickable providers.
+- Do not include real account labels, email addresses, local paths, tokens,
+  provider homes, `.jsonl` logs, or config files in commits, fixtures, issues,
+  or screenshots.
+- Keep public examples synthetic.
+
+## Development
+
+Install the project in a virtual environment or with your preferred local Python
+workflow, then run the checks before submitting changes:
+
+```bash
+ruff check .
+pytest
+```
+
+For macOS app changes, also run the Swift tests from the repo root when the
+bundled runtime is available:
+
+```bash
+env TK_BUNDLED_RUNTIME=/path/to/tk swift test --package-path macos/TokenKickKit
+```
+
+## Pull Requests
+
+- Keep changes focused and describe the user-visible behavior.
+- Add or update tests when behavior changes.
+- Update docs when commands, setup behavior, provider support, or safety
+  defaults change.
+- Avoid broad refactors unless they are necessary for the fix.
+- Do not bump versions, create tags, publish packages, or change release
+  metadata in ordinary contribution PRs.
+
+## Provider And Terms Safety
+
+TokenKick does not increase quota, bypass rate limits, or evade provider
+restrictions. It tracks windows users already have and can optionally send a
+minimal provider-native request after explicit consent. Changes that alter
+kicking, scheduling, setup defaults, daemon behavior, or provider automation
+need extra care and tests.

tokenkick-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Paul Kahle
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

tokenkick-1.0.0/PKG-INFO

@@ -0,0 +1,149 @@
+Metadata-Version: 2.4
+Name: tokenkick
+Version: 1.0.0
+Summary: Local CLI for tracking AI coding quota windows, planning reset coverage, and optional explicit provider-native kicks.
+Project-URL: Homepage, https://github.com/noriworks/tokenkick
+Project-URL: Documentation, https://github.com/noriworks/tokenkick#readme
+Project-URL: Repository, https://github.com/noriworks/tokenkick
+Project-URL: Issues, https://github.com/noriworks/tokenkick/issues
+Project-URL: Security, https://github.com/noriworks/tokenkick/security/policy
+Author: Paul Kahle
+License-Expression: MIT
+License-File: LICENSE
+Keywords: ai-coding,claude,cli,codex,developer-tools,mcp,quota,rate-limit
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development
+Classifier: Topic :: System :: Monitoring
+Classifier: Topic :: Utilities
+Requires-Python: >=3.10
+Requires-Dist: click>=8.1
+Requires-Dist: httpx>=0.27
+Requires-Dist: inquirerpy>=0.3.4
+Requires-Dist: mcp>=1.9
+Requires-Dist: prompt-toolkit>=3.0
+Requires-Dist: rich>=13.0
+Requires-Dist: tomli>=2.0; python_version < '3.11'
+Provides-Extra: dev
+Requires-Dist: pytest-cov; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff; extra == 'dev'
+Provides-Extra: notify
+Requires-Dist: httpx; extra == 'notify'
+Description-Content-Type: text/markdown
+
+# TokenKick
+
+**Reset? Go.**
+
+TokenKick is a local CLI for developers juggling multiple AI coding accounts.
+It tracks quota reset windows, shows which account needs attention next, and
+can optionally send a tiny provider request to anchor a newly reset window.
+
+## Quick Start
+
+```bash
+pipx install tokenkick
+tk
+```
+
+The native Mac app is a beta desktop surface for the same local runtime. When
+available, beta DMGs are attached to
+[GitHub Releases](https://github.com/noriworks/tokenkick/releases). The CLI is
+the recommended install path for first-time users; non-notarized beta DMGs may
+show a macOS security warning.
+
+On first run, `tk` opens the TUI and starts with setup when no accounts are
+saved yet. Setup discovers accounts and saves them with auto-kick off by
+default. If you later enable auto-kick for a provider, TokenKick shows a
+provider-specific risk notice and requires you to type `ENABLE` before saving
+the acknowledgment. Interactive setup also offers notifications, daemon start,
+and short schedule/Codex strategy info.
+
+For a manual CLI setup:
+
+```bash
+tk setup
+tk status --refresh
+tk auto enable "<label>"
+tk notify --ntfy tokenkick-yourname
+tk daemon --background
+```
+
+Auto-kick sends minimal provider requests automatically on a schedule. Provider
+terms and any account consequences are your responsibility; use it only if you
+accept that risk.
+
+For scripts and automation, use explicit commands:
+
+```bash
+tk status
+tk status --refresh
+tk remote telegram --background
+tk plan --work-window 18:30-23:30 --json-output
+tk history --verbose
+tk doctor
+```
+
+## Demo
+
+![Synthetic TokenKick status demo](docs/assets/readme-status-demo.svg)
+
+The demo output above is generated from synthetic data with:
+
+```bash
+.venv/bin/python scripts/render-readme-demo.py
+```
+
+## Documentation
+
+- [How TokenKick works](docs/HOW_TOKENKICK_WORKS.md)
+- [Commands](docs/TOKENKICK_COMMANDS.md)
+- [Magic setup (advanced)](docs/MAGIC_SETUP.md)
+- [Agent playbook](docs/AGENT_PLAYBOOK.md)
+- [Providers](docs/PROVIDERS.md)
+- [Changelog](docs/CHANGELOG.md)
+- [Security](SECURITY.md)
+- [Contributing](CONTRIBUTING.md)
+
+## Provider Support
+
+Codex and Claude are kickable in this release. Gemini, Antigravity,
+OpenRouter, and other unverified providers are monitor-only until their status
+and safe kick behavior are verified.
+
+TokenKick does not increase quota, bypass limits, or evade provider
+restrictions. It helps you notice and act on quota windows you already have.
+
+Codex-Spark is detected as a separate Codex quota bucket when the provider
+exposes it. TokenKick then shows it as a sibling account such as
+`codex-spark (...)` with its own session/weekly window. It does not infer Spark
+access from your subscription tier. `tk plan` skips Spark until you set an
+explicit `usable_session_minutes` for that account, because the rough placeholder
+is not enough evidence for orchestration decisions.
+
+## Disclaimer
+
+TokenKick is an independent, open-source project. It is not affiliated with,
+endorsed by, or sponsored by OpenAI, Anthropic, Google, or any other provider.
+"Codex", "ChatGPT", "Claude", and "Gemini" are trademarks of their respective
+owners, used here only to describe compatibility.
+
+TokenKick does not increase your quota, bypass rate limits, or evade any
+provider restriction. It helps you track your own reset windows and, optionally,
+send a minimal request through a provider's official CLI to anchor a window you
+have already paid for.
+
+**Automated or scheduled kicking may violate a provider's Terms of Service.**
+Some providers restrict automated or scripted access to their consumer products.
+Enabling auto-kick is your decision and your responsibility. You alone are
+responsible for how you use TokenKick with your accounts and for complying with
+each provider's terms. Use at your own risk.
+
+TokenKick is provided "as is", without warranty of any kind. The authors are
+not liable for any consequence arising from its use, including account
+restriction, suspension, or loss of access.

tokenkick-1.0.0/README.md

@@ -0,0 +1,111 @@
+# TokenKick
+
+**Reset? Go.**
+
+TokenKick is a local CLI for developers juggling multiple AI coding accounts.
+It tracks quota reset windows, shows which account needs attention next, and
+can optionally send a tiny provider request to anchor a newly reset window.
+
+## Quick Start
+
+```bash
+pipx install tokenkick
+tk
+```
+
+The native Mac app is a beta desktop surface for the same local runtime. When
+available, beta DMGs are attached to
+[GitHub Releases](https://github.com/noriworks/tokenkick/releases). The CLI is
+the recommended install path for first-time users; non-notarized beta DMGs may
+show a macOS security warning.
+
+On first run, `tk` opens the TUI and starts with setup when no accounts are
+saved yet. Setup discovers accounts and saves them with auto-kick off by
+default. If you later enable auto-kick for a provider, TokenKick shows a
+provider-specific risk notice and requires you to type `ENABLE` before saving
+the acknowledgment. Interactive setup also offers notifications, daemon start,
+and short schedule/Codex strategy info.
+
+For a manual CLI setup:
+
+```bash
+tk setup
+tk status --refresh
+tk auto enable "<label>"
+tk notify --ntfy tokenkick-yourname
+tk daemon --background
+```
+
+Auto-kick sends minimal provider requests automatically on a schedule. Provider
+terms and any account consequences are your responsibility; use it only if you
+accept that risk.
+
+For scripts and automation, use explicit commands:
+
+```bash
+tk status
+tk status --refresh
+tk remote telegram --background
+tk plan --work-window 18:30-23:30 --json-output
+tk history --verbose
+tk doctor
+```
+
+## Demo
+
+![Synthetic TokenKick status demo](docs/assets/readme-status-demo.svg)
+
+The demo output above is generated from synthetic data with:
+
+```bash
+.venv/bin/python scripts/render-readme-demo.py
+```
+
+## Documentation
+
+- [How TokenKick works](docs/HOW_TOKENKICK_WORKS.md)
+- [Commands](docs/TOKENKICK_COMMANDS.md)
+- [Magic setup (advanced)](docs/MAGIC_SETUP.md)
+- [Agent playbook](docs/AGENT_PLAYBOOK.md)
+- [Providers](docs/PROVIDERS.md)
+- [Changelog](docs/CHANGELOG.md)
+- [Security](SECURITY.md)
+- [Contributing](CONTRIBUTING.md)
+
+## Provider Support
+
+Codex and Claude are kickable in this release. Gemini, Antigravity,
+OpenRouter, and other unverified providers are monitor-only until their status
+and safe kick behavior are verified.
+
+TokenKick does not increase quota, bypass limits, or evade provider
+restrictions. It helps you notice and act on quota windows you already have.
+
+Codex-Spark is detected as a separate Codex quota bucket when the provider
+exposes it. TokenKick then shows it as a sibling account such as
+`codex-spark (...)` with its own session/weekly window. It does not infer Spark
+access from your subscription tier. `tk plan` skips Spark until you set an
+explicit `usable_session_minutes` for that account, because the rough placeholder
+is not enough evidence for orchestration decisions.
+
+## Disclaimer
+
+TokenKick is an independent, open-source project. It is not affiliated with,
+endorsed by, or sponsored by OpenAI, Anthropic, Google, or any other provider.
+"Codex", "ChatGPT", "Claude", and "Gemini" are trademarks of their respective
+owners, used here only to describe compatibility.
+
+TokenKick does not increase your quota, bypass rate limits, or evade any
+provider restriction. It helps you track your own reset windows and, optionally,
+send a minimal request through a provider's official CLI to anchor a window you
+have already paid for.
+
+**Automated or scheduled kicking may violate a provider's Terms of Service.**
+Some providers restrict automated or scripted access to their consumer products.
+Enabling auto-kick is your decision and your responsibility. You alone are
+responsible for how you use TokenKick with your accounts and for complying with
+each provider's terms. Use at your own risk.
+
+TokenKick is provided "as is", without warranty of any kind. The authors are
+not liable for any consequence arising from its use, including account
+restriction, suspension, or loss of access.

tokenkick-1.0.0/SECURITY.md

@@ -0,0 +1,34 @@
+# Security Policy
+
+## Reporting A Vulnerability
+
+Please do not open a public issue for suspected vulnerabilities, leaked secrets,
+or account-safety problems.
+
+Report security issues privately through GitHub private vulnerability reporting
+on the public repository once it is enabled. If that is unavailable, use the
+private contact channel published by the maintainer. Include:
+
+- affected TokenKick version or commit
+- operating system and install method
+- the command or workflow involved
+- a concise reproduction, if safe to share
+- any logs or screenshots with account IDs, tokens, homes, and local paths
+  redacted
+
+I will acknowledge reports as quickly as practical, investigate, and coordinate
+a fix before public disclosure when the issue is confirmed.
+
+## Scope
+
+Security-sensitive areas include:
+
+- leaked or mishandled provider credentials, tokens, or local account state
+- accidental exposure of `~/.tokenkick/`, Codex homes, Claude config, or logs
+- unintended automatic provider requests
+- daemon behavior that acts without an explicit saved setting
+- release artifacts or docs that include private account data
+
+TokenKick is a local tool and does not run a hosted service for users in this
+release. Provider-account enforcement, quota policy, and Terms of Service
+questions should be handled with the relevant provider.