pi-ctx-budget

Context window budget display for pi — /ctx-budget command + toggleable footer

Packages

Package details

extensionskill

Install pi-ctx-budget from npm and Pi will load the resources declared by the package manifest.

npm repohome report
$ pi install npm:pi-ctx-budget
Package
pi-ctx-budget
Version
0.1.0
Published
May 19, 2026
Downloads
not available
Author
buihongduc132
License
MIT
Types
extension, skill
Size
28.3 KB
Dependencies
0 dependencies · 1 peer
Pi manifest JSON
{
  "extensions": [
    "./extensions"
  ],
  "skills": [
    "./skills"
  ]
}

Security note

Pi packages can execute code and influence agent behavior. Review the source before installing third-party packages.

README

pi-ctx-budget

npm version License: MIT

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