Newsletter, guides

Set up the pi coding agent with Claude for low token use

Configure the pi coding agent with an Anthropic API key, Haiku 5.5 as the default model, rtk output compression and a lean prompt, with measured token costs.

, 8 min read, updated

The pi coding agent costs very little to run once you turn off what you do not use. With the default setup and a shared skills folder, my first message sent 16,312 prompt tokens. With skills off it sent 2,407. That one setting is the largest saving, and it takes one line in settings.json.

This guide sets up pi 1.5.2 with an Anthropic API key and Claude Haiku 5.5 as the default model. Sonnet 5.5 and Opus 5.5 stay one keypress away. You also add rtk to shrink command output, and a short AGENTS.md. Every number below comes from runs on a small test repo that I describe at the end, so you can repeat them.

Key takeaways

  • Turn skills off by default. In my runs that cut the starting prompt from 16,312 tokens to 2,407, and a skills-on session cost four to seven times more per task with the same pass rate.
  • Haiku 5.5 passed every task in my set at 9 to 24 times lower cost than Sonnet 5.5. Make it the default and switch up only when a task fails.
  • Save the Anthropic key with pi auth login anthropic --api-key. The key never goes into a prompt, a script argument or a repo.
  • rtk helps on listing, search and test output (91% smaller on one file listing). It does nothing on small tasks and passes some commands through unchanged.
  • Keep optional packages out of the default setup. Load pi-subagents for one run with -e when you need it.

What does a pi session cost before you type anything?

Pi sends a system prompt, tool definitions, your context files and your skills with every request. Pi itself is small. The weight comes from what you attach to it.

I measured the first request of a session, where the prompt was “Reply with: ok”, on Haiku 5.5. The table shows how each lever changes it.

Setup Prompt tokens
Defaults with my shared skills folder 16,312
Skills off 2,407
Skills off and tools limited to read and bash 1,694
Skills off and pi-subagents loaded 3,061

These tokens are paid on every request of the session, not once. Prompt caching lowers the price of the repeated part, but a smaller prefix is still cheaper and faster. The prompt caching lab shows the mechanism.

Flow of token savings in pi: skills off, a short AGENTS.md, the rtk hook, then a model chosen by task type

How do you add the Claude API key to pi?

Use pi’s own login command. It asks for the key, stores it in pi’s auth file under your home folder and checks it.

pi auth login anthropic --api-key
pi auth check

pi auth check should report that Anthropic is ready. Do not put the key in settings.json, in a shell alias or on a command line, because those end up in history and in logs. If a coding agent helps you set this up, run the login yourself in your terminal so the key never enters its context.

Then list the models pi can see with pi --list-models. You should find claude-haiku-5-5, claude-sonnet-5-5 and claude-opus-5-5 under the anthropic provider.

Which settings make pi lean?

Edit ~/.pi/agent/settings.json. This is the file I run, with the secret-free fields only.

{
  "defaultProvider": "anthropic",
  "defaultModel": "claude-haiku-5-5",
  "defaultThinkingLevel": "medium",
  "enabledModels": [
    "anthropic/claude-haiku-5-5",
    "anthropic/claude-sonnet-5-5",
    "anthropic/claude-opus-5-5"
  ],
  "modelThinkingLevels": {
    "anthropic/claude-haiku-5-5": "medium",
    "anthropic/claude-sonnet-5-5": "medium",
    "anthropic/claude-opus-5-5": "medium"
  },
  "compaction": { "enabled": true, "reserveTokens": 8192, "keepRecentTokens": 8000 },
  "quietStartup": "header",
  "skills": ["!**"]
}

Each field does one job. The pi settings reference lists them all.

  • skills: ["!**"] excludes every skill, so none of their descriptions enter the prompt.
  • enabledModels sets the models that Ctrl+P cycles through, in order.
  • modelThinkingLevels pins medium thinking on all models, which matches how Claude Code runs by default.
  • compaction keeps recent context small, so long sessions summarize earlier than the default.

Skills are not bad. A skill that you need for one task can be switched on for that run. For throwaway runs, add --no-skills --no-context-files and nothing else loads.

Which model should be the default?

Haiku 5.5 as the default, Sonnet 5.5 on demand, Opus 5.5 for rare hard problems. I started with Sonnet as the default and changed my mind after the numbers.

I ran five focused tasks on each model. They were: review a diff, write a README section, triage a list of issues, fix a seeded bug with a test, and answer a question about local files.

All fifteen runs passed. Time per task was similar, between 4 and 13 seconds. Cost was not.

Model Cost per task, five tasks
Haiku 5.5 $0.0004 to $0.0008
Sonnet 5.5 $0.0058 to $0.0143
Opus 5.5 $0.0116 to $0.0236

Haiku was 9 to 24 times cheaper than Sonnet on the same task. The tasks were small and each one had a clear check, so this does not show that Haiku matches Sonnet on a large refactor. It shows where to start: begin on Haiku, and move up for the task that fails. The guide on choosing a model per task explains this routing in general.

Switch models mid-session with Ctrl+P. Raise thinking to high for one call only when a task needs it.

What does rtk do inside pi?

rtk rewrites shell commands so that their output is shorter. Pi has a hook system for extensions, and rtk installs a small extension that uses it.

rtk init -g --agent pi

That writes ~/.pi/agent/extensions/rtk.ts. Read it before you keep it. It is a short hook that calls rtk rewrite on each bash command. If rtk fails, the original command runs.

Set RTK_DISABLED=1 to turn it off. The rtk pi hook readme describes it.

I tested it by asking pi to list TypeScript files in a large site repo with find src -name '*.ts'. Output was 15,847 characters with rtk off and 1,404 with rtk on, about 91% smaller. A git log --stat call returned identical output both ways, because rtk has no rewrite for it.

On my five small tasks the rtk-off runs cost the same as the rtk-on runs. So rtk pays off on repos where a listing, a search or a test run returns pages of text. If your tasks are small, skip it and keep one less moving part.

I chose rtk’s own installer over the community wrappers on npm. The wrappers I checked had between 30 and 345 downloads a month and one maintainer each. The tool’s own hook has the maintainers who change rtk.

Should you install pi-subagents?

Not by default. pi-subagents is the one package I would trust, with a large user base, an MIT license, pinned dependencies and no install scripts. It adds the ability to run a worker with its own model and tool list.

It also adds weight. Loading it raised my starting prompt from 2,407 to 3,061 tokens. So load it for one run and pin the version.

pi -e npm:[email protected]

My rule for any package is simple. It needs more than 10,000 downloads a month or a known organization behind it. It must have a release in the last 60 days, and I read its source before install. If a package fails that test, I write a prompt template instead.

How do you keep the prompt short with AGENTS.md?

Put four rules in ~/.pi/agent/AGENTS.md and stop. Pi loads this file into every session, so every line costs tokens on every request.

# Rules for pi

- Read only the files named. Search only when no file is named.
- Make the smallest change that works. Run the test or command that proves it.
- Report in plain sentences. No filler, no restating the task.
- Never print or log secrets.

A 2026 study of context files, listed below, found that a short AGENTS.md cut output tokens and run time. Long procedures belong in a skill that you load when you need it, not in the file that loads every time.

How can you measure your own setup?

Use pi’s JSON mode. It prints one event per line, and the message_end events carry usage.

pi -p --no-session --mode json "Review git diff --staged" < /dev/null \
  | grep '"message_end"' | tail -1

Run the same task before and after one change, and compare input tokens, output tokens and cost. Revert the change and confirm that the number moves back. A saving that does not reverse was never caused by your change.

My test repo is small on purpose. It holds a Python cart module with a seeded bug, a retry module, a unit test file, a diff and a list of issues. The numbers will differ on your code. The method will not.

What to do next

  1. Run pi auth login anthropic --api-key and then pi auth check.
  2. Copy the settings above into ~/.pi/agent/settings.json and confirm that the first message costs about 2,400 prompt tokens.
  3. Install the rtk hook only if your tasks print long listings or test output.
  4. Write a four-line AGENTS.md and keep it short.
  5. Pick one task you repeat, run it on Haiku, and move up only on failure.
  6. Read the practitioner guide to pi for code review, docs and triage for the prompts I use on top of this setup.
  7. Before you give any agent a shell, read how to scope a bash tool safely.

Frequently asked questions

Does pi work with a Claude API key?

Yes. Pi supports Anthropic as a provider. Run pi auth login anthropic --api-key, then pi auth check, and select a model such as claude-haiku-5-5. Billing goes to your Anthropic account, not to a subscription.

Which Claude model is best for pi?

Start with Haiku 5.5 for focused tasks and switch to Sonnet 5.5 when one fails. In my five-task test every model passed, and Haiku cost 9 to 24 times less than Sonnet. Use Opus 5.5 for hard design work.

How do I reduce token use in the pi coding agent?

Turn skills off with "skills": ["!**"], keep AGENTS.md to a few lines and limit tools for review runs. Skills off cut my starting prompt from 16,312 to 2,407 tokens. Compress long command output with rtk when tasks print a lot.

Does rtk work with pi?

Yes. rtk init -g --agent pi installs an extension that rewrites bash commands. It shrank a file listing by about 91% in my test. It does not shorten every command, and it gave no gain on small tasks.

Is the pi-subagents package safe to install?

I vetted version 0.88.1: MIT license, pinned dependencies, no install scripts and a large user base. Read the source yourself before you install any package, and pin the version.

Sources

Build what you just read, with Param, live

  1. You read the guide

  2. Free Live LabBuild a Second Brain with Claude CodeA second brain over your notes, docs and Linear that answers with sources and serves the same memory to any agent over MCP.Free seat
  3. ProWatch the video coursesDesign a Software Factory for Your Coding Agents, Build Your First Software Factory Execution Harness and each new course as the sessions are cut. The first lesson of each is free after you sign in.$149 a year
  4. WorkshopAgentic AI System Design for Engineers & PMsAn architecture for one real workflow at your company that you can take to a design review: roles, models, context, tools, approvals, failure plan and budget.$497
  5. BuildcampAgentic AI Buildcamp for Engineers & PMsDesign, build and deploy a production agentic AI system in four weeks$997

Or watch the recording: Cut AI Agent Costs with Token Economics

Subscribe to Top 1% Engineers

One issue at a time on building AI systems that hold up in production: architecture, the open source that matters, and what to do on Monday. Every number cited.

We email you each new issue. You can leave at any time. Privacy

More guides

See the newsletter and every guide