TokenSaver

TokenSaver is a local-first prompt compression and AI-agent skills package for company-wide use. It is based on JuliusBrussee/caveman, renamed and extended with TokenSaver commands, local metrics, Cursor/Codex setup, SkillSpector security scanning, and bundled engineering skills.

TokenSaver does not route prompts, code, responses, secrets, or files through a TokenSaver server. It installs local rules, commands, hooks, and skill files into supported tools.

Core Features

| Feature | What it gives you | | --- | --- | | TokenSaver response modes | Terse answer styles: lite, full, ultra, wenyan, and off. | | Cursor support | Project rules and slash commands for always-on TokenSaver behavior. | | Codex support | Project commands, hooks, and AGENTS-style rule activation. | | Claude Code hooks | Session/UserPrompt hooks, stats capture, and optional statusline savings badge. | | opencode/OpenClaw support | Local plugin/rule install paths for supported agent environments. | | Local stats | Aggregate saved-token and estimated-cost reporting without storing prompt text. | | SkillSpector integration | Optional NVIDIA SkillSpector scan wrapper with static-only default. | | Bundled skills | 24 TokenSaver skills for reviews, APIs, security, backend/frontend, Java/Kotlin/Spring/NestJS, E2E, research, CodeTour, and minimal-code Ponytail style. | | Company-safe defaults | External package/marketplace installs disabled unless explicitly allowed. |

Privacy And Safety

TokenSaver is designed for internal rollout where data sharing must be avoided.

• No TokenSaver backend.
• No prompt text stored.
• No response text stored.
• No source code stored in analytics.
• No API keys, user identifiers, or file contents stored in metrics.
• Cursor/Codex rule files stay inside the workspace.
• SkillSpector scans default to --no-llm.
• External package or marketplace installs are blocked unless --allow-network-installs is passed.

Local metric files contain aggregate counts only, such as token totals, saved token estimates, timestamps, model names when available, session ids, and mode.

Quick Install

Fastest path for a new machine: use npx. This does not depend on npm global bin PATH, so it avoids the common tokensaver: command not found issue.

Cursor:

npx -y @manikchhabra/tokensaver --with-init --only cursor

Codex:

npx -y @manikchhabra/tokensaver --with-init --only codex

Cursor + Codex:

npx -y @manikchhabra/tokensaver --with-init --only cursor --only codex

Optional SkillSpector install:

npx -y @manikchhabra/tokensaver --install-skillspector

Global Installation

From this checkout:

node bin/install.js --list
node bin/install.js --with-init --only cursor
node bin/install.js --with-init --only codex

From the npm package after publishing:

npm install -g @manikchhabra/tokensaver
tokensaver --list
tokensaver --with-init --only cursor

If npm install -g succeeds but tokensaver says command not found, npm's global bin folder is not on your shell PATH. Check where npm installed it:

npm prefix -g

On macOS/Linux with npm or nvm, add this to ~/.zshrc or ~/.bashrc:

export PATH="$(npm prefix -g)/bin:$PATH"

Then reload your shell:

source ~/.zshrc
command -v tokensaver
tokensaver --help

On Windows PowerShell, npm global shims usually live directly under the prefix:

npm prefix -g
$env:Path += ";$(npm prefix -g)"
tokensaver --help

If you do not want to touch PATH, use the npx commands from Quick Install.

From a local tarball:

npm install -g /path/to/manikchhabra-tokensaver-0.1.3.tgz
tokensaver --with-init --only cursor

Shell shims from this checkout:

bash install.sh --only claude
pwsh install.ps1 --only claude

Common Commands

tokensaver --help
tokensaver --list
tokensaver --with-init --only cursor
tokensaver --with-init --only codex
tokensaver --mode full
tokensaver --mode ultra
tokensaver --mode off
tokensaver --cursor-stats
tokensaver --cursor-stats-json
tokensaver --scan-skills
tokensaver --install-skillspector
tokensaver --uninstall

Useful install flags:

| Flag | Purpose | | --- | --- | | --with-init | Write project rule/command files into the current repo. | | --only <agent> | Install for one target, for example cursor, codex, claude, opencode, or openclaw. | | --all | Enable hooks, init files, and MCP shrink wiring. | | --minimal | Install only core plugin/extension pieces. | | --non-interactive | Do not prompt. Useful for managed rollout scripts. | | --allow-network-installs | Allow external package/marketplace calls. Off by default. | | --install-skillspector | Install NVIDIA SkillSpector locally for skill scanning. | | --no-skillspector | Skip SkillSpector prompt. |

Cursor Usage

Cursor supports project rules from .cursor/rules/*.mdc and slash commands from .cursor/commands/*.md. Install both:

tokensaver --with-init --only cursor

This writes:

• .cursor/rules/tokensaver.mdc
• .cursor/commands/tokensaver.md
• .cursor/commands/tokensaver-help.md
• .cursor/commands/tokensaver-stats.md
• .cursor/commands/tokensaver-commit.md
• .cursor/commands/tokensaver-review.md
• .cursor/commands/tokensaver-compress.md
• .cursor/commands/tokensaver-ponytail-style.md

Reload Cursor after install.

Cursor does not expose a safe extension hook to rewrite every third-party AI prompt before send. TokenSaver therefore uses an always-on project rule so normal chats behave like an implicit /tokensaver <request> where Cursor supports rule application.

Use in chat:

/tokensaver
/tokensaver full
/tokensaver ultra
/tokensaver off
/tokensaver review this file
/tokensaver-stats
/tokensaver-ponytail-style fix this with smallest safe diff

Mode is stored locally in .tokensaver/config.json.

Codex Usage

Install Codex project support:

tokensaver --with-init --only codex

This writes:

• .codex/config.toml
• .codex/hooks.json
• .codex/commands/*.toml for TokenSaver core commands and bundled skills
• AGENTS.md style activation rules where applicable

Use:

/tokensaver full
/tokensaver ultra
/tokensaver off
/tokensaver-ponytail-style fix this with smallest safe diff
/tokensaver-api-design design this endpoint
/tokensaver-security-review review this auth flow
/tokensaver-springboot-verification verify this service

Specialty Codex slash commands are generated for every bundled skill, including API design, API connector builder, backend/frontend patterns, cost tracking, deep research, E2E testing, Java/Kotlin, Liquid Glass design, NestJS, security review, Spring Boot patterns/security/verification, CodeTour, Ponytail style, and TokenCrew.

Or from shell:

tokensaver --mode full
tokensaver --mode ultra
tokensaver --mode off

Claude Code Usage

Claude Code support includes TokenSaver hooks and stats capture. Install:

tokensaver --only claude

Stats commands inside Claude Code:

/tokensaver-stats
/tokensaver-stats --all
/tokensaver-stats --since 7d

Hook metrics are written under the Claude config directory:

• .tokensaver-history.jsonl
• .tokensaver-analytics.json
• .tokensaver-statusline-suffix

Stats And Savings

Cursor local stats:

tokensaver --cursor-stats
tokensaver --cursor-stats-json

Mode estimates:

| Mode | Typical reduction | | --- | --- | | lite | Lower compression, more natural language. | | full | Default balanced compression. | | ultra | Aggressive compression. | | wenyan | Maximum terse style. | | off | Disable TokenSaver style. |

Measured savings are only available where the host exposes enough prompt or response information to local hooks. Cursor does not expose every AI prompt stream to extensions or rules, so Cursor savings may include estimates rather than full measured accounting.

SkillSpector Scanning

TokenSaver includes a wrapper for NVIDIA SkillSpector.

Install SkillSpector:

tokensaver --install-skillspector

Scan all bundled skills:

tokensaver --scan-skills

Default behavior scans every child skill under skills/*/SKILL.md individually, so reports show real skill names instead of Skill: unknown.

Scan one skill:

tokensaver --scan-skills ./skills/tokensaver-security-review

Write reports:

tokensaver --scan-skills --scan-format markdown --scan-output skillspector-reports
tokensaver --scan-skills --scan-format sarif --scan-output skillspector-reports
tokensaver --scan-skills --scan-format json --scan-output skillspector-reports

Force legacy single-input scan:

tokensaver --scan-skills ./skills --scan-single
tokensaver-skillspector ./skills --single

Privacy default:

skillspector scan <target> --no-llm

Allow SkillSpector semantic LLM stage only after company approval:

tokensaver --scan-skills --allow-scan-llm

Bundled Skills

TokenSaver currently ships these skills:

| Skill | Use | | --- | --- | | tokensaver | Compressed response mode for lower-token technical answers. | | tokensaver-help | Quick command and mode reference. | | tokensaver-stats | Local savings, usage, and estimated cost reporting. | | tokensaver-commit | Compact Conventional Commit messages. | | tokensaver-review | Dense, actionable code review comments. | | tokensaver-compress | Compress memory/rule files while preserving technical content. | | tokencrew | Delegation guide for investigator, builder, and reviewer subagents. | | tokensaver-api-design | REST API naming, pagination, errors, versioning, and rate limits. | | tokensaver-api-connector-builder | Add API connectors by following existing repo patterns. | | tokensaver-backend-patterns | Node.js, Express, and Next.js backend architecture patterns. | | tokensaver-cost-tracking | Analyze local token usage, spend, budgets, and cost reports. | | tokensaver-deep-research | Cited web research with external MCP privacy gates. | | tokensaver-e2e-testing | Playwright E2E patterns, CI artifacts, and flake controls. | | tokensaver-frontend-patterns | React and Next.js UI, state, data, performance, and a11y patterns. | | tokensaver-java-coding-standards | Java standards for Spring Boot and Quarkus services. | | tokensaver-kotlin-patterns | Idiomatic Kotlin, coroutines, null safety, and Gradle DSLs. | | tokensaver-liquid-glass-design | iOS Liquid Glass design guidance for SwiftUI/UIKit/WidgetKit. | | tokensaver-nestjs-patterns | NestJS modules, controllers, providers, DTOs, guards, and interceptors. | | tokensaver-ponytail-style | Minimal-code, YAGNI, stdlib/native-first implementation style inspired by Ponytail. | | tokensaver-security-review | Security review for auth, input, secrets, endpoints, and sensitive flows. | | tokensaver-springboot-patterns | Spring Boot REST, service, data, caching, async, and logging patterns. | | tokensaver-springboot-security | Spring Security authn/authz, CSRF, CORS, headers, and dependency checks. | | tokensaver-springboot-verification | Spring Boot build, test, coverage, static analysis, and release checks. | | tokensaver-code-tour | CodeTour walkthroughs with real file and line anchors. |

Codex slash commands are generated for every bundled skill during tokensaver --with-init --only codex.

Company Distribution

Recommended rollout:

npm install -g @manikchhabra/tokensaver
tokensaver --with-init --only cursor --non-interactive
tokensaver --with-init --only codex --non-interactive
tokensaver --install-skillspector --non-interactive
tokensaver --scan-skills

For internal package registries, publish the scoped package to the approved registry and distribute the same install commands with your registry config.

More rollout detail:

• docs/ORGANIZATION_DISTRIBUTION_GUIDE.md
• docs/QUICK_INSTALL_CURSOR_CODEX.md
• docs/SKILLSPECTOR_INTEGRATION.md
• docs/TOKENIZER_EVALUATION.md
• docs/BUNDLED_ECC_SKILLS.md
• docs/ECC_SKILLS_ONE_LINERS.md

Uninstall

tokensaver --uninstall

or from source:

node bin/install.js --uninstall

Remove npm package:

npm uninstall -g @manikchhabra/tokensaver

License

MIT. See LICENSE and NOTICE for upstream attribution.