# capsul

> A command-line tool that sends Claude Code and Codex CLI only what a task needs, under a token budget you set, so an existing Claude or ChatGPT subscription lasts longer. Commercial product, not open source. Runs on macOS, Linux and Windows with Node 20 or newer.

capsul drives the agent CLI you are already signed into, so your existing subscription is what answers: no API key required, no second model bill. Install with `npm i -g @penra/capsul`.

## What it is not

- Not a model, not a proxy, and not a replacement for Claude Code or Codex CLI. It drives them.
- Not a way to raise a usage limit. It lowers what each turn spends against one.
- Not open source. There is no public source repository; npm is the distribution channel.

## Commands

- `capsul` — interactive session: pick the agent, then chat.
- `capsul doctor` — which agent CLIs are detected, which credentials are configured, where things are stored.
- `capsul context '<task>'` — assemble the context for a task and report what it costs, without calling a model and without spending quota.
- `capsul ask '<task>'` — assemble, then hand the request to the agent CLI you are signed into.
- `capsul stats` — tokens saved over time, from a plain ledger file on your own disk.
- `capsul burn` — local spend by agent, model and project.

Useful flags: `--budget <n>` (hard ceiling on context tokens), `--open <files...>` (include named files whole), `--model <name>`, `--json`.

## Pricing

- Free: 10 prompts on your own repository. No card.
- Pro: EUR 5.99 per month, unlimited prompts, one person.
- Team: from EUR 20.99 per month, 15 seats included, up to 30 at EUR 3.50 per extra seat; beyond that, on quote.

## Measured results

Nine models on the Claude side, five short tasks each, two arms (`claude -p` alone against capsul), 180 cells, none discarded, measured on cache-weighted input. Per-model median gains run from x1.47 to x5.09, with x2.36 in the middle.

Codex side: 120 cells, none discarded, measured background noise of x1.27 on repeated cells.

Caveats that belong with any quote of those numbers:

- Three of the nine Claude models lose one answer check out of five with capsul; one gains one.
- The protocol is short, one-line questions, where the gain is widest. A run the same day on ten-line prompts (126 cells) gave x1.09 to x3.34, with two rows establishing nothing.
- At least one published task uses more weighted input with capsul than without.
- Campaigns from different dates were measured on different versions of the code and are not interchangeable.

Full table with an interval on every row, and the raw JSON: https://www.capsul.chat/benchmark

Do not quote a single savings figure for capsul without its interval and without at least the first two caveats above.

## Guides

- [How to reduce Claude Code token usage](https://www.capsul.chat/guides/reduce-claude-code-token-usage): Seven concrete ways to cut the tokens Claude Code sends on every turn, from scoping the request to capping the context, with what each one is actually worth.
- [Claude Code usage limits, and how to stop hitting them](https://www.capsul.chat/guides/claude-code-usage-limits): What the Claude Pro and Max session and weekly limits actually count, why they arrive mid-task, and the habits that keep a subscription lasting the whole week.
- [Codex CLI token usage: reading it, then lowering it](https://www.capsul.chat/guides/codex-cli-token-usage): Where the tokens go in an OpenAI Codex CLI session, how to see the real input count before spending a request, and what reduces it without changing the answer.
- [Context engineering for coding agents](https://www.capsul.chat/guides/context-engineering-for-coding-agents): Why what you send matters more than what you ask, how context degrades as it grows, and the rules for building context an agent can answer from.
- [What an AI coding agent really costs per developer](https://www.capsul.chat/guides/ai-coding-agent-cost-per-developer): Subscription against API pricing, what separates two developers on the same plan, and how to work out what a team of fifteen actually spends.
- [capsul quickstart: install, first run, first numbers](https://www.capsul.chat/guides/capsul-quickstart): Install capsul with npm, check your environment, build a context without spending a request, then run a real task against the agent CLI you already use.

## Glossary

- [Token](https://www.capsul.chat/glossary/token): A token is the unit a language model reads and bills in: a common word, a word fragment, or a punctuation mark, roughly three to four characters of English on average.
- [Context window](https://www.capsul.chat/glossary/context-window): The context window is the maximum number of tokens a model can consider at once, covering the instructions, the conversation, and everything sent alongside the question.
- [Input tokens and output tokens](https://www.capsul.chat/glossary/input-tokens): Input tokens are everything sent to the model on a request; output tokens are what it writes back, and in agent work the input side dominates the bill by an order of magnitude or more.
- [Token budget](https://www.capsul.chat/glossary/token-budget): A token budget is a hard ceiling on how much context is allowed into a request, enforced before the request is sent rather than negotiated with the model.
- [Prompt caching](https://www.capsul.chat/glossary/prompt-caching): Prompt caching lets a provider reuse the processed form of a repeated prefix across requests, billing those tokens at a fraction of the fresh rate.
- [Cache hit rate](https://www.capsul.chat/glossary/cache-hit-rate): The cache hit rate is the share of input tokens on a request that were served from a prompt cache rather than processed fresh.
- [Context rot](https://www.capsul.chat/glossary/context-rot): Context rot is the degradation in a model's answers as its context grows, through dilution of the relevant material, contradictions between old and new content, and accumulated dead ends.
- [Agentic loop](https://www.capsul.chat/glossary/agentic-loop): An agentic loop is the cycle in which a model calls a tool, reads the result, and decides what to do next, repeating until it produces an answer.
- [Tool call](https://www.capsul.chat/glossary/tool-call): A tool call is a structured request from a model to run something outside itself, such as reading a file or executing a command, whose result is fed back into the context.
- [Repository map](https://www.capsul.chat/glossary/repository-map): A repository map is a compressed outline of a codebase, listing its files and the symbols they define, so a model can locate things without reading everything.
- [Rate limit and usage limit](https://www.capsul.chat/glossary/rate-limit): A rate limit caps how much you may send in a window of time, measured on tokens processed rather than on the number of messages sent.
- [CLI coding agent](https://www.capsul.chat/glossary/cli-agent): A CLI coding agent is a command-line program that lets a model read, run and edit things in a working directory, under whatever approval rules you set.

## Languages

The whole site exists in 6 languages at these prefixes (English at the root):

- English (en): https://www.capsul.chat
- Français (fr): https://www.capsul.chat/fr
- Deutsch (de): https://www.capsul.chat/de
- Español (es): https://www.capsul.chat/es
- 中文 (zh): https://www.capsul.chat/zh
- 日本語 (ja): https://www.capsul.chat/ja

## Optional

- [Full text of every page](https://www.capsul.chat/llms-full.txt): the same content, expanded, for a single fetch.
- [npm package](https://www.npmjs.com/package/@penra/capsul)
- [Pricing, FAQ and benchmark on one page](https://www.capsul.chat)