ASK Token Optimizer

ASK Token Optimizer is a freemium product from ASK AI — free for individuals and teams under USD $100k, commercially licensed above. Proceeds from enterprise licensing go toward raising technology literacy in local communities and paying independent developers through our bounty program. Every commercial seat helps fund someone else's first commit.

— ASK-Ai Team Canada

Stop paying for tokens Claude never needed to see.

Proprietary binary · licensed under Community / Commercial terms · free under USD $100k annual revenue

     

🤖 Living UX Install — your agent installs it, tailored to your machine

Don't follow a static checklist. Point your AI coding agent (Claude Code, Cursor, Cline, Continue) at README-LLM.md and it runs a living install: it audits your actual environment — OS, CPU architecture, shell, where your Claude config and PATH live — then executes a post-install flow shaped to your system, wires the hooks (asking before it changes anything), and verifies the result end-to-end. One adaptive flow that fits Linux, macOS, Windows, or a Raspberry Pi — without you reading a single step.

→ Hand your agent README-LLM.md. It takes it from there.

The problem

Every time Claude Code runs a command — git status, grep, ls, cargo build — the full output lands in the context window. A single grep across a large codebase can dump 250,000 tokens of noise that Claude processes, charges you for, and largely ignores.

That's not a Claude problem. That's a plumbing problem. And it's solvable before it reaches Claude.

What ASK Token Optimizer does

It sits between your terminal and Claude Code as two lightweight hooks. Before Claude sees a command's output, the optimizer filters it — stripping noise, collapsing repetition, keeping only what Claude actually needs to reason about. The output is structurally identical; the token count is not.

Without optimizer:
  git status  →  raw output  →  Claude sees 1,200 tokens

With optimizer:
  git status  →  filtered     →  Claude sees 110 tokens
                                              ↑
                                        92% fewer tokens.
                                        Same information.

No API key. No cloud. No account. The optimizer runs locally, processes output on your machine, and never touches the network.

Performance — live audit data

Measured on a real Claude Code session: 351 commands over 30 days. Source: ask gain.

Maximum savings — by command type

Figures are averages across all runs of that command type in a 30-day session. See honest audit below for steady-state numbers.

340,000 input tokens compressed to 41,800 delivered to Claude.

Why we show you the honest number too

The 87.7% session figure is real. But one command — a single grep run — produced 250,000 tokens of output and accounts for 93% of all savings in that figure. Remove that one outlier and measure the remaining 335 commands in steady-state:

What this tells you: ASK Token Optimizer is highly effective on high-volume output (grep, curl, build logs, large diffs) — those are the commands burning most of your budget anyway. On short-output commands (git status, quick reads) it compresses less. Your own workload will land somewhere between these two figures. Run ask gain after a day of use to see your real number.

We show both because you deserve to know what you're actually buying.

Licensing — free under $100k, commercial above

A single codebase. Two licenses. The engine is identical in both tiers — nothing is locked or degraded in the free version.

Installing or running the software constitutes acceptance of the LICENSE. Governing law: Canada. Commercial licensing: licensing@ask-ai.ca

Install — Linux / macOS / Windows / Pi4

Download or clone the SDK, then from its directory:

./setup.sh

Installs the binary, creates the ask shortcut, stages hook templates, and verifies. If no pre-built binary matches your platform and Rust is installed, it builds from source automatically.

Install — Windows (no WSL required)

.\install.ps1

Copies the binary to %USERPROFILE%\.local\bin, adds it to PATH, stages hooks. Full guide: INSTALL-WINDOWS.md.

Install — with an AI agent (Claude Code, Cursor, Cline)

Paste this into your agent. It follows README-LLM.md — the machine-readable install contract — and installs + wires up the optimizer for you:

Follow README-LLM.md in this repo to install and configure ASK Token Optimizer.

Activate the hooks (one time)

The optimizer only runs once the two hooks are wired into Claude Code. Edit ~/.claude/settings.json (Linux / macOS / Pi4) or %USERPROFILE%\.claude\settings.json (Windows):

Linux / macOS / Pi4:

{
  "hooks": {
    "PreToolUse":  [ { "matcher": "Bash", "hooks": [ { "type": "command", "command": "$HOME/.claude/hooks/ask-rewrite.sh" } ] } ],
    "PostToolUse": [ { "matcher": "Bash", "hooks": [ { "type": "command", "command": "$HOME/.claude/hooks/ask-filter.sh" } ] } ]
  }
}

Windows:

{
  "hooks": {
    "PreToolUse":  [ { "matcher": "Bash", "hooks": [ { "type": "command", "command": "python %USERPROFILE%\\.claude\\hooks\\ask-rewrite.py" } ] } ],
    "PostToolUse": [ { "matcher": "Bash", "hooks": [ { "type": "command", "command": "python %USERPROFILE%\\.claude\\hooks\\ask-filter.py" } ] } ]
  }
}

Restart Claude Code, then confirm it's working:

ask gain

SDK contents

.
├── builds/
│   ├── linux-x86_64/         ← pre-built binary, Linux x86_64
│   ├── linux-arm64/          ← pre-built binary, Linux arm64 / Pi4
│   ├── macos-x86_64/         ← pre-built binary, macOS Intel
│   ├── macos-arm64/          ← pre-built binary, macOS Apple Silicon (M1/M2/M3)
│   └── windows-x86_64/       ← pre-built binary, Windows x86_64 (.exe)
├── hooks/                    ← Claude Code hook templates (fork freely)
├── setup.sh                  ← Linux / macOS / Pi4 installer
├── install.ps1               ← Windows installer
├── INSTALL-WINDOWS.md        ← full Windows guide
├── ask-token-optimizer.service   ← optional: run as a system service
├── .env.example              ← optional configuration
├── LICENSE
└── README.md

CLI reference

ask --version          Version info
ask gain               Your cumulative savings since install
ask gain --graph       Daily savings trend
ask <command> <args>   Run any supported command through the optimizer
ask --hook             Compression endpoint used by the hooks
ask rewrite <cmd>      Preview how a command would be rewritten
ask serve --port N     Optional HTTP service mode (POST /v1/compress/output)

Supported commands: git · ls · tree · grep · find · cargo · npm · pnpm · aws · psql · gh · read · diff · json · deps · env — and more. Run ask --help for the full list.

Configuration (optional)

Copy .env.example → .env. Everything defaults to local-only operation.

No key ever points at Anthropic or any third-party service. Local by default. Inference is opt-in and runs wherever you point it.

Claude Code setup — copy-paste guide

Five steps, under two minutes. Open a terminal in the SDK directory.

Step 1 — Install

# Linux / macOS / Pi4
./setup.sh

# Windows (PowerShell)
.\install.ps1

The installer asks to wire the hooks for you. If you say yes, skip to Step 4.

Step 2 — Verify the binary is on PATH

ask --version
# should print: ask-token-optimizer 0.4.3

If ask: command not found, add to your shell profile:

export PATH="$HOME/.local/bin:$PATH"

Step 3 — Wire the hooks

Open (or create) ~/.claude/settings.json and add the hooks block:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          { "type": "command", "command": "$HOME/.claude/hooks/ask-rewrite.sh" }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          { "type": "command", "command": "$HOME/.claude/hooks/ask-filter.sh" }
        ]
      }
    ]
  }
}

Windows — replace the two command values with:

"python %USERPROFILE%\\.claude\\hooks\\ask-rewrite.py"
"python %USERPROFILE%\\.claude\\hooks\\ask-filter.py"

Step 4 — Restart Claude Code

Close and reopen Claude Code (or reload the window). The hooks activate on restart.

Step 5 — Confirm it's working

Run a few commands inside a Claude Code session, then:

ask gain

You should see token savings logged. A fresh install with no commands yet will show 0 — that's normal.

Troubleshooting

FAQ

Is it safe to install? Yes. The optimizer only intercepts Bash tool output inside Claude Code. It does not touch your files, credentials, or environment. The hooks degrade safely — if the binary is missing or crashes, output passes through to Claude untouched.

Does it change what Claude does? No. Claude receives the same factual content, in fewer tokens. Filtered output is structurally accurate — noise and repetition are removed, not meaning.

Will it break my workflow? Unsupported commands pass through unchanged. If a command's output looks wrong after filtering, run ask rewrite <cmd> to preview the transformation, or add it to the exclusion list in .env.

What happens to my data? Nothing leaves your machine. Compression is entirely local. The history.db savings ledger lives at ~/.local/share/ask/history.db — readable with any SQLite viewer.

How it compares

ASK Token Optimizer vs RTK

Support

Community support for the free tier. Commercial customers: SLA-backed support, include ask --version in any issue report. licensing@ask-ai.ca