Pi Integration

Pi is a terminal coding agent with tools for reading files, editing code, and running commands. Add Halfbill as a custom provider to choose from the model catalogue and track usage in one dashboard.

Install Pi

Install the current package:

pnpm add -g @earendil-works/pi-coding-agent
pi --version

The older @mariozechner/pi-coding-agent package is deprecated. See the Pi website for installation options.

Configure the provider

Create an API key in your Halfbill dashboard, then set it in the shell where you will run Pi:

export HALFBILL_API_KEY="your_api_key"

Add this provider to ~/.pi/agent/models.json. Merge it with any existing providers:

{
	"providers": {
		"halfbill": {
			"baseUrl": "https://api.halfbill.uk/v1",
			"api": "openai-completions",
			"apiKey": "$HALFBILL_API_KEY",
			"headers": { "x-source": "pi" },
			"models": [
				{
					"id": "claude-sonnet-5",
					"reasoning": true,
					"contextWindow": 200000,
					"maxTokens": 4096
				}
			]
		}
	}
}

The model is a working example. Choose any model from the models page, and use its exact ID. Match reasoning and contextWindow to the selected model. This example caps the response at 4,096 tokens with maxTokens.

Keep the $ in "$HALFBILL_API_KEY". Current Pi interpolates environment variables only with $NAME or ${NAME}. A plain "HALFBILL_API_KEY" is sent as the literal key and causes an authentication error.

Using Halfbill Code? A Halfbill Code plan key works the same way; use the canonical model ID.

Select the model

Start Pi from your project directory and open the model picker:

pi

Type /model, then choose the Halfbill model. Pi reloads models.json when you open the picker, so configuration changes do not require a restart.

You can also select the provider and model when launching:

pi --provider halfbill --model claude-sonnet-5

Verify the connection

Give Pi a small task with a clear check:

Fix slugify.ts so all tests pass. Read the files, make the smallest fix,
run node --test slugify.test.ts, and summarize. Do not edit the tests.

Inspect the resulting diff and test output. Requests appear in your Halfbill dashboard, with the model, token usage, and cost.

For a one-shot command:

pi --provider halfbill --model claude-sonnet-5 -p "Explain this project"

Troubleshooting

• Authentication error: Check that the shell variable is set, the key is active, and apiKey includes the $ prefix.
• Model missing: Copy its exact ID from the catalogue, then reopen /model.
• Wrong endpoint: Use https://api.halfbill.uk/v1 with api: "openai-completions".
• Unsupported reasoning setting: Match the model's reasoning support and supported effort levels.

See Pi's custom provider documentation for advanced configuration.