New: Insights — Token usage insights for coding agents
|
A Monorepo of Pi Extensions and Herdr Mods
A monorepo of benchmarked/minimal overhead tools I've built for Pi & Herdr:
- Pi extensions: terminal UI, subagent delegation, web search, interactive interviews, and permission controls.
- Herdr mods: Currently, just one - a local-first token-usage dashboard for Pi, Codex & different coding agents.
- Minimal by Design — Focused tools with minimal overhead. Context and schemas stay small to preserve the agent's context window.
- Keyless by Default — Public web and code retrieval work without API keys; Insights reads local session data without an account.
- Native Integration — Pi extensions use Pi's extension lifecycle, tools, slash commands, and themes. Herdr mods use Herdr's native mod system.
| Package | Description | Install |
|---|---|---|
| pi-slate | Minimal full-screen terminal UI with split sidebars and media previews. Zero context bloat. | pi install npm:pi-slate |
| pi-subagents | Tiny, benchmarked subagent harness with 88% less token overhead (benchmarks). | pi install npm:@gagansd/pi-subagents |
| pi-web-search | Cited public web and code search. Keyless by default with optional ranking. | pi install npm:@gagansd/pi-web-search |
| pi-ask | Structured interactive TUI interviews for human-in-the-loop decisions. | pi install npm:@gagansd/pi-ask |
| pi-automode (beta) | Permission gate for Pi: risky calls stop for a local decision, protected paths block, exact rules cut repeated asks. | pi install npm:@gagansd/pi-automode |
Requires Node.js >=22.19.0 and Pi >=1.0.0. Point Pi to a clone of this repository to register all five Pi extensions, skills, and Slate themes. This does not install Herdr mods:
git clone https://github.com/GaganSD/coding-agent-toolkit.git
cd coding-agent-toolkit
pi install .Then reload Pi with /reload.
Install individual extensions directly:
pi install npm:pi-slate # Terminal UI & themes
pi install npm:@gagansd/pi-subagents # Subagent delegation
pi install npm:@gagansd/pi-web-search # Public web & code search
pi install npm:@gagansd/pi-ask # Clarification interviews
pi install npm:@gagansd/pi-automode # Permission gate (opt-in, off by default)| Mod | Description | Install |
|---|---|---|
| Insights | Local-first token-usage dashboard with model rankings, usage trends, and an activity heatmap. Reads Pi, Codex, Claude Code, and OpenCode sessions. | From a checkout: npm run install:local --prefix herdr-insights |
Requires Herdr and Node.js 22.15+. No dependencies or account needed. From this repository's root:
npm run install:local --prefix herdr-insightsThe installer validates the mod with herdr-app check without opening a tab or test window. Add -- --open to open one Insights tab. It installs only mods/insights/ under ~/.config/herdr-app, leaving layouts, keys, and terminals unchanged. No Pi extension installation is required.
See the Insights README for standalone checkout instructions, settings, privacy details, and uninstallation, INSTALL.md for agent installation instructions, or RECIPE.md for the rebuild specification.
Prerequisites: Node.js >=22.19.0, npm >=10.0.0, Pi >=1.0.0.
npm ci --ignore-scripts
npm test # unit & integration
npm run typecheck
npm run test:tooling
npm run secrets:scan
npm run build --prefix pi-slate # or pi-subagents, pi-web-search, pi-ask, pi-automodeAfter pi install ., local edits apply on /reload.
Insights uses Node.js 22.15+; its native validation requires Herdr. Run its checks separately from the root Pi extension suite:
npm run test:insights
npm run check:insightsThese are developer checks, not installation steps. See the Insights development guide for opt-in native release validation.
After installing root development dependencies, count literal text locally (no API calls):
node scripts/tokens.mjs --text "hello world"
node scripts/tokens.mjs --file pi-ask/src/index.ts
printf 'hello world' | node scripts/tokens.mjs
node scripts/tokens.mjs --text "hello world" --encoding cl100k_base
# {"tokens":2,"encoding":"cl100k_base","scope":"text-only"}Shared repository scripts/tests can import countTokens(text, { encoding }) from
scripts/tokens.mjs; the encoding defaults to o200k_base. Encoders are cached
for repeated calls. Counts are exact for the selected tokenizer, not universal
model counts (e.g. Claude/Gemini), and exclude chat framing, tool schemas not
included in the input, images, and provider overhead. Input whitespace is preserved;
stdin adds no newline of its own. Special-token-looking strings are counted as
literal text. This is development tooling, not a runtime dependency shipped with
individual extensions.
@gagansd/pi-subagents is continuously benchmarked against standard delegation alternatives on dynamic multi-step workflows (parallel join, bounded repair, conditional fanout):
| Metric | @gagansd/pi-subagents |
pi-subagents |
Improvement |
|---|---|---|---|
| Package Size | 103.35 KB | 11.60 MB | 99.11% reduction |
| Initial Token Overhead | 718 | 6,158 | 88.34% reduction |
| Avg Tokens (5 tasks · Kimi-K3) | 331,346 | 638,964 | 48.14% fewer tokens |
| Avg Tokens (5 tasks · Grok-4.6) | 256,451 | 979,286 | 73.81% fewer tokens |
See benchmarks/README.md for full benchmark methodology, runner scripts, and scoring criteria.
coding-agent-toolkit/
├── pi-slate/ # Minimal TUI, custom surfaces, diff viewers & themes
├── pi-subagents/ # High-efficiency subagent delegation harness
├── pi-web-search/ # Multi-provider web & code search with classifier
├── pi-ask/ # Structured TUI interview & clarification modal
├── pi-automode/ # Parent-session permission gate with verified launcher
├── herdr-insights/ # Native Herdr mod: local coding-agent token-usage dashboard
├── benchmarks/ # Multi-model workflow benchmarking suite
├── docs/ # Architecture, CI/CD, and release guides
└── scripts/ # Build, test, security scanning, and release tools
- Continuous Integration: Every change runs type checks, unit/integration suites, clean consumer installations, and secret scans via GitHub Actions.
- Secret Protection: Automated pre-commit and CI scans with Gitleaks to prevent credential leaks.
- Dependency Auditing: Vulnerability scans with Snyk and
npm audit.
See CI/CD Documentation for release workflows and release preparation details.