claude-master-toolkit 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Oliver Calderon
+
+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,99 @@
+# workctl
+
+**Token-efficient CLI + metrics dashboard for [Claude Code](https://claude.ai/code).**
+
+See what your sessions actually cost. Cut context bloat before it bites. Query your history in a real dashboard instead of squinting at `/cost`.
+
+```bash
+npm install -g workctl
+workctl dashboard
+```
+
+Opens a local dashboard at `http://localhost:3200` backed by SQLite. Reads your Claude Code session JSONL files directly — no API keys, no telemetry, no accounts.
+
+---
+
+## Why
+
+Claude Code stores every session as JSONL under `~/.claude/projects/`. That's the source of truth for real token usage and cost — but there's no good way to see it. `workctl` parses those files into SQLite and gives you:
+
+- **Realized cost** per session, per project, per day — using the actual Claude 4.6 / 4.5 pricing table.
+- **Context window telemetry** — know when you're about to hit the 200k wall before the warning.
+- **Token-saving primitives** for the Bash tool — `slice`, `find`, `git-log`, `test-summary` — return compact output instead of full files.
+- **A dashboard** (React + Recharts) that lives on your machine. Nothing leaves it.
+
+Think of it as the missing `/cost` page for Claude Code.
+
+## Install
+
+```bash
+npm install -g workctl
+```
+
+Requires Node 18+. The database auto-initializes on first run at `~/.claude/state/claude-master-toolkit/ctk.sqlite`.
+
+## Usage
+
+### Dashboard
+
+```bash
+workctl dashboard              # http://localhost:3200
+workctl dashboard -p 4000      # custom port
+workctl dashboard --no-open    # don't auto-open browser
+```
+
+The server watches `~/.claude/projects/` and syncs new session events in real time.
+
+### CLI primitives
+
+All commands are designed to return **compact, Claude-friendly output** — ideal for the `Bash` tool in agent loops.
+
+| Command | What it does |
+|---|---|
+| `workctl cost [--quiet]` | Realized cost of the current session (reads session JSONL, applies pricing) |
+| `workctl context` | Current window usage, cumulative totals, cost, threshold advice |
+| `workctl tokens [file]` | Rough token count for a file or stdin (`chars / 4`) |
+| `workctl estimate <file>` | Faithful pre-flight count via Anthropic `count_tokens` API |
+| `workctl slice <file> <symbol>` | Extract just one function / class / type from a file |
+| `workctl find <query> [path]` | Ranked ripgrep, top 20 results |
+| `workctl git-log [N]` | One-line log for last N commits |
+| `workctl git-changed` | Files changed vs main branch with line counts |
+| `workctl test-summary [cmd]` | Run a test command, print only pass/fail summary |
+| `workctl model <phase>` | Model alias recommendation per SDD phase |
+| `workctl dashboard` | Launch the local metrics dashboard |
+
+Every command supports `--json` for machine-readable output.
+
+> **`ctk` alias.** The binary is also installed as `ctk` for backwards compatibility. Use whichever you prefer.
+
+## Cost accuracy
+
+Three fidelity sources, picked per use case:
+
+| Source | Fidelity | Used by |
+|---|---|---|
+| Session JSONL (`~/.claude/projects/*/*.jsonl`) | **100%** — real API-charged counts | `cost`, `context`, dashboard |
+| Anthropic `count_tokens` API | **100%** — official endpoint | `estimate` (needs `ANTHROPIC_API_KEY`) |
+| `chars / 4` | rough | `tokens`, fallback for `estimate` |
+
+Pricing table is hard-coded in `src/shared/pricing.ts` for the Claude 4.6 / 4.5 family. Update there when Anthropic changes prices.
+
+## Context window vs cumulative cost
+
+These are **different metrics** and `workctl` reports both:
+
+- **Context window** = what Claude sees right now. Equals the last turn's `input + cache_read + output`. Not a running sum — summing double-counts cache reads.
+- **Cumulative cost** = every turn's tokens weighted by per-model prices. This is what `/cost` shows.
+
+Use the window metric to decide when to `/compact` (70 / 85 / 95 % of 200k). Use cumulative to measure spend.
+
+## Privacy
+
+- No network calls except the optional `count_tokens` pre-flight endpoint.
+- No telemetry.
+- Database lives under `~/.claude/state/` on your machine.
+- Override with `CTK_DB_PATH=/custom/path.sqlite`.
+
+## License
+
+MIT — see [LICENSE](./LICENSE).