tktuner 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Matheus Oliveira
+
+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.

package/README.md

@@ -0,0 +1,57 @@
+# TkTuner
+
+> Stop paying Fable prices for Haiku work.
+
+Local-first token usage analytics for Claude Code power users. TkTuner reads the session logs Claude Code already writes to `~/.claude/projects/`, classifies how you actually use the agent (exploration / planning / execution / delegation), and shows where you burn tokens and quota: premium models doing cheap work, poor cache reuse, subagents inheriting expensive models.
+
+**Local first.** `scan` and `report` run 100% on your machine, free, no account. TkTuner never stores message text, thinking content, or tool inputs — only models, token counts, tool names, timestamps and identifiers.
+
+## Usage
+
+```bash
+tktuner scan     # parse ~/.claude/projects/**/*.jsonl incrementally into a local SQLite db
+tktuner report   # terminal report: cost by model, phase×model waste, cache health, quota pressure
+```
+
+Useful flags:
+
+```bash
+tktuner scan --claude-dir <path>   # custom Claude projects dir (default: ~/.claude/projects)
+tktuner scan --full                # ignore incremental state and reparse everything
+tktuner report --days 7            # analysis window (default: 30)
+tktuner report --all               # entire history
+tktuner report --project <name>    # filter by project name substring
+tktuner report --json              # machine-readable output
+tktuner report --debug-session <id-prefix>  # per-turn classification breakdown
+tktuner report --prices <path>     # override the bundled model price table
+```
+
+The local database lives at `$XDG_DATA_HOME/tktuner/tktuner.db` (default `~/.local/share/tktuner/tktuner.db`); override with `--db <path>`.
+
+## Dashboard (tktuner.com)
+
+Optional: sync your usage **metadata** to a hosted dashboard with history, charts and multi-device support.
+
+```bash
+tktuner login          # device flow — approve in the browser
+tktuner sync           # scan, then upload new turns (numbers only, gzip batches)
+tktuner sync --dry-run # audit exactly what would be uploaded
+tktuner hook install   # opt-in: auto-sync when a Claude Code session ends
+tktuner whoami         # account, device and sync state
+tktuner logout         # revoke this device and delete local credentials
+```
+
+What syncs: token counts, model ids, tool **names**, timestamps, session ids, `sha256(project path)` + the folder's basename, session slugs, text **lengths**. What never syncs (and is never even stored locally): prompts, answers, thinking content, tool inputs/outputs, file paths, git branches. `--dry-run` shows the exact payload.
+
+## Requirements
+
+- Node.js >= 20
+- `better-sqlite3` ships prebuilt binaries for common platforms; if your platform has none, a C++ toolchain (`build-essential`) is required to compile it.
+
+## Status
+
+Local analytics + dashboard sync. Prescription (`optimize` / `apply` — a generated `.claude/` folder tuned to your usage profile) is next.
+
+## License
+
+MIT