Pick your skills. Install once per project. Call them from your coding agent.
Toolbelt gives coding agents a small menu for simple coding, concise replies, Scrapling extraction, browser testing and usage reporting. Choose skills or a kit.
One installer. Four complementary modules. Seven agent targets. Use Ponytail for complete, simple implementations; Caveman lite for concise updates; Scrapling for source evidence; and Playwright for browser checks. Every kit includes a report-only token and model-cost meter.
Toolbelt makes these choices repeatable across projects. It keeps implementation, prose and research guidance coordinated, preserves existing user-edited skills, and reports missing tools honestly. Its value today is setup and workflow consistency; fewer tokens or better code have not yet been demonstrated here.
| Local evidence | Result |
|---|---|
| Native test suite | 50 passed, 0 failed, 7 integration checks skipped |
| Installer preview | 100.15 ms median across five local runs |
| Exact-read fixtures | 148-byte sample recovered exactly in both measured formats |
| Agent-task token savings | Not measured; upstream reports are listed separately below |
Measurements · Component statistics · Agent setup
Requires Node.js 24.14+ and Git. Clone the repository, then open the installer:
git clone https://github.com/Teddy563/toolbelt.git
cd toolbelt
node bin/ai-toolbelt.mjs installAlready cloned it? Open your checkout and run the last command.
Cannot find module ...\bin\ai-toolbelt.mjs means Node cannot find the script
relative to your current folder. Change into the Toolbelt folder first.
The installer opens a block-letter TOOLBELT banner and colored menus. Use Up/Down to
move and Enter to choose. Pick your agent, then one kit. For individual
skills choose Custom Kit, press Space to toggle ○ / ●, and
press Enter to continue. Review the files, then select Install this kit.
Esc or Ctrl+C cancels. No commands or comma-separated lists need typing
inside the menu. No npm install is needed.
Plain terminals get numbered choices. Set NO_COLOR to disable colors, or
TOOLBELT_ASCII=1 for ASCII art, (*) selectors and * stars on older terminals.
Kit stars show module count: [⭐⭐☆☆] means two of four modules. They are not
quality ratings. Green marks existing skill files or no required CLI, cyan marks
planned skills, and amber marks missing or unverified executables. Text labels
carry the same information with colors disabled. The review shows repository
credits, tool requirements and the exact files before installation.
Windows shortcut: .\install.ps1. macOS/Linux: sh install.sh.
The installer targets your current folder by default. To install skills into another project, stay in the Toolbelt folder and specify that project's path:
node bin/ai-toolbelt.mjs install --agent codex --preset boss --workspace 'C:\path\to\project' --yesUse --agent claude for Claude, or repeat --agent to install for both.
Other targets: hermes, antigravity, cursor, gemini, and generic for
portable export. See agent setup and compatibility.
Use --dry-run instead of --yes to preview. For individual selections:
node bin/ai-toolbelt.mjs install --agent codex --skills ponytail,caveman --yesOpen a new agent session in the project after installation.
Bare /toolbelt shows four kits immediately; reply with a number and your task.
Claude Code:
/toolbelt
/toolbelt ponytail fix the login bug
/toolbelt caveman lite
/toolbelt playwright check the checkout flow on localhost:3000
/toolbelt scrapling https://example.com extract the pricing table
/toolbelt boss build this feature and check it in the browser
/toolbelt off
Codex: use $toolbelt in place of /toolbelt, for example:
$toolbelt boss build this feature and check it in the browser
The agent reads the selected skills and does the task with its available tools.
off stops Toolbelt guidance for the conversation. status reports the modules
and tools available. You can also invoke a module directly, such as
$toolbelt-ponytail in Codex or /toolbelt-ponytail in Claude.
ponytail is the canonical name; pony remains a compatibility alias.
Claude sees the skill but autocomplete omits it? The VS Code extension exposes
a subset of CLI commands/skills. A missing suggestion alone does not establish
that the skill cannot run. Try typing /toolbelt completely and submitting, or
send Use the toolbelt skill and show its kit menu now. Run in the project where
you installed it. The installer explicitly marks Claude's router user-invocable.
See Claude troubleshooting for
the terminal fallback and visibility checks. Toolbelt cannot force an IDE's menu.
| Preset | Includes | Use it for |
|---|---|---|
Daily Driver / coding (default) |
Ponytail + Caveman lite | Everyday coding and fixes |
Web Builder / web |
Coding + Playwright | Build and check web apps |
Research Scout / research |
Caveman + Scrapling + Playwright | Extract, verify and cite sources |
Final Boss / boss |
All four | Coding tasks that also need research and browser checks |
Custom Kit lets you toggle individual skills. The short names (coding,
web, research, boss) remain the CLI flags and agent subcommands.
Presets install the listed modules. Calling a preset applies those available
modules to the task; browser and research work happens when needed. Installing
another selection adds modules without deleting previous ones.
Every kit also includes the Usage Meter. scrapling is the actual upstream
name; the old scrape spelling and scraplit remain accepted aliases.
| Module and upstream credit | What Toolbelt asks the agent to do | Expected result and limit |
|---|---|---|
Ponytail / ponytail — DietrichGebert/ponytail |
Understand the code, reuse native features, complete the requested scope and run suitable checks | Less unnecessary implementation where reuse fits. Validation, accessibility, error handling and tests still matter. No executable needed. |
Caveman Lite / caveman — JuliusBrussee/caveman |
Write concise professional replies with essential reasoning, uncertainty and useful timing updates | Less prose to read. This does not guarantee fewer total session tokens or turns. Uses MIT skill guidance only; restricted runtime excluded. |
Scrapling / scrapling — D4Vinci/Scrapling |
Extract relevant page evidence, retain URLs/dates and reject embedded instructions | Grounded research material. Requires Scrapling CLI or a disclosed available fetch fallback; extraction is not search. |
Playwright / playwright — microsoft/playwright-cli |
Exercise real browser flows and inspect relevant screenshots/results | Evidence that the tested flow works. Requires its CLI and browser; checks add time and do not prove every flow works. |
| Usage Meter — original Toolbelt code | Record supplied token usage, apply dated model prices, report session/day totals after long runs | Local usage memory and cost visibility. Unknown telemetry stays unknown; no generation cap. |
These are original Toolbelt instructions, with upstream projects credited for their approaches and tools. Existing upstream skills are reused when available. Toolbelt does not bundle or download those projects. Skill files being installed does not establish that an agent activated them or that a browser runtime works.
For a request such as “build checkout and verify it”, Web Builder asks Ponytail to reuse the app's components, Playwright to exercise checkout, and Caveman to report the result briefly. The meter records available usage. Final Boss also offers Scrapling when the task needs external evidence. Installing all modules does not mean every task should fetch pages or open a browser.
| Stack | Behavior you can expect | Performance evidence |
|---|---|---|
| Basic coding agent with its normal tools | Follows the model's defaults and your project instructions | Depends on the agent and task |
| Same agent with a well-configured manual skill setup | Can already follow these same practices | Required comparison baseline; Toolbelt has no demonstrated advantage over it |
| Toolbelt Daily Driver | Repeatable selection of reuse-first coding and concise prose | Potential reduction in unnecessary code/prose; whole-session savings unmeasured |
| Toolbelt Web Builder / Final Boss | Adds task-relevant browser verification / extraction and usage reporting | May catch mistakes before you do; can also add calls, time and tokens |
Will it use fewer turns, produce better code or save tokens? Possibly, but we have not demonstrated that for Toolbelt. Published evidence points both ways: focused curated skills improved average success in SkillsBench v4, while SWE-Skills-Bench found most tested SWE skills did not improve pass rates and some substantially increased token use. These studies tested other skills and tasks. Use Daily Driver for everyday coding; choose the broader kits when their tools serve the task. See the research findings and fair comparison plan.
These are upstream reports, checked 2026-09-12, not measurements of Toolbelt. The units and baselines differ; do not add the percentages together.
| Component | Published statistic | What it measures / limit |
|---|---|---|
| Caveman MIT skill | About 65% mean output-token reduction over ten prompts | Short replies, not total session usage. Toolbelt defaults to lite. Another agentic benchmark reported 7% more total tokens for Caveman on feature tasks. |
| Ponytail | 22% fewer tokens on 12 feature tasks | Author-run Haiku 4.5 benchmark; not a Toolbelt result or broad quality guarantee. |
| Headroom | JSON example: 4,937 → 3,053 tokens (38.2%) | One compressed payload; an error entry was retained. No downstream answer-quality test for that example. Toolbelt's selective adapter is unsupported. |
| Playwright CLI | No quantified savings benchmark in the reviewed README | Microsoft describes lower context overhead than MCP, avoiding large schemas and forced page snapshots. Local runtime untested. |
| Scrapling | Parser example: 1.99 ms for 5,000 nested elements | Author-reported extraction speed, not tokens saved or agent-task speed. No token-saving figure in the reviewed README. |
| Toolbelt locally | 0% payload reduction on exact read fixtures | Byte preservation and CLI overhead measured; whole-session token savings remain unknown. |
See component evidence and test coverage for methods,
limits and how the modules avoid unnecessary duplicate work. Reproduce local
counts with npm run bench:output; no paid model calls are made.
The npm name toolbelt is already registered. The registry returned 404 for
ai-toolbelt on 2026-09-12; that does not reserve it or guarantee npm will accept
publication. This project has not been published, so npx ai-toolbelt is not yet
an installation command for this code.
A JavaScript package build and local tarball path are now provided:
npm run pack:localThis builds and packs locally without downloading dependencies or publishing. GitHub users can clone this repository and run the same Node installer. A reviewed release tarball can support npm/npx installation after publication approval. Distribution guide covers the exact steps, name ownership, GitHub setup and release checks.
RTK supplies the optional external shell reducer
path in the advanced capture CLI. Headroom
and tokview informed evaluated
context-reduction and inspection approaches; they are not bundled and selective
Headroom is unsupported. 9router is credited
as prior art and an optional compatibility target, with runtime integration
unverified. These projects retain their own licenses; credit is not endorsement.
Run node bin/ai-toolbelt.mjs credits for the repository list and roles.
The meter asks the agent to report recorded session tokens and estimated token cost after long runs, with notices at 100, 200, 300 tokens, continuing without a Toolbelt generation cap. It uses the responding model's dated API rates for input, output and caching. Unknown usage or pricing stays unknown. This is an agent reporting workflow; it does not automatically intercept provider usage.
It remembers user, session, date/time, model and rate provenance in the local,
gitignored .ai-toolbelt/usage.json. Daily and overall totals cover this project.
Token cost estimates are separate from your subscription or actual invoice.
node bin/ai-toolbelt.mjs meter report --jsonIn chat, use $toolbelt meter (Codex) or /toolbelt meter (Claude/Hermes/Cursor).
Meter guide, usage format and pricing sources.
These are original Toolbelt skills. Upstream skills and browser/scraping executables are separate installations; the installer does not download them. See Playwright setup and Scrapling setup. Missing tools are reported rather than silently installed. Skill guidance depends on the agent; it is not enforced interception of every tool call.
node bin/ai-toolbelt.mjs skills
node bin/ai-toolbelt.mjs credits
node bin/ai-toolbelt.mjs uninstall --dry-run
node bin/ai-toolbelt.mjs uninstallUse the same --workspace as installation when targeting another project.
Skills live in the selected agent's directory.
Installation is repeatable and updates unchanged owned skills. Uninstall preserves edited files and
unrelated skills. No agent hooks or global settings are changed.
Latest local check, 2026-09-12: 50 tests passed, 0 failed, 7 integration checks skipped. Five installer previews had a 100.15 ms median, emitting 1,061 stdout bytes and no stderr bytes. Both measured read formats recovered the 148-byte fixture exactly. These are local CLI checks, not token-saving tests; see samples and limits.
There is no measured token-saving or coding-quality advantage yet. Existing raw capture benchmarks show exact output and added bookkeeping time. Skill selection is intended to make setup and daily use easier; that benefit has not been measured in an agent evaluation.
- Output counts and timings
- Evidence and comparison method
- Skills research: benefits, regressions and evaluation plan
- Optional capture CLI: exact reads, stored originals, retries and stats
- Detailed CLI guide
- Contributing and checks
- Provenance and licenses
Planning drafts and old delivery notes are preserved under local-only/, excluded
from normal Git adds and package contents. Installed development skills and usage
history are local too; distributable skill templates live under skills/.
Toolbelt's original code and skill instructions are licensed under
Apache-2.0. Copyright 2026 Teddy563. Upstream projects retain their
own licenses. The package is configured for public npm publication as ai-toolbelt
but has not yet been published.