# Ctok

> Lighthouse for Claude prompts - estimate tokens, recommend models, refine prompts before you send.

- **Type:** MCP server
- **Install:** `agentstack add mcp-ctok-cli-ctok`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [ctok-cli](https://agentstack.voostack.com/s/ctok-cli)
- **Installs:** 0
- **Category:** [Developer Tools](https://agentstack.voostack.com/c/developer-tools)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [ctok-cli](https://github.com/ctok-cli)
- **Source:** https://github.com/ctok-cli/ctok
- **Website:** https://ctok-cli.github.io/ctok/

## Install

```sh
agentstack add mcp-ctok-cli-ctok
```

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

## About

# 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](https://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:

```sh
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:

```sh
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:

```sh
# 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](https://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

```sh
# 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:

```json
{
  "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

```sh
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.

```sh
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](https://github.com/ctok-cli)
- **Source:** [ctok-cli/ctok](https://github.com/ctok-cli/ctok)
- **License:** MIT
- **Homepage:** https://ctok-cli.github.io/ctok/

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/mcp-ctok-cli-ctok
- Seller: https://agentstack.voostack.com/s/ctok-cli
- 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%.