---
slug: "agentoom-pi-spending-guard"
source_type: "readme"
source_url: "https://cdn.jsdelivr.net/gh/agentoom/pi-extension-spending@main/README.md"
repo: "https://github.com/agentoom/pi-extension-spending"
source_file: "README.md"
branch: "main"
---
# @agentoom/pi-spending-guard

Track LLM spending per task and pause when a configurable threshold is reached for [pi](https://pi.dev) by [agentoom.com](https://agentoom.com).

When your spending limit is hit, spending-guard pauses the task and asks you to choose: continue (double the limit or reset the counter), refine the prompt, or stop entirely — so you never lose control of your API costs.

## Install

```bash
pi install npm:@agentoom/pi-spending-guard
```

## Quick start

Out of the box, spending-guard is **enabled** with a **$3.00 default limit**. Start pi and spend away — it'll pause automatically at $3.00.

## Usage

### Commands

| Command | Description |
|---------|-------------|
| `/spending` | Show current spending, limit, and enabled state |
| `/spending limit [amount]` | Set or view the spending limit (e.g. `/spending limit 5`) |
| `/spending toggle [on\|off]` | Enable/disable tracking; no argument toggles |
| `/spending-limit [amount]` | Shortcut: set or view the limit |
| `/spending-toggle [on\|off]` | Shortcut: enable/disable |
| `/spending-status` | Shortcut: show current status |

### Threshold dialog

When accumulated cost reaches the configured limit, spending-guard pauses and presents a 4-option dialog:

| Option | Behaviour |
|--------|-----------|
| **Continue (double the limit)** | Raises the cap to 2× the current limit and keeps going |
| **Continue (reset counter)** | Keeps the same limit, resets accumulated cost to $0.00 |
| **Refine the prompt** | Opens an input field so you can write a more focused prompt |
| **Stop the task** | Gracefully shuts down pi |

### Cost display

While tracking is enabled, current spending is shown live in the footer status bar:

```
💵 $1.23 / $3.00
```

## Configuration

Spending-guard reads from these files (project takes priority):

1. `.pi/spending-guard.json` — project-local
2. `~/.pi/agent/spending-guard.json` — global

If neither file exists, it defaults to **enabled** with a **$3.00 limit**.

### Config format

```json
{
  "enabled": true,
  "limit": 5.00
}
```

| Key | Type | Default | Description |
|-----|------|---------|-------------|
| `enabled` | `boolean` | `true` | Whether tracking starts active |
| `limit` | `number` | `3.00` | Spending threshold in USD |

### Per-project vs global

- Place the extension globally to track spending across all projects:
  ```bash
  pi install npm:@agentoom/pi-spending-guard
  ```
- Place a `.pi/spending-guard.json` in a specific project to override the default for that project only.

## Development

```
spending/
├── package.json
├── index.ts          # Extension entry point
├── .gitignore
└── README.md
```

Run against a local path:

```bash
pi install ./spending
```

## Links

- [agentoom.com](https://agentoom.com)
- [npm: @agentoom/pi-spending-guard](https://www.npmjs.com/package/@agentoom/pi-spending-guard)