🧮 Token Calculator Suite

imageLicense: MIT imageNode.js imageTypeScript imagePlatforms

Conforms to Agent Plugins 1.0.0 — the portable packaging format from the Agentic AI Foundation (OpenAI, Amazon, Microsoft, Cursor and Vercel, with Google as core maintainer). The repository root is the plugin root: it carries the portable plugin.json manifest alongside .claude-plugin/ and the four skills in skills/token-analysis/, skills/file-analysis/, skills/project-cost/ and skills/model-comparison/, so any conformant client discovers them.

Works in ChatGPT. The skills are plain text — instructions and criteria, no local execution — so they install by switching Work on in the ChatGPT selector and adding them from Plugins, by name or by this repository's URL. They behave the same as in Claude. Their frontmatter validates against the closed Agent Skills field set, which is what ChatGPT, claude.ai and the Skills API require to accept an upload: an extra key there is not ignored, it fails hard. Also available on the free plan, with usage limits.

Unified token calculation system for Claude Chat, Cowork, and Claude Code.

Reusable, open-source library for estimating Claude token consumption across three Anthropic platforms. Built with modularity, accuracy, and privacy in mind.

✨ Features:

• 📊 Accurate token estimation (±18% with exact data)
• 🔄 Single source of truth (shared core library)
• 🌍 Multi-platform: Chat, Cowork, Claude Code
• 🛡️ Privacy-first (Option C consent model)
• 📦 Production-ready TypeScript
• 📚 Fully documented with examples

📦 What's included

token-calculator-suite/
├── skills/                      ← Plugin skills (Cowork + Claude Code)
├── plugin.json                  ← Agent Plugins 1.0.0 manifest
├── .claude-plugin/              ← Claude Code manifest + marketplace entry
├── packages/
│   ├── core/                    ← Shared calculation logic
│   ├── calculador-tokens-v2/    ← Claude.ai skill
│   └── cli/                     ← token-calc CLI (@token-calc/cli)
├── README.md                    ← This file
└── package.json                 ← Monorepo config

🚀 Quick Start

For Chat (claude.ai)

Installation: Copy the whole packages/calculador-tokens-v2/ directory into your skills folder. Copy the directory, not just the SKILL.md: the Agent Skills spec requires the folder name to match the frontmatter name, which is what identifies the skill.

Usage:

/tokens

Features:

• ✅ Calculates tokens in current conversation
• ✅ Opción C: Asks permission before using personal data
• ✅ Accuracy: ±18% with exact data, ±22-30% without
• ✅ Real-time context usage tracking

For Cowork

Installation:

1. Zip the repository root (it is the plugin root: plugin.json, .claude-plugin/ and skills/ all live there) as token-calculator.zip
2. In Cowork: Customize > Plugins > Upload > Select zip

Usage:

/token-calculator:token-analysis     # Analyze text for token count and cost
/token-calculator:file-analysis      # Estimate a file's token consumption
/token-calculator:project-cost       # Estimate total API cost for a project
/token-calculator:model-comparison   # Compare models by cost and context window

Features:

• ✅ Analyzes PDFs, DOCX, images, code files
• ✅ Generates batch reports for multiple files
• ✅ Suggests optimization opportunities
• ✅ Exports as CSV or table

For Claude Code

Two independent ways to use this in Claude Code. They are not alternatives to each other — most people want the first.

This package is a CLI, not an MCP server. Earlier revisions of this section described registering a dist/mcp-server.js under mcpServers. That file does not exist and never did: the package (@token-calc/cli) has no MCP SDK dependency and implements no JSON-RPC. Its build output is dist/cli.js, a token-calc executable. If you followed those instructions and got stuck looking for mcp-server.js, that is why. See issue #1.

Option A — Install the plugin (skills only, no build)

/plugin marketplace add https://github.com/novanoticia/token-calculator-suite
/plugin install token-calculator@token-calculator-suite
/reload-plugins

Then invoke any of the four skills:

/token-calculator:token-analysis      # tokens and cost for a chunk of text
/token-calculator:file-analysis       # what a file will cost in context
/token-calculator:project-cost        # total API cost for a project
/token-calculator:model-comparison    # models by cost and context window

Nothing to compile: the skills are Markdown.

Option B — Build the token-calc CLI

Prerequisites

• Node.js 18.0.0 or higher (node --version)
• Yarn 4 (Berry). This matters: the workspaces use the workspace:* protocol and the lockfile is Berry v8. Yarn Classic (1.x) fails outright with Couldn't find package "@token-calc/core@workspace:*" ... on the "npm" registry. Enable Berry with corepack enable && yarn set version stable.
• Git

Steps

1. Clone

   git clone https://github.com/novanoticia/token-calculator-suite.git
   cd token-calculator-suite
   

2. Install dependencies

   yarn install
   

   .yarnrc.yml already sets nodeLinker: node-modules, so this produces a real node_modules tree rather than Yarn PnP.

3. Build

   yarn build
   

   This builds @token-calc/core and then @token-calc/cli, in that order — the CLI depends on core. To build just one: yarn build:core or yarn build:cli.

4. Verify

   ls packages/cli/dist/
   

   You should see cli.js. That is the executable the token-calc bin points to.

5. Run it

   node packages/cli/dist/cli.js tokens \
     --messages 50 --user-words 5000 --assistant-words 8000 --lang es
   
   node packages/cli/dist/cli.js convert --words 1000 --lang es
   node packages/cli/dist/cli.js file --path ./document.pdf
   node packages/cli/dist/cli.js help
   

   To get a bare token-calc on your PATH, link the package once. npm link is the one that creates a global bin — Yarn Berry's yarn link does something different (it links a package into another project, not onto your PATH):

   cd packages/cli && npm link && cd -
   token-calc help
   

   Or skip linking and add an alias:

   alias token-calc="node $(pwd)/packages/cli/dist/cli.js"
   

6. Use it from Claude Code

   There is nothing to configure. Claude runs it through the Bash tool like any other command — just tell it what you want, mentioning the path or the linked binary:

   "Run token-calc on ./informe.pdf and tell me if it fits in the context window"

   To let Claude call it without asking permission each time, add it to your allowed tools, for example Bash(token-calc:*).

Troubleshooting

• Couldn't find package "@token-calc/core@workspace:*" — you are on Yarn Classic. Run corepack enable && yarn set version stable, then yarn install again.
• yarn build compiles core but not the CLI — you are on a revision from before the root build script chained both. Use yarn build:cli directly.
• Looking for mcp-server.js — it does not exist. The build output is packages/cli/dist/cli.js. See the note at the top of this section.
• Type errors about process or fs — @types/node must be installed at the root; it is already in the root devDependencies, so re-run yarn install.
• Unknown command: undefined — you ran the CLI with no arguments. That message is followed by the usage text; pick one of tokens, file, convert, help.

What the CLI gives you

• ✅ Token estimation for a conversation, with a min–max range and a confidence level
• ✅ File analysis (PDF, DOCX, images, code) by path or by type and size
• ✅ Word and character conversion, language-aware (ES/EN)
• ✅ Context-window usage as an absolute figure and a percentage
• ✅ Human-readable output plus a JSON block for piping

📊 How It Works

Core Library (packages/core/)

All platforms share a single source of truth:

calculateTokens({
  messageCount: 50,
  userWords: 5000,
  assistantWords: 8000,
  language: 'es',
  useExactData: true
})

Returns:

{
  "totalTokens": 28540,
  "minEstimate": 23000,
  "maxEstimate": 34000,
  "errorMarginPercent": "±18%",
  "contextUsage": {
    "tokensUsed": 28540,
    "tokensAvailable": 200000,
    "percentageUsed": 14.27
  },
  "confidence": "high"
}

Accuracy Levels

Supported File Types

🔧 Architecture

Three Tiers

┌─────────────────────────────────────────────────┐
│ PRESENTATION LAYER                              │
├──────────────┬──────────────┬──────────────────┤
│ Chat Skill   │ Cowork Plugin│ Claude Code CLI  │
├──────────────┴──────────────┴──────────────────┤
│ SHARED CORE LIBRARY (@token-calc/core)         │
├─────────────────────────────────────────────────┤
│ - Calculation algorithms                        │
│ - Constants & ratios                            │
│ - Language-specific tokenization                │
│ - Error margin logic                            │
└─────────────────────────────────────────────────┘

Modification Guide

To change a calculation formula:

1. Edit packages/core/src/index.ts
2. Run yarn build
3. All platforms automatically use new logic

To add a new file type:

1. Add to packages/core/src/constants.ts
2. Implement in calculateFileTokens()
3. Available to all platforms immediately

📝 Configuration

Language Support

// Spanish (default)
calculateTokens({ language: 'es' })  // 1 word ≈ 1.3 tokens

// English
calculateTokens({ language: 'en' })  // 1 word ≈ 1.0 tokens

Privacy (Option C)

First time only, asks for consent:

🔐 Can I use your Preferences + Memory for exact calculations?
[SÍ] [NO]

• Yes: ±18% accuracy (uses 3,468 exact tokens)
• No: ±22-30% accuracy (estimates only)

🎯 Use Cases

Personal

• "How many tokens am I using this week?"
• "Will this PDF fit in my context window?"
• "Should I archive old conversations?"

Team/Enterprise

• Token budget tracking across projects
• File size optimization recommendations
• Cost estimation for Claude API usage
• Compliance reporting (document processing)

Developer

• Estimate API costs before calling Claude
• Optimize prompt engineering (token budgeting)
• Batch processing analysis
• Automated workflow optimization

🔐 Privacy & Security

✅ No external data collection

• All calculations run locally
• Personal data (Preferences/Memory) never sent anywhere
• Option C requires explicit consent before use

✅ Transparent accuracy

• Always shows error margins
• Distinguishes "known" vs "estimated" data
• Reports confidence levels

🤝 Contributing

All code is open source on GitHub.

Setup dev environment

git clone https://github.com/token-calculator-suite/token-calculator-suite.git
cd token-calculator-suite
yarn install
yarn build

To customize for your team

1. Fork repo
2. Edit constants in packages/core/src/constants.ts
3. Customize skills/commands for your workflow
4. Deploy to your Cowork/Code instances

📚 Documentation

🐛 Known Limitations

• System prompt estimation is ±1.5k tokens (not observable)
• Web search results compression varies (±20%)
• Language detection not automatic (must specify --lang)
• Concurrent file analysis in Cowork not optimized for >100 files

📞 Support

• Bug reports: GitHub Issues
• Feature requests: GitHub Discussions
• Custom integrations: Contact maintainers

📄 License

MIT License. Free to use, modify, and distribute.

🙏 Acknowledgments

Built with modularity first, tested across three Anthropic platforms.

Last updated: March 2026 Maintainers: Token Calculator Suite Contributors

Part of token-calculator-suite. Made for accuracy, privacy, and reusability.