# Install

> Install TokenWise routing rules into the user's Claude Code config (CLAUDE.md and settings.json). Probes the user's Claude Code build for known routing bugs first, shows diffs, backs up originals, asks for per-file confirmation. Supports --guided (default), --manual (print copy-paste only), and --dry-run (preview without writing). Use when the user says "install tokenwise", "set up tokenwise", or…

- **Type:** Skill
- **Install:** `agentstack add skill-codeshux-tokenwise-install`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [CodeShuX](https://agentstack.voostack.com/s/codeshux)
- **Installs:** 0
- **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [CodeShuX](https://github.com/CodeShuX)
- **Source:** https://github.com/CodeShuX/tokenwise/tree/main/skills/install

## Install

```sh
agentstack add skill-codeshux-tokenwise-install
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# /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

2. **Claude Code version:** run `claude --version` via Bash. Record output.

3. **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.

4. **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".

5. **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.

```markdown

## 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)

```json
{
  "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
4. 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](https://github.com/CodeShuX)
- **Source:** [CodeShuX/tokenwise](https://github.com/CodeShuX/tokenwise)
- **License:** MIT

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

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-codeshux-tokenwise-install
- Seller: https://agentstack.voostack.com/s/codeshux
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.