pi-ctx-budget

Context window budget display for pi — track token usage across system prompts, skills, tools, and conversation with a /ctx-budget command and toggleable footer bar.

Features

• Token estimation — estimates source token usage from system context, skills, and tool schemas
• Runtime tracking — shows conversation token usage from live context data
• Compact display — renders ASCII budget summary with percentage breakdown
• Toggleable footer — optional persistent footer bar showing per-category token percentages
• Persistent config — footer preference saved to ~/.pi/pi-ctx-budget.json
• Environment overrides — PI_CTX_BUDGET_FOOTER=1 to force-enable footer

Installation

For Humans

npm install -g pi-ctx-budget

For AI Agents

This is a pi extension package. Add it to your pi settings.json:

{
  "packages": [
    {
      "name": "pi-ctx-budget",
      "url": "https://github.com/buihongduc132/pi-ctx-budget.git"
    }
  ]
}

For pi git-sourced

Clone into your git-sourced extensions directory:

cd ~/.pi/agent/git/github.com/buihongduc132/
git clone https://github.com/buihongduc132/pi-ctx-budget.git

Then ensure settings.json includes the git-sourced path.

Usage

/ctx-budget command

| Command | Description | |---------|-------------| | /ctx-budget | Compact budget summary | | /ctx-budget all | Verbose per-item breakdown | | /ctx-budget --verbose | Same as all | | /ctx-budget detail | Same as all | | /ctx-budget footer | Show footer toggle status | | /ctx-budget footer on | Enable footer (persisted) | | /ctx-budget footer off | Disable footer (persisted) | | /ctx-budget footer <category> | Toggle a footer category |

Footer categories

The footer bar shows percentage of context window used per category:

• Sys — System prompt (internal pi prompt + all context files)
• A — AGENTS.md files
• Sk — Skills
• T — Extension + MCP tools

Example output

╭─ Context Budget ──────────────────────────────────────╮
│ System    12,450t  ██████████████░░░░░░░░░  8.3%     │
│ Skills     1,200t  ████░░░░░░░░░░░░░░░░░░░  0.8%     │
│ Tools      3,800t  █████░░░░░░░░░░░░░░░░░  2.5%     │
│ Conv       8,200t  ███████████░░░░░░░░░░░  5.5%     │
│ Free    134,350t  ░░░░░░░░░░░░░░░░░░░░  82.9%     │
│ Model: gpt-4o  Window: 150K                         │
╰──────────────────────────────────────────────────────╯

Development

npm install
npm run typecheck    # TypeScript type checking
npm test             # Run tests
npm run test:coverage # Tests with coverage
npm run smoke-test   # Quick smoke test
npm pack --dry-run   # Verify package contents

License

MIT © buihongduc132