feat: Budget & Token Tracker spec (Phase 4)

.gitignore

@@ -0,0 +1,21 @@
+# Python build artifacts
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+*.egg
+
+# Virtual environments
+.venv/
+venv/
+env/
+
+# Node
+node_modules/
+
+# OS
+.DS_Store
+
+# wtcraft worktrees
+worktrees/

.worktree-task.md

@@ -0,0 +1,46 @@
+---
+branch: feat/budget-tracker
+agent: codex
+status: ready
+created: 2026-05-27
+priority: high
+base: feat/automate-github-releases
+---
+
+## Scope
+
+- src/wtcraft/_shell.sh
+- src/wtcraft/_budget.py
+- templates/worktrees/.worktree-task.md
+- templates/.claude/commands/planwt.md
+- templates/.gemini/commands/planwt.toml
+
+## Steps
+
+- [ ] [D] Research Claude session JSONL schema and map local user log directories.
+- [ ] [A] Create `src/wtcraft/_budget.py` with CLI log parsing, USD pricing conversion, and budget limit checks.
+- [ ] [A] Implement rule-based heuristics for Velocity Alert, Cache Efficiency, and Model Routing in `src/wtcraft/_budget.py`.
+- [ ] [A] Modify `src/wtcraft/_shell.sh` to add the `budget` command and inject before/after task event hooks.
+- [ ] [A] Update `templates/worktrees/.worktree-task.md` with default budget frontmatter.
+- [ ] [A] Support both Claude skills (`planwt.md`) and Gemini CLI custom commands (`planwt.toml`) templates.
+- [ ] [D] Verify execution manually against real local agent logs.
+- [ ] [D] Run smoke tests (`tests/smoke.sh`) and ensure it passes successfully.
+
+## Off-limits
+
+- package.json
+- pyproject.toml
+- CLAUDE.md
+- AGENTS.md
+
+## Context
+
+- Claude session logs are stored at `~/.claude/projects/<project-dir-name>/*.jsonl`.
+- Pricing for Sonnet 3.5: $3.00 input, $15.00 output, $3.75 cache write, $0.30 cache read per million tokens.
+- Maintain compatibility with global npm/pip installations.
+
+## Verification
+
+- [ ] python3 -c "import os; print(os.path.exists('src/wtcraft/_budget.py'))"
+- [ ] ./scripts/wtcraft help budget
+- [ ] ./tests/smoke.sh

README.md

@@ -6,6 +6,8 @@
 [![GitHub release](https://img.shields.io/github/v/release/zywkloo/wtcraft?logo=github&maxAge=300)](https://github.com/zywkloo/wtcraft/releases)
 [![License](https://img.shields.io/github/license/zywkloo/wtcraft)](./LICENSE)
 
+> 💡 **Looking for a lightweight, zero-bloat multi-agent control flow?** If you want explicit, budget-aware orchestration without Codex/Claude Desktop app installations, you're in the right place! `wtcraft` is a git-native harness designed to give you precise control with minimal overhead.
+
 **Budget-Aware Multi-Agent Harness**
 
 <p align="center">
@@ -169,6 +171,9 @@ Fowler describes *what* harness engineering is. Stripe and OpenAI describe *how*
 
 - [Roadmap](./docs/roadmap.md)
 - [Principles](./docs/principles.md)
+- [Token Budget — Positioning and User Narratives](./docs/budget/token-budget.md)
+- [Token Budget — Command and Heuristics Specification](./docs/budget/budget.md)
+- [Token Budget — Handoff & Routing Design Notes](./docs/budget/handoff-and-routing.md) (planning; model identifiers need ongoing maintenance)
 - [Migration Notes](./docs/migration.md)
 - [Changelog](./CHANGELOG.md)
 

docs/budget/budget.md

@@ -0,0 +1,66 @@
+# wtcraft Budget & Token Tracker (Token Budget AI Assistant)
+
+Positioning: **Control your agent API spending with git-native usage tracking.**
+
+Solo developers orchestrating multiple coding agents face a common risk: **runaway API costs**. A loop-happy agent or a bloated context window can quietly consume $10–$50 in a single afternoon. 
+
+`wtcraft` integrates a local, rule-based **Token Budget AI Assistant** designed to parse agent execution logs, project token burn rates, and recommend immediate cost-saving adjustments at every hook in your workflow.
+
+---
+
+## 1. Hybrid Configuration Model
+
+You define your budget rules transparently, with flexible overrides:
+
+- **Project Defaults:** Configured directly in the frontmatter of `.agent-harness/planner.md` (which templates into each `.worktree-task.md`):
+  ```yaml
+  max_task_budget: 2.00   # Max USD allowed for this task
+  alert_threshold: 0.80   # Warn at 80% consumption
+  ```
+- **Runtime Overrides:** Set via environment variables for easy manual or automation overrides:
+  ```bash
+  export WTCRAFT_MAX_BUDGET=5.00
+  ```
+
+---
+
+## 2. Real-time Event Hooks (Velocity, Cache & Models)
+
+Instead of checking your API dashboard post-factum, `wtcraft` gives you active budget feedback during the lifecycle of each task:
+
+### Phase A: Task Initiation (`wtcraft new`)
+When starting a task, the assistant reads the project's recent token velocity and predicts costs:
+- **Velocity Check:** *"Daily budget consumed: $0.42 / $5.00 limit."*
+- **Model Recommendation:** *"This task touches only 2 small files. Consider running with Gemini 1.5 Flash to save ~$0.35 over Claude 3.5 Sonnet."*
+
+### Phase B: Verification loops (`wtcraft verify` / `wtcraft check`)
+Before/after running smoke tests or verification commands, the assistant parses the active worktree session logs:
+- **Burn-Rate Alerts:** If a session's token consumption gradient is steep:
+  > [!WARNING]
+  > **High Token Burn-Rate Detected!**
+  > At your current velocity ($0.62/min), you are projected to exhaust your remaining $0.40 budget in **38 seconds**. Consider committing current changes and restarting the session to compact history.
+- **Cache Optimization Suggestions:** Monitors prompt cache hits to ensure you are maximizing discounts:
+  > [!TIP]
+  > **Cache Efficiency is Low (32%):**
+  > You are paying full price for prompt context. To enable Claude's prompt caching, avoid making minor edits to files outside of your target scope to prevent context invalidation.
+
+---
+
+## 3. The `wtcraft budget` CLI Command
+
+A single, lightweight command to see where your money went across all active session logs (parsing local session records with absolute local privacy):
+
+```bash
+wtcraft budget [--days 7] [--detail]
+```
+
+It outputs a highly readable ASCII table of token metrics, cache hit efficiency, estimated USD spend, and rule-based recommendations to optimize your developer setup.
+
+---
+
+## 4. Supported Agents & Log Parsers
+
+`wtcraft` parses local CLI records to compile its reports:
+1. **Claude Code CLI:** Parses JSONL logs in `~/.claude/projects/` matching the current workspace path.
+2. **Gemini CLI:** Integrates with local Gemini API invocation metrics.
+3. **Aider / Codex:** Parses standard chat history and cost logs where available.