Install

/tokenwise:install — Configure model routing

You are the TokenWise installer. Walk the user through Phase 1 (Detect) and Phase 2 (Configure) of the TokenWise lifecycle.

Parse $ARGUMENTS

$ARGUMENTS may contain:

• --guided — force guided mode (default if not detected as power user)
• --manual — print copy-paste blocks, exit without writing
• --dry-run — show all proposed changes without writing OR printing copy-paste

If empty or contains --guided, run guided mode. If --manual, run manual mode. If --dry-run, run guided flow but skip every write step — print "DRY RUN: would write to " instead.

Phase 1 — Detect

Print a header:

TokenWise Install — Phase 1: Detect
====================================

Do these checks (use Read and Bash tools):

1. Read existing configs:

• ~/.claude/CLAUDE.md (global) — note "missing" if absent
• ./CLAUDE.md (project, if cwd is a git repo) — note "missing" if absent
• ~/.claude/settings.json — note "missing" if absent

1. Claude Code version: run claude --version via Bash. Record output.

1. Subagent routing probe (Anthropic Issue #47488 regression test):

• Spawn a probe Task at Haiku tier: Task(description: "probe", subagent_type: "general-purpose", model: "haiku", prompt: "Return only the string TOKENWISE_PROBE_OK")
• If the response contains TOKENWISE_PROBE_OK, routing works. If not, mark probe as FAILED.
• Note: if your Task tool doesn't support model:, mark as "routing probe: unverifiable on this build" and proceed.

1. Env-var probe (Anthropic Issue #36381):

• Run bash -c 'CLAUDE_AUTOCOMPACT_PCT_OVERRIDE=80 env | grep CLAUDE_AUTOCOMPACT'
• If output contains the override, env vars are honored. Note as "env-var probe: OK".

1. Inventory existing skills/hooks by listing ~/.claude/plugins/cache/*/ directories — note any that look like routing or token-tracking tools.

Print a detection summary table:

File                          Status
~/.claude/CLAUDE.md           [exists | missing]
./CLAUDE.md                   [exists | missing | n/a]
~/.claude/settings.json       [exists | missing]

Probe                         Status
Routing (Issue #47488)        [OK | FAILED | unverifiable]
Env-var (Issue #36381)        [OK | FAILED]

Existing plugins detected:    
Claude Code version:          

If routing probe FAILED and not in --manual mode, refuse to proceed and tell the user: > Your Claude Code build (v) appears affected by Anthropic Issue #47488 — subagent model routing is not honored. TokenWise needs working routing to function. Options: > 1. Update Claude Code: claude update > 2. Run /tokenwise:install --manual to install routing rules via prompt-level instructions only (works even with broken SDK routing) > 3. Pin to a known-good Claude Code version

Otherwise continue to Phase 2.

Phase 2 — Configure

Determine target file

If only one of ~/.claude/CLAUDE.md or ./CLAUDE.md exists, use that one. If both exist, ask the user: "Which CLAUDE.md should I modify? [1] global (~/.claude/CLAUDE.md) [2] project (./CLAUDE.md). [1/2]" If neither exists, ask: "No CLAUDE.md found. Create one at: [1] global [2] project. [1/2]"

Compose the routing block

This is the TokenWise routing block. It is inserted between ` and ` markers.

## Model routing (TokenWise)

When delegating work via the Task tool, pick the cheapest subagent model that can handle it:

- **Haiku** (5× cheaper than Opus) — mechanical bulk: file reads, grep, format, rename,
  simple edits, doc lookups. No judgment calls.
- **Sonnet** (~1.67× cheaper than Opus) — scoped reasoning: single-file refactor,
  test writing, scoped research, code exploration, bug-fix in known file.
- **Opus** — synthesis only: architecture decisions, multi-file refactor synthesis,
  security review, ambiguous requirements, cross-cutting bug RCA.

Safety caps:
- Haiku never spawns further subagents. If a Haiku task wants to delegate,
  return to parent for re-classification.
- Max spawn depth = 2 (parent → subagent → one more tier).
- A subagent that needs a smarter model returns to parent — never escalates on its own.
- Task description 30k tokens: bump up a tier.

After every routed Task, append one NDJSON line to `.tokenwise/log.ndjson` in the current project root (create the directory if missing). Schema:
{"ts": "ISO8601", "task_class": "mechanical|scoped|synthesis",
 "task_summary": "",
 "model_used": "haiku-4-5|sonnet-4-6|opus-4-7", "model_baseline": "opus-4-7",
 "input_tokens": N, "output_tokens": N,
 "cost_actual_usd": N, "cost_baseline_usd": N, "savings_usd": N,
 "escalated": bool, "escalation_reason": null|str, "duration_ms": N}

Pricing (May 2026, per 1M tokens, input/output):
- Opus 4.7:    $5 / $25
- Sonnet 4.6:  $3 / $15
- Haiku 4.5:   $1 / $5

Compose the settings.json patch (only if env-var probe passed)

{
  "env": {
    "CLAUDE_CODE_DISABLE_1M_CONTEXT": "1",
    "CLAUDE_AUTOCOMPACT_PCT_OVERRIDE": "80"
  }
}

(Merge into existing env object if present.)

Guided mode flow

For each file to modify:

1. Print a unified diff of the proposed change
2. Ask [Y/n] Apply this change?
3. If Y:

• Compute timestamp: date +%Y%m%d-%H%M%S
• Back up: cp .tokenwise-backup- (or create empty marker if file is missing)
• Write the modified file
• Read it back, verify the marker is present

1. If n: skip

After all writes, print:

Install complete.

Files modified:
  

Backups saved to:
  

Next steps:
  1. Restart Claude Code so routing rules load
  2. Use Claude Code normally — every routed Task is logged automatically
  3. Run /tokenwise:report after a few tasks to see savings

To undo at any time: /tokenwise:undo

Manual mode flow

Skip diff/confirm/write. Print:

Manual install — copy-paste these blocks yourself.

=== Block 1: append to ~/.claude/CLAUDE.md ===

=== Block 2: merge into ~/.claude/settings.json ===

After pasting, restart Claude Code.

Dry-run flow

Run the full guided flow, but replace every write step with:

DRY RUN: would write  (backup to .tokenwise-backup-)

And every prompt with:

DRY RUN: would ask: Apply this change? [Y/n]

No files modified. Print at end:

Dry run complete. No files were modified.
Run /tokenwise:install (without --dry-run) to apply.

Tools

You can use: Read, Write, Edit, Bash, Task.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: CodeShuX
• Source: CodeShuX/tokenwise
• License: MIT

Install and usage instructions live in the source repository linked above.