Ctok

ctok - the focus layer for Claude Code

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.

[](https://npmjs.com/package/@ctok/cli) [](LICENSE) [](https://github.com/ctok-cli/ctok/actions) [](https://modelcontextprotocol.io) [](#run-it-from-a-clone-recommended)

> 📖 [Full usage guide → USAGE.md](USAGE.md) · 🌐 Live playground → ctok-cli.github.io/ctok/playground

---

Why ctok - Plan → Execute → Verify

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.

---

Run it from a clone (recommended)

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 setup

setup 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 -- from the repo root.

---

Or install from npm (CLI + MCP, already published)

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

Verify: ctok --version

---

Every surface, and how to get it

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](USAGE.md).

---

Quick start

# 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

---

CLI commands

| 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 --help for full options. Use --json for machine-readable output.

---

MCP: use ctok inside Claude Code

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.

---

Configuration

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 settings

Config file: ~/.ctok/config.json. Plan is also auto-detected from ~/.claude/settings.json.

---

Monorepo

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)

---

Contributing

See [CONTRIBUTING.md](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 test

---

Privacy

ctok 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](SECURITY.md).

---

License

MIT - see [LICENSE](LICENSE).

Source & license

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

• Author: ctok-cli
• Source: ctok-cli/ctok
• License: MIT
• Homepage: https://ctok-cli.github.io/ctok/

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