tokencast 0.1.0__tar.gz

tokencast-0.1.0/.claude/commands/tokencostscope-version.md

@@ -0,0 +1 @@
+/Volumes/Macintosh HD2/Cowork/Projects/costscope/commands/tokencostscope-version.md

tokencast-0.1.0/.claude/settings.json

@@ -0,0 +1,53 @@
+{
+  "hooks": {
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash '/Volumes/Macintosh HD2/Cowork/Projects/costscope/scripts/tokencast-learn.sh'"
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "Agent",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash '/Volumes/Macintosh HD2/Cowork/Projects/costscope/scripts/tokencast-track.sh'"
+          }
+        ]
+      },
+      {
+        "matcher": "Agent",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash '/Volumes/Macintosh HD2/Cowork/Projects/costscope/scripts/tokencast-agent-hook.sh'"
+          }
+        ]
+      }
+    ],
+    "PreToolUse": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash '/Volumes/Macintosh HD2/Cowork/Projects/costscope/scripts/tokencast-midcheck.sh'"
+          }
+        ]
+      },
+      {
+        "matcher": "Agent",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash '/Volumes/Macintosh HD2/Cowork/Projects/costscope/scripts/tokencast-agent-hook.sh'"
+          }
+        ]
+      }
+    ]
+  }
+}

tokencast-0.1.0/.claude/settings.local.json

@@ -0,0 +1,46 @@
+{
+  "permissions": {
+    "allow": [
+      "mcp__claude_ai_Gmail__gmail_search_messages",
+      "mcp__claude_ai_Gmail__gmail_read_message",
+      "Bash(bash:*)",
+      "Bash(python3:*)",
+      "Bash(gh pr:*)",
+      "Skill(tokencostscope)",
+      "Skill(commit-commands:commit-push-pr)",
+      "Bash(/usr/bin/python3 -m py_compile scripts/update-factors.py)",
+      "mcp__codebase-memory-mcp__list_projects",
+      "mcp__codebase-memory-mcp__index_repository",
+      "Bash(xargs -0 ls -t)",
+      "Bash(/usr/bin/python3 \"/Volumes/Macintosh HD2/Cowork/Projects/costscope/scripts/sum-session-tokens.py\" /Users/kellyl./.claude/projects/-Volumes-Macintosh-HD2-Cowork-Projects-costscope/b9eb66bb-94ad-4e79-aa6d-c99f1b9bffba.jsonl 0)",
+      "WebSearch",
+      "Bash(/usr/bin/python3 -c \"import ast; ast.parse\\(open\\(''/Volumes/Macintosh HD2/Cowork/Projects/costscope/tests/test_decay_weighting.py''\\).read\\(\\)\\); print\\(''OK: test_decay_weighting.py''\\)\")",
+      "Bash(/usr/bin/python3 -c \"import ast; ast.parse\\(open\\(''/Volumes/Macintosh HD2/Cowork/Projects/costscope/tests/test_signature_factors.py''\\).read\\(\\)\\); print\\(''OK: test_signature_factors.py''\\)\")",
+      "Bash(/usr/bin/python3 -c \"import ast; ast.parse\\(open\\(''/Volumes/Macintosh HD2/Cowork/Projects/costscope/tests/test_midcheck.py''\\).read\\(\\)\\); print\\(''OK: test_midcheck.py''\\)\")",
+      "Bash(/usr/bin/python3 -c \"import sys; sys.path.insert\\(0, ''scripts''\\); from update_factors import compute_decay_weights, compute_ewma, trimmed_mean, update_factors; print\\(''imports OK''\\)\")",
+      "Bash(chmod:*)",
+      "Bash(/usr/bin/python3 -c \":*)",
+      "Bash(timeout 1 cat)",
+      "Bash(/usr/bin/python3 -c \"import ast; ast.parse\\(open\\('/Volumes/Macintosh HD2/Cowork/Projects/costscope/tests/test_midcheck.py'\\).read\\(\\)\\); print\\('OK'\\)\")",
+      "mcp__claude_ai_open-brain__capture_thought",
+      "WebFetch(domain:github.com)",
+      "Bash(truncate -s 0 \"/Volumes/Macintosh HD2/Cowork/Projects/costscope/calibration/history.jsonl\")",
+      "Bash(\"/Volumes/Macintosh HD2/Cowork/Projects/costscope/calibration/factors.json\")",
+      "Bash(/usr/bin/python3 \"/Volumes/Macintosh HD2/Cowork/Projects/costscope/scripts/parse_last_estimate.py\" \"/Volumes/Macintosh HD2/Cowork/Projects/costscope/calibration/last-estimate.md\" 2>&1)",
+      "Bash(/usr/bin/python3 \"/Volumes/Macintosh HD2/Cowork/Projects/costscope/scripts/parse_last_estimate.py\" \"/Volumes/Macintosh HD2/Cowork/Projects/costscope/calibration/last-estimate.md\")",
+      "Bash(python3 -c \":*)",
+      "Bash(/opt/homebrew/bin/python3 --version)",
+      "Bash(/usr/bin/python3 --version)",
+      "Bash(ln -s \"/Volumes/Macintosh HD2/Cowork/Projects/costscope\" tokencast)",
+      "Bash(rm tokencostscope:*)",
+      "Bash(sed -i '' 's/## costscope estimate/## tokencast estimate/g' SKILL.md tests/test_cache_write_modeling.py docs/wiki/Home.md)",
+      "Bash(sed -i '' \"s/## costscope estimate \\(v1.x.x\\)/## tokencast estimate \\(v1.x.x\\)/g\" CLAUDE.md)",
+      "Bash(cd:*)",
+      "Bash(gh repo:*)",
+      "Bash(curl:*)",
+      "Bash(pip3 install:*)",
+      "Bash(pip3 --version)",
+      "Bash(/usr/bin/python3 -m build)"
+    ]
+  }
+}

tokencast-0.1.0/.claude/worktrees/pr-review-loop-modeling/.claude/settings.local.json

@@ -0,0 +1,7 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(git:*)"
+    ]
+  }
+}

tokencast-0.1.0/.github/workflows/sync-wiki.yml

@@ -0,0 +1,48 @@
+name: Sync Wiki
+
+on:
+  push:
+    branches:
+      - main
+    paths:
+      - "docs/wiki/**"
+  workflow_dispatch: # allow manual trigger
+
+jobs:
+  sync-wiki:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Push docs/wiki to GitHub Wiki
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          REPO: ${{ github.repository }}
+          COMMIT_SHA: ${{ github.sha }}
+        run: |
+          # Clone the wiki repo (separate git repo at <repo>.wiki.git)
+          git clone \
+            "https://x-access-token:${GH_TOKEN}@github.com/${REPO}.wiki.git" \
+            wiki-repo
+
+          # Sync docs/wiki/ → wiki repo root (delete pages removed from docs/wiki/)
+          rsync -av --delete --exclude='.git' docs/wiki/ wiki-repo/
+
+          cd wiki-repo
+
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          git config user.name "github-actions[bot]"
+
+          git add -A
+
+          if git diff --staged --quiet; then
+            echo "No wiki changes to sync."
+          else
+            git commit -m "Sync wiki from docs/wiki @ ${COMMIT_SHA}"
+            git push
+            echo "Wiki synced successfully."
+          fi

tokencast-0.1.0/.gitignore

@@ -0,0 +1,4 @@
+# Calibration data is per-user and should not be committed
+calibration/history.jsonl
+calibration/factors.json
+calibration/active-estimate.json

tokencast-0.1.0/CLAUDE.md

@@ -0,0 +1,83 @@
+# tokencast
+
+A Claude Code skill that automatically estimates Anthropic API token costs when a development plan is created, and learns from actual usage over time to improve accuracy via calibration factors.
+
+## Repo
+
+- GitHub: `krulewis/tokencast`
+- Current version: 2.1.0
+
+## Key Files
+
+| Path | Purpose |
+|------|---------|
+| `SKILL.md` | Skill definition — activation rules, calculation algorithm, output template |
+| `references/heuristics.md` | Token budgets, pipeline step decompositions, complexity multipliers, parallel discount parameters — all tunable parameters live here |
+| `references/pricing.md` | Model pricing per million tokens, cache rates, step→model mapping |
+| `references/calibration-algorithm.md` | Calibration algorithm documentation |
+| `references/examples.md` | Worked estimation examples |
+| `scripts/tokencast-learn.sh` | Stop hook — reads session JSONL at end of session, computes actuals, calls update-factors.py |
+| `scripts/tokencast-midcheck.sh` | PreToolUse hook for mid-session cost warnings — checks spend vs pessimistic estimate |
+| `scripts/update-factors.py` | Computes and persists calibration factors from completed session data |
+| `scripts/sum-session-tokens.py` | Parses session JSONL to sum token costs |
+| `calibration/` | Calibration data directory — gitignored; contains `active-estimate.json` and `factors.json` |
+| `tests/test_pr_review_loop.py` | Tests for PR Review Loop cost modeling |
+| `tests/test_parallel_agent_accounting.py` | Tests for parallel agent cost discounting |
+| `tests/test_file_size_awareness.py` | Tests for file size bracket computation and auto-measurement |
+| `docs/wiki/` | GitHub wiki source — Home, How-It-Works, Installation, Configuration, Calibration, Roadmap |
+| `README.md` | Repo root README (not inside `.claude/skills/tokencast/`) |
+
+## Test Commands
+
+```bash
+# Run all tests — use system Python 3.9 which has pytest
+/usr/bin/python3 -m pytest tests/
+
+# Run a specific test file
+/usr/bin/python3 -m pytest tests/test_pr_review_loop.py
+
+# Run with verbose output
+/usr/bin/python3 -m pytest tests/ -v
+```
+
+**Do NOT use `pytest` or `python3 -m pytest` directly.** Homebrew `python3` resolves to 3.14 which does NOT have pytest. Always use `/usr/bin/python3`.
+
+## Architecture Conventions
+
+- **All tunable parameters live in `references/heuristics.md`** — not hardcoded in SKILL.md. This includes complexity multipliers, band multipliers, parallel discount factors, cache rate floors, review cycle defaults, decay halflife, per-signature min samples, and midcheck parameters.
+- **Time-decay constants:** `DECAY_HALFLIFE_DAYS = 30` in `update-factors.py` mirrors `decay_halflife_days` in `references/heuristics.md`. `DECAY_MIN_RECORDS = 5` (cold-start guard) is hardcoded in `update-factors.py` and intentionally NOT in heuristics.md — it is a statistical invariant, not user-tunable.
+- **Per-signature factors:** Pass 5 of `update-factors.py` computes per-signature factors from signature-normalized step arrays. Signatures are derived at Pass 1 read time and stored as a private `_canonical_sig` field. In `factors.json`, they live under `signature_factors` and are read with `.get('signature_factors', {})` default for backward compatibility.
+- **Mid-session check:** `tokencast-midcheck.sh` is a PreToolUse hook. It reads `active-estimate.json` and the session JSONL to compute actual spend, then writes state to `calibration/.midcheck-state` (ephemeral, gitignored). Hook is fail-silent via `set -euo pipefail` + `|| exit 0` — failures do not interrupt your work. State file format: two lines — last-checked byte size and cooldown sentinel (`0` or `COOLDOWN:<size>`).
+- **Pipeline signature derivation:** Not written to `active-estimate.json`. SKILL.md Step 3e derives it inline from the `steps` array using the same normalization formula as `learn.sh` line 38.
+- **Shell injection safety** — `learn.sh` and `midcheck.sh` use `shlex.quote()` and env vars pattern to pass data to Python. Never interpolate user-derived strings directly into shell commands.
+- **`active-estimate.json` is the handshake** between estimation (SKILL.md writes it at estimate time) and learning (learn.sh reads it at session end). Schema changes must be backward compatible.
+- **Backward compatibility** — new fields in `active-estimate.json` and `factors.json` schemas use `.get()` defaults in Python so old files don't break newer scripts.
+- **File size brackets** — when file paths are extractable from the plan and files exist on disk, tokencast auto-measures via batched `wc -l` (cap: 30 files). Three brackets: small (≤49 lines) = 3k/1k tokens (read/edit), medium (50–500) = 10k/2.5k, large (≥501) = 20k/5k. Fixed-count file reads in all steps use the weighted-average bracket. Override: `avg_file_lines=N`. Unmeasured files fall back to override bracket or medium default.
+- **`file_brackets` in active-estimate.json** — stores aggregate bracket counts (not per-file data) for future calibration stratification. Schema: `{"small": N, "medium": N, "large": N}` or null. `null` means no paths extracted (not the same as `{"small":0,"medium":0,"large":0}` which means paths extracted but none measurable).
+- **Version string must be consistent** across three places: `SKILL.md` frontmatter (`version:`), output template header (`## tokencast estimate (v1.x.x)`), and `learn.sh` `VERSION` variable. Always update all three together.
+- **PR Review Loop calibration** applies the factor independently to each band (not re-anchored as fixed ratios of calibrated Expected) — this preserves the decay model's per-band cycle counts.
+- **Step 3.5 runs post-step-loop** — the PR Review Loop row computation happens after all individual pipeline steps complete Steps 3a–3e, not inline. Cache each constituent step's pre-discount cost during the per-step loop.
+- **Parallel discount does NOT apply to PR Review Loop C value** — `C` uses undiscounted step costs even when constituent steps were modeled as parallel.
+
+## Memory / Docs Update Paths
+
+When completing work, the `docs-updater` agent should update:
+- `docs/wiki/` — whichever wiki pages cover the changed functionality
+- `MEMORY.md` at `/Users/kellyl./.claude/projects/-Volumes-Macintosh-HD2-Cowork-Projects-costscope/memory/MEMORY.md`
+- `ROADMAP.md` if version or milestone status changed
+
+## Project-Specific Estimate Overrides
+
+- **`review_cycles=4`** — use this override when running `/tokencast` for tokencast changes. The global `heuristics.md` default of 2 is too low for this project; historical data across 5 sessions averages 4–5 passes (v1.3: 5, v1.5: 4, v1.6: 3, v1.7+v2.0: 4, v2.1: 11).
+
+## Gotchas
+
+- **Paths with spaces** — always quote shell paths; use `-print0 | xargs -0` for `find` pipelines. The repo lives at `/Volumes/Macintosh HD2/Cowork/Projects/costscope` — the space in "Macintosh HD2" will break unquoted shell commands.
+- **macOS volume path** — `/Volumes/Macintosh HD2/...` is the working directory; scripts run from there will have the space in the absolute path.
+- **Worktree working directory** — if using git worktrees, the working dir differs from the main repo root. Use absolute paths.
+- **README.md location** — `README.md` is in the repo root (`/Volumes/Macintosh HD2/Cowork/Projects/costscope/README.md`), not inside `.claude/skills/tokencast/`.
+- **`calibration/` is gitignored** — do not commit calibration data. The directory may not exist on a fresh clone; scripts must handle its absence gracefully.
+
+---
+
+<!-- Global pipeline, workflow, agent delegation, and codebase-memory rules are in ~/.claude/CLAUDE.md — loaded automatically every session. No need to duplicate here. -->

tokencast-0.1.0/LICENSE

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

tokencast-0.1.0/PKG-INFO

@@ -0,0 +1,197 @@
+Metadata-Version: 2.4
+Name: tokencast
+Version: 0.1.0
+Summary: Pre-execution cost estimation for LLM agent workflows with calibration learning
+Project-URL: Homepage, https://github.com/krulewis/tokencast
+Project-URL: Documentation, https://github.com/krulewis/tokencast/wiki
+Project-URL: Repository, https://github.com/krulewis/tokencast
+Project-URL: Issues, https://github.com/krulewis/tokencast/issues
+Author-email: Kelly Lewis <krulewis@users.noreply.github.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agent,calibration,cost-estimation,llm,mcp,token-cost
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Topic :: Software Development :: Quality Assurance
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+<p align="center">
+  <img src="assets/tokencast-logo.svg" alt="tokencast logo" width="150">
+</p>
+
+# tokencast
+
+A Claude Code skill that estimates Anthropic API cost for planned agent tasks, then **learns from actual usage** to improve estimates over time.
+
+Install once per project. It auto-estimates after plans are created and auto-learns at session end. Zero ongoing friction.
+
+## Setup (one time per project)
+
+```bash
+# Clone the repo (anywhere — it doesn't need to live inside your project)
+git clone https://github.com/krulewis/tokencast.git
+
+# Install into your project (quote paths with spaces)
+bash tokencast/scripts/install-hooks.sh "/path/to/your-project"
+```
+
+> **Paths with spaces:** Always wrap the project path in quotes. Without them the install script will fail on paths like `/Volumes/Macintosh HD2/...`.
+
+This does three things:
+1. Symlinks the skill into `<project>/.claude/skills/tokencast/`
+2. Adds a `Stop` hook for auto-learning at session end
+3. Adds a `PostToolUse` hook to nudge estimation after planning agents
+
+Every Claude Code session in that project now has tokencast active.
+
+## What Happens Automatically
+
+### After a plan is created
+tokencast detects the plan in conversation context, infers size, files, complexity, project type, and language, then outputs a cost table:
+
+```
+## tokencast estimate
+
+Change: size=M, files=5, complexity=medium
+Calibration: 1.12x from 8 prior runs
+
+| Step                  | Model  | Optimistic | Expected | Pessimistic |
+|-----------------------|--------|------------|----------|-------------|
+| Research Agent        | Sonnet | $0.60      | $1.17    | $4.47       |
+| Architect Agent       | Opus   | $0.67      | $1.18    | $3.97       |
+| ...                   | ...    | ...        | ...      | ...         |
+| TOTAL                 |        | $3.37      | $6.26    | $22.64      |
+```
+
+### At session end
+The learning hook silently:
+1. Reads the session's JSONL log
+2. Computes actual token cost (including cache write tokens)
+3. Compares to the estimate
+4. Updates calibration factors
+
+### Next session
+Future estimates use learned correction factors. More sessions = better accuracy.
+
+## Manual Invocation
+
+You can also invoke explicitly with overrides:
+
+```
+/tokencast size=L files=12 complexity=high
+/tokencast steps=implement,test,qa
+/tokencast review_cycles=3
+/tokencast review_cycles=0
+```
+
+Use `review_cycles=N` to set the number of expected PR review cycles. Use `review_cycles=0` to suppress the PR Review Loop row.
+
+## How It Works
+
+1. Infers size, file count, complexity from the plan in conversation
+2. Reads reference files for pricing and token heuristics
+3. Loads learned calibration factors (if any exist)
+4. Computes per-step token estimates using activity decomposition
+5. Applies complexity multiplier, context accumulation `(K+1)/2`, and cache rates
+6. Splits into Optimistic / Expected / Pessimistic bands
+7. If PR Review Loop is in scope, computes loop cost using geometric decay across N review cycles (Optimistic=1, Expected=N, Pessimistic=N×2)
+8. Applies calibration correction to Expected band (individual steps re-anchor; PR Review Loop scales each band independently)
+9. Records the estimate for later comparison with actuals
+
+## Overrides
+
+| Override | Effect |
+|----------|--------|
+| `size=M` | Set size class explicitly |
+| `files=5` | Set file count explicitly |
+| `complexity=high` | Set complexity explicitly |
+| `steps=implement,test,qa` | Estimate only those pipeline steps |
+| `project_type=migration` | Set project type explicitly |
+| `language=go` | Set primary language explicitly |
+| `review_cycles=3` | Set PR review cycle count (0 = disable) |
+
+## Confidence Bands
+
+| Band        | Cache Hit | Multiplier | Meaning                                |
+|-------------|-----------|------------|----------------------------------------|
+| Optimistic  | 60%       | 0.6x       | Best case — focused agent work         |
+| Expected    | 50%       | 1.0x       | Typical run                            |
+| Pessimistic | 30%       | 3.0x       | With rework loops, debugging, retries  |
+
+## Calibration
+
+Calibration is fully automatic:
+- **0-2 sessions:** No correction applied. "Collecting data" status.
+- **3-10 sessions:** Global correction factor via trimmed mean of actual/expected ratios (trim_fraction=0.1).
+- **10+ sessions:** EWMA with recency weighting. Per-size-class factors activate when a class has 3+ samples.
+- **Outlier filtering:** Sessions with actual/expected ratio >3.0x or <0.2x are excluded from calibration and logged for inspection.
+
+Calibration data lives in `calibration/` (gitignored, local to each user).
+
+## Disabling
+
+```bash
+bash /path/to/tokencast/scripts/disable.sh /path/to/your-project
+```
+
+Removes the skill and hooks. Preserves calibration data for reuse.
+
+## Files
+
+```
+SKILL.md                        — Skill definition (auto-trigger, algorithm)
+references/pricing.md           — Model prices, cache rates, step→model map
+references/heuristics.md        — Token budgets, pipeline decompositions, multipliers
+references/examples.md          — Worked examples with arithmetic
+references/calibration-algorithm.md — Detailed calibration algorithm reference
+commands/
+  tokencast-version.md     — /tokencast-version slash command
+scripts/
+  install-hooks.sh              — One-time project setup
+  disable.sh                    — Remove from project
+  tokencast-learn.sh       — Stop hook: auto-captures actuals
+  tokencast-track.sh       — PostToolUse hook: nudges estimation after plans
+  sum-session-tokens.py         — Parses session JSONL for actual costs
+  update-factors.py             — Computes calibration factors from history
+calibration/                    — Per-user local data (gitignored)
+  history.jsonl                 — Estimate vs actual records
+  factors.json                  — Learned correction factors
+  active-estimate.json          — Transient marker for current estimate
+```
+
+## v1.1 Changes
+
+- **Trimmed mean** replaces median for faster convergence with small samples
+- **Outlier flagging** — extreme ratios (>3.0x or <0.2x) excluded from calibration, logged for inspection
+- **Richer data** — project type, language, pipeline signature, and step count captured per session
+- **Baseline subtraction** — tokens spent before the estimate are excluded from actuals
+- **Security hardening** — path injection fixes, consolidated parsing, safe handling of paths with spaces
+- **Version markers** — `version: 1.1.0` in SKILL.md, `--version` flag on learn script
+
+## v1.2 Changes
+
+- **PR Review Loop modeling** — geometric-decay cost model for review-fix-re-review cycles
+- **New override** — `review_cycles=N` to set expected cycle count (0 = disable)
+- **Per-band calibration** — PR Review Loop applies calibration independently per band (not re-anchored)
+- **New schema fields** — `review_cycles_estimated` and `review_cycles_actual` in active-estimate.json
+
+## Limitations
+
+- Pipeline step names reflect a default workflow — map your own steps to the closest defaults. Formulas are pipeline-agnostic (see `references/heuristics.md`)
+- Heuristics assume typical 150-300 line source files
+- Does not model parallel agent execution
+- Calibration requires 3+ completed sessions before corrections activate
+- Pricing data embedded; check `last_updated` in references/pricing.md
+- Multi-session tasks only capture the session containing the estimate
+
+## License
+
+MIT

tokencast-0.1.0/README.md

@@ -0,0 +1,172 @@
+<p align="center">
+  <img src="assets/tokencast-logo.svg" alt="tokencast logo" width="150">
+</p>
+
+# tokencast
+
+A Claude Code skill that estimates Anthropic API cost for planned agent tasks, then **learns from actual usage** to improve estimates over time.
+
+Install once per project. It auto-estimates after plans are created and auto-learns at session end. Zero ongoing friction.
+
+## Setup (one time per project)
+
+```bash
+# Clone the repo (anywhere — it doesn't need to live inside your project)
+git clone https://github.com/krulewis/tokencast.git
+
+# Install into your project (quote paths with spaces)
+bash tokencast/scripts/install-hooks.sh "/path/to/your-project"
+```
+
+> **Paths with spaces:** Always wrap the project path in quotes. Without them the install script will fail on paths like `/Volumes/Macintosh HD2/...`.
+
+This does three things:
+1. Symlinks the skill into `<project>/.claude/skills/tokencast/`
+2. Adds a `Stop` hook for auto-learning at session end
+3. Adds a `PostToolUse` hook to nudge estimation after planning agents
+
+Every Claude Code session in that project now has tokencast active.
+
+## What Happens Automatically
+
+### After a plan is created
+tokencast detects the plan in conversation context, infers size, files, complexity, project type, and language, then outputs a cost table:
+
+```
+## tokencast estimate
+
+Change: size=M, files=5, complexity=medium
+Calibration: 1.12x from 8 prior runs
+
+| Step                  | Model  | Optimistic | Expected | Pessimistic |
+|-----------------------|--------|------------|----------|-------------|
+| Research Agent        | Sonnet | $0.60      | $1.17    | $4.47       |
+| Architect Agent       | Opus   | $0.67      | $1.18    | $3.97       |
+| ...                   | ...    | ...        | ...      | ...         |
+| TOTAL                 |        | $3.37      | $6.26    | $22.64      |
+```
+
+### At session end
+The learning hook silently:
+1. Reads the session's JSONL log
+2. Computes actual token cost (including cache write tokens)
+3. Compares to the estimate
+4. Updates calibration factors
+
+### Next session
+Future estimates use learned correction factors. More sessions = better accuracy.
+
+## Manual Invocation
+
+You can also invoke explicitly with overrides:
+
+```
+/tokencast size=L files=12 complexity=high
+/tokencast steps=implement,test,qa
+/tokencast review_cycles=3
+/tokencast review_cycles=0
+```
+
+Use `review_cycles=N` to set the number of expected PR review cycles. Use `review_cycles=0` to suppress the PR Review Loop row.
+
+## How It Works
+
+1. Infers size, file count, complexity from the plan in conversation
+2. Reads reference files for pricing and token heuristics
+3. Loads learned calibration factors (if any exist)
+4. Computes per-step token estimates using activity decomposition
+5. Applies complexity multiplier, context accumulation `(K+1)/2`, and cache rates
+6. Splits into Optimistic / Expected / Pessimistic bands
+7. If PR Review Loop is in scope, computes loop cost using geometric decay across N review cycles (Optimistic=1, Expected=N, Pessimistic=N×2)
+8. Applies calibration correction to Expected band (individual steps re-anchor; PR Review Loop scales each band independently)
+9. Records the estimate for later comparison with actuals
+
+## Overrides
+
+| Override | Effect |
+|----------|--------|
+| `size=M` | Set size class explicitly |
+| `files=5` | Set file count explicitly |
+| `complexity=high` | Set complexity explicitly |
+| `steps=implement,test,qa` | Estimate only those pipeline steps |
+| `project_type=migration` | Set project type explicitly |
+| `language=go` | Set primary language explicitly |
+| `review_cycles=3` | Set PR review cycle count (0 = disable) |
+
+## Confidence Bands
+
+| Band        | Cache Hit | Multiplier | Meaning                                |
+|-------------|-----------|------------|----------------------------------------|
+| Optimistic  | 60%       | 0.6x       | Best case — focused agent work         |
+| Expected    | 50%       | 1.0x       | Typical run                            |
+| Pessimistic | 30%       | 3.0x       | With rework loops, debugging, retries  |
+
+## Calibration
+
+Calibration is fully automatic:
+- **0-2 sessions:** No correction applied. "Collecting data" status.
+- **3-10 sessions:** Global correction factor via trimmed mean of actual/expected ratios (trim_fraction=0.1).
+- **10+ sessions:** EWMA with recency weighting. Per-size-class factors activate when a class has 3+ samples.
+- **Outlier filtering:** Sessions with actual/expected ratio >3.0x or <0.2x are excluded from calibration and logged for inspection.
+
+Calibration data lives in `calibration/` (gitignored, local to each user).
+
+## Disabling
+
+```bash
+bash /path/to/tokencast/scripts/disable.sh /path/to/your-project
+```
+
+Removes the skill and hooks. Preserves calibration data for reuse.
+
+## Files
+
+```
+SKILL.md                        — Skill definition (auto-trigger, algorithm)
+references/pricing.md           — Model prices, cache rates, step→model map
+references/heuristics.md        — Token budgets, pipeline decompositions, multipliers
+references/examples.md          — Worked examples with arithmetic
+references/calibration-algorithm.md — Detailed calibration algorithm reference
+commands/
+  tokencast-version.md     — /tokencast-version slash command
+scripts/
+  install-hooks.sh              — One-time project setup
+  disable.sh                    — Remove from project
+  tokencast-learn.sh       — Stop hook: auto-captures actuals
+  tokencast-track.sh       — PostToolUse hook: nudges estimation after plans
+  sum-session-tokens.py         — Parses session JSONL for actual costs
+  update-factors.py             — Computes calibration factors from history
+calibration/                    — Per-user local data (gitignored)
+  history.jsonl                 — Estimate vs actual records
+  factors.json                  — Learned correction factors
+  active-estimate.json          — Transient marker for current estimate
+```
+
+## v1.1 Changes
+
+- **Trimmed mean** replaces median for faster convergence with small samples
+- **Outlier flagging** — extreme ratios (>3.0x or <0.2x) excluded from calibration, logged for inspection
+- **Richer data** — project type, language, pipeline signature, and step count captured per session
+- **Baseline subtraction** — tokens spent before the estimate are excluded from actuals
+- **Security hardening** — path injection fixes, consolidated parsing, safe handling of paths with spaces
+- **Version markers** — `version: 1.1.0` in SKILL.md, `--version` flag on learn script
+
+## v1.2 Changes
+
+- **PR Review Loop modeling** — geometric-decay cost model for review-fix-re-review cycles
+- **New override** — `review_cycles=N` to set expected cycle count (0 = disable)
+- **Per-band calibration** — PR Review Loop applies calibration independently per band (not re-anchored)
+- **New schema fields** — `review_cycles_estimated` and `review_cycles_actual` in active-estimate.json
+
+## Limitations
+
+- Pipeline step names reflect a default workflow — map your own steps to the closest defaults. Formulas are pipeline-agnostic (see `references/heuristics.md`)
+- Heuristics assume typical 150-300 line source files
+- Does not model parallel agent execution
+- Calibration requires 3+ completed sessions before corrections activate
+- Pricing data embedded; check `last_updated` in references/pricing.md
+- Multi-session tasks only capture the session containing the estimate
+
+## License
+
+MIT