capsul quickstart: install, first run, first numbers

1. Install

$npm i -g @penra/capsul

2. Check the environment

doctor reports which agent CLIs it can see, which credentials are configured, and where things are stored. It shows you where they live without ever showing what they are.

$capsul doctor

If your agent CLI is not detected here, nothing else will work. Fix this step before going further.

3. Build a context without spending anything

This is the command to run first, on a task you actually have. It assembles the context and reports what it costs, without calling a model and without touching your quota.

$capsul context 'why does the login redirect loop'

Add --json for a machine-readable version, and --open when you already know which file matters:

$capsul context 'fix the redirect loop' --open src/middleware.ts --json

4. Run the task

ask does the same assembly and then hands the request to the agent CLI you are signed into. Your existing Claude or ChatGPT plan is what answers: no API key to paste, no second model bill.

$capsul ask 'fix the redirect loop' --budget 3000

Running capsul with no subcommand opens an interactive session instead, where you pick the agent and chat.

$capsul

Afterwards

• →capsul stats cumulates tokens saved over time. The ledger is a plain file on your own disk.
• →capsul burn breaks local spend down by agent, model and project.
• →--model haiku for mechanical work: renames, formatting, single-file edits.
• →--budget <n> sets a hard ceiling on context. Nothing spills over it silently.