token-furnace 0.1.3 → 0.1.5

package/README.md

@@ -1,22 +1,46 @@
 # token-furnace
 
+[![npm version](https://img.shields.io/npm/v/token-furnace)](https://www.npmjs.com/package/token-furnace)
+[![Node.js](https://img.shields.io/node/v/token-furnace)](https://www.npmjs.com/package/token-furnace)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+[![npm downloads](https://img.shields.io/npm/dm/token-furnace)](https://www.npmjs.com/package/token-furnace)
+
 Where the token budget actually went. `token-furnace` reads your local Claude Code and Codex
 transcripts, finds token leaks, and shows the result in your terminal, as JSON for agents, and in a
 local dashboard. Transcript data never leaves your machine.
 
-## Requirements
+## Quick start
 
-- Node.js 22.13 or newer.
+Requires **Node.js 22.13 or newer** and local Claude Code or Codex transcripts.
 
 Run it without installing:
 
+```sh
+npx token-furnace@latest
 ```
-npx token-furnace
+
+Open the live dashboard:
+
+```sh
+npx token-furnace@latest serve
 ```
 
-Or install it globally:
+Visit **http://127.0.0.1:8765**. The first scan measures local usage; later scans reuse a metadata cache.
+Choose Claude Code or Codex independently for each chart, and pin a selection to remember it on reload.
 
+Export a report for scripts or sharing:
+
+```sh
+npx token-furnace@latest --json --no-plan-usage
+npx token-furnace@latest --html report.html
 ```
+
+Reports include session titles and file paths. Review an exported report before sharing it.
+With no transcripts, the CLI exits 1; run `npx token-furnace@latest --list-sources` to see where it looks.
+
+Or install it globally:
+
+```sh
 npm install -g token-furnace
 ```
 
@@ -31,6 +55,7 @@ npm install -g token-furnace
 | `token-furnace --list-sources` | Each agent, its path, and its transcript count. |
 | `token-furnace serve [--port 8765]` | Live dashboard on `http://127.0.0.1:<port>`. It serves the last scan and refreshes it in the background. |
 | `token-furnace setup [--apply] [--verify] [--rollback] [--aggressive]` | Installer. Dry run unless `--apply`. |
+| `token-furnace fix-config` | Repairs context and worker settings; backs up changed files first. Optional `--include-depth`. |
 | `token-furnace hook churn` | Claude Code PostToolUse churn hook. Reads the payload on stdin. Never blocks. |
 
 Options:
@@ -41,6 +66,39 @@ Options:
 - `--no-plan-usage` — never call `api.anthropic.com`. A saved reading is still used.
 - `-h`, `--help` — usage text.
 
+## Context targets
+
+The analysis targets context sizes of **Claude Code 400k** and
+**Codex 300k**. Checkup, session flags, dashboard KPIs, hourly spend charts, benchmark estimates,
+and configuration repair all use these values. A turn exactly at its provider target is within
+target. Mixed-provider charts compare each turn against its own provider target.
+
+## Auto Fixes
+
+In the live dashboard, click **Auto Fixes** in the page header, review the changes, and select
+**Back up and apply**. Cancel closes the modal without changing files.
+
+The **Auto Fixes** button opens a checklist with every repair checked by default. Uncheck any
+setting to leave it unchanged; only selected repairs are applied. Backups are always made first.
+The CLI defaults still exclude depth limits unless `--include-depth` is supplied.
+Both providers get a concurrent worker cap of 3; Claude gets tool concurrency capped at 4
+and Sonnet workers if no worker model is pinned. Codex worker reasoning is set to medium
+unless already medium or lower. Existing lower caps and pinned models are preserved.
+Use `token-furnace fix-config --include-depth` or keep the modal depth checkboxes selected to also cap
+nesting at 1. This is optional because some agent versions may reject it or block spawning.
+Session age, caller reads, wakeups and unbounded loops require workflow changes; configuration
+repairs cannot rewrite those historical measurements.
+
+Run `token-furnace fix-config` to set Claude Code's `autoCompactWindow` to `400000` and
+Codex's `model_auto_compact_token_limit` to `300000`. Checks warn when these settings differ.
+The command respects `CLAUDE_CONFIG_DIR` and `CODEX_HOME`, preserves unrelated settings,
+and saves each existing changed file beside the original as `.token-furnace-backup`
+(with a numbered suffix when needed). No backup is needed for a newly created file.
+Invalid or unsupported configuration exits 1 before editing either file. Repeated runs make
+no changes once targets match. Restore by copying the printed backup path over its original.
+Restart agents after repair. A shell `CLAUDE_CODE_AUTO_COMPACT_WINDOW` override must be unset
+in the shell; the command reports it when present.
+
 ## Setup and hook
 
 `token-furnace setup` prints the planned changes and changes no file. Add `--apply` to write them.
@@ -92,18 +150,29 @@ main thread, or a positive number to set the worker count.
 An unknown option does not exit 2. `node:util` `parseArgs` throws, so that run exits 1 with a stack
 trace.
 
-## Release status
+## Development and contributing
+
+Bug reports and focused pull requests are welcome. For a bug, include your Node.js version,
+the command you ran, and a redacted error or minimal transcript example. Keep credentials and
+private transcript content out of issues.
+
+```sh
+git clone https://github.com/jonit-dev/token-furnace.git
+cd token-furnace
+npm ci
+npm run typecheck
+npm test
+npm run smoke
+```
+
+`npm test` builds the CLI and dashboard before running the suite. `npm run smoke` packs and installs
+the package into a temporary project, then checks the installed CLI, HTML export and live server
+against synthetic transcripts. `npm pack` and `npm publish` rebuild the distributable automatically.
+The dashboard is self-contained: no CDN scripts, fonts or styles are needed.
 
-Version 0.1.0. The `setup` and `hook` commands are integrated and tested (PRD-006). The dashboard
-is a React + Vite + TypeScript single-file build (PRD-005). `--html` writes one file and `serve`
-serves the same page. Both load no external URL: no CDN `<script>` or `<link>`.
+[Report a bug](https://github.com/jonit-dev/token-furnace/issues) ·
+[Browse the source](https://github.com/jonit-dev/token-furnace)
 
-The package smoke test passes on both Node.js 22.13 and Node.js 24.16: `npm pack`, a temporary
-install, and `npx --no-install` runs of the CLI (`--json`), `--html`, and `serve` all match the
-expected totals and routes. The tarball includes `dist/scan-worker.js` and `dist/dashboard.html`. The package file allowlist
-contains `dist/`, `SKILL.md`, `references/`, and `README.md`, plus npm metadata and the license.
-It contains no `.py`, `.sh`, test, or fixture files.
+## License
 
-The full Vitest suite (86 tests) plus the root and web typechecks and the build pass. The four CLI
-paths (cold workers, warm cache, inline main-thread, and `--no-cache` workers) return identical
-`Report` JSON. Publishing to npm is pending the package owner.
+[MIT](LICENSE) © Joao Paulo Furtado

package/SKILL.md

@@ -210,7 +210,8 @@ Applied by default — none of these reduce reasoning quality:
 | Claude | `CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS` | `3` | Default is 20. Caps simultaneous fan-out; does not cap total work. |
 | Claude | `ENABLE_TOOL_SEARCH` | `true` | Defers MCP tool schemas instead of loading every definition up front. Pure win with several MCP servers. |
 | Claude | `MAX_MCP_OUTPUT_TOKENS` | `12000` | Default 25K. Bounds a pathological MCP dump. |
-| Claude | `autoCompactWindow` | `200000` | Manual for now: `token-furnace setup` does not set it. On a 1M model the default compacts near 1M, so every turn carries up to 1M of context. |
+| Claude | `autoCompactWindow` | `400000` | Set with `token-furnace fix-config` (backup first). On a 1M model the default compacts near 1M, so every turn carries up to 1M of context. |
+| Codex | `model_auto_compact_token_limit` | `300000` | Set with `token-furnace fix-config` (backup first). |
 | Codex | `model_verbosity` | `low` | Shortens visible prose only. Reasoning is a separate setting and is untouched. |
 | Codex | `tool_output_token_limit` | `10000` | Bounds giant build and test logs. |
 | Codex | `agents.max_concurrent_threads_per_session` | `3` | Same reasoning as the Claude cap. |
@@ -255,7 +256,7 @@ npx token-furnace serve              # live report on http://127.0.0.1:8765
 Read the output in this order:
 
 1. **Spend by context size.** Cost per turn scales with the context carried into it, so a
-   few very long turns can dominate a week. A large share above 300k means sessions are
+   few very long turns can dominate a week. A large share above the provider target means sessions are
    never compacting: use a smaller context window, or start fresh sessions between
    unrelated tasks. Compression cannot fix this.
 2. **Always-resident preamble.** Instructions, memory, skill catalog and tool schemas are
@@ -266,14 +267,14 @@ Read the output in this order:
 4. **Tool calls.** If duplicate reads or repeated identical commands are rare, output
    compression has nothing to eat and is not your lever.
 5. **Leak checks.** Each top session gets one line per leak it shows, with the fix:
-   - *late compaction*: peak context above 300k. Set `autoCompactWindow` to about 200000.
+   - *late compaction*: peak context above the provider target (Claude 400k, Codex 300k). Values come from `src/core/context.ts`.
    - *caller reads*: 100+ file or log reads (`Read`, `sed -n`, `grep`, `rg`, `cat`, `python3 -`)
      run in the caller's own context. Send them to a cheap read-only agent.
    - *wakeups*: 50+ teammate, task-notification or cross-session messages. Each one is a
      full-context turn. Ask for one report at the end.
    - *loop*: 200+ turns per human prompt. Give the autonomous loop a stop condition and a budget.
    - *long-lived*: open 12+ hours. Start one fresh session per task.
-6. **Config checks.** `autoCompactWindow` unset or above 300k (the env var
+6. **Config checks.** `autoCompactWindow` unset or different from 400k; Codex `model_auto_compact_token_limit` unset or different from 300k (the env var
    `CLAUDE_CODE_AUTO_COMPACT_WINDOW` overrides the setting), and any `MEMORY.md` index over
    200 lines (Claude Code does not load the rest).