Stop context rot. Keep Claude Code fast, focused, and cheap on long projects.
ctok is a free, open-source toolkit that runs before you hit send: it sizes the prompt, picks the right model and effort, trims the dead weight, and tells you exactly what each message costs you - in dollars and in your 5-hour quota window. Count tokens for Claude Haiku 4.5, Sonnet 4.6, and Opus 4.7.
📖 Full usage guide → USAGE.md · 🌐 Live playground → ctok-cli.github.io/ctok/playground
Long Claude Code sessions rot: context piles up, the wrong model burns money, and you blow your quota mid-task. ctok wraps a simple discipline around every prompt.
| Phase | What you do | ctok command |
|---|---|---|
| Plan | Pick the right model + effort before you spend tokens | ctok model · ctok check |
| Execute | Strip filler and dedupe so every message stays lean | ctok refine |
| Verify | See what % of your 5-hour window this prompt costs | ctok scan · quota meter |
Same engine, everywhere you work: terminal, your editor, the browser, Claude Code via MCP.
No app store, no account, no signup. Clone the repo and you have the whole toolkit working locally in one command:
git clone https://github.com/ctok-cli/ctok.git
cd ctok
# macOS / Linux
./scripts/setup.sh
# Windows (PowerShell)
./scripts/setup.ps1
# any OS (after `corepack enable`)
pnpm setupsetup installs dependencies, builds every package, and links the ctok binary onto your PATH. Then:
ctok --version
ctok doctor
ctok check "Refactor the auth module to use JWT"Don't want a global symlink? Run ./scripts/setup.sh --no-link and use pnpm start -- <args> from the repo root.
The CLI and MCP server are on npm - free, no store involved:
# CLI
npm install -g @ctok/cli # pnpm add -g @ctok/cli · yarn global add @ctok/cli
# MCP server runs straight from npx (see MCP section below)
npx -y @ctok/mcpVerify: ctok --version
Some surfaces live on free registries. The store-gated ones (which need paid developer accounts) you build straight from your clone - no store required.
| Surface | How to run it | Store needed? |
|---|---|---|
| CLI | npm i -g @ctok/cli · or clone + ./scripts/setup.sh |
No |
| MCP server | npx -y @ctok/mcp in your client config · or point at local dist |
No |
| Web playground | ctok-cli.github.io/ctok/playground · or ctok serve · or pnpm web:dev |
No |
| Browser extension | Clone → pnpm -F @ctok/browser-ext build → load unpacked |
No (skip the Web Store) |
| Desktop app | Clone → pnpm -F @ctok/desktop tauri build → run the local build |
No (skip the App Stores) |
Full step-by-step for each is in USAGE.md.
# Estimate a prompt (tokens, cost, quota impact)
ctok check "Refactor the auth module to use JWT"
# Estimate from a file, or pipe from stdin
ctok check -f prompt.md
cat context.txt | ctok check -
# Refine: trim filler, dedupe, tighten - with a before/after diff
ctok refine --diff "please help me to write a function that does sorting"
# Recommend a model + effort level
ctok model "Implement a full OAuth2 flow with PKCE"
# See where the tokens in your repo actually live
ctok scan ./my-project
# Interactive REPL (no args)
ctok| Command | Description |
|---|---|
ctok check [prompt] |
Estimate tokens, cost, and quota impact |
ctok refine [prompt] |
Run the 7-pass prompt refiner (--diff for before/after) |
ctok scan [dir] |
Analyse a project directory |
ctok model [prompt] |
Recommend model + effort level |
ctok serve |
Launch the web playground locally on port 31337 |
ctok history |
Show recent prompt history |
ctok diff |
Compare two history entries |
ctok config |
Get/set configuration values |
ctok init |
Write .ctokignore for the current project |
ctok doctor |
Check environment and config |
Run ctok <command> --help for full options. Use --json for machine-readable output.
Add this to your MCP client config (Claude Code, Cursor, Zed, Claude Desktop) - it runs from npm, nothing to install:
{
"mcpServers": {
"ctok": {
"command": "npx",
"args": ["-y", "@ctok/mcp"]
}
}
}Prefer your clone? Point command at node and args at packages/mcp/dist/index.js after pnpm build. Tools exposed: estimate, refine, recommend_model, scan_project.
ctok config set plan pro # Free | Pro | Max5x | Max20x | Team | Enterprise | API
ctok config set telemetry true # opt-in to anonymous usage stats (disabled by default)
ctok config get # show all settingsConfig file: ~/.ctok/config.json. Plan is also auto-detected from ~/.claude/settings.json.
packages/
core/ @ctok/core - estimation engine, recommender, reducer
scanner/ @ctok/scanner - project directory scanner
refiner/ @ctok/refiner - 7-pass prompt refiner
quota/ @ctok/quota - plan limits and quota impact calculator
cli/ @ctok/cli - Commander.js CLI
mcp/ @ctok/mcp - MCP server (JSON-RPC 2.0 over stdio)
web/ @ctok/web - Next.js playground (ctok-cli.github.io/ctok)
desktop/ @ctok/desktop - Tauri 2 desktop wrapper (build locally)
browser-ext/ @ctok/browser-ext - Chrome MV3 extension (load unpacked)
docs/ - Astro Starlight documentation site
scripts/ - clone-and-run setup (setup.sh / .ps1 / .mjs)
See CONTRIBUTING.md. All packages use TypeScript strict mode, Vitest for tests, and tsup for builds.
git clone https://github.com/ctok-cli/ctok.git
cd ctok
pnpm install
pnpm build
pnpm testctok collects no telemetry by default. When opted in (ctok config set telemetry true), only anonymous event names, app version, and platform are sent - never prompt text, file names, or any personally identifiable information. See SECURITY.md.
MIT - see LICENSE.