TCalc: know what your coding agent can fit before the session starts

Overview

TCalc is a local-first tool for developers who use coding agents on real repositories. It measures estimated tokens by file, folder, and language, then connects those numbers to context fit and estimated session cost. The scan can also produce a budgeted repo map, an agent rules file, or a Markdown and JSON report.

The project is available as a VS Code extension and CLI. An experimental stdio MCP server exposes the same scan, recommendation, repo-map, rules, and report capabilities to compatible clients. Source stays on the user's machine, and the repository includes a check that guards the no-telemetry requirement.

Problem

A file count is a poor proxy for context size. A repository may contain generated output, vendored code, fixtures, or a few large files that consume most of a model's window. Developers often discover that only after a session has started and the agent has already read the wrong material.

Model choice creates a second guess. The largest model is not always needed, but choosing a smaller one without measuring the workspace can lead to truncation or repeated context loading. TCalc makes both decisions visible before the coding session begins.

Approach

The scanner follows workspace ignore rules and classifies files before estimating tokens. The recommendation layer keeps model metadata separate from scanning logic, so catalogs can change without rewriting the core. It scores options against the scan and the user's goal instead of naming one model as universally best.

The output is meant to be used, not merely observed. A developer can set a token budget for a repo map, generate rules for Codex, Claude Code, Cursor, and other agents, or create an MCP configuration from the command line.

Architecture

TCalc uses a pnpm workspace so each concern can evolve without tying the scanner to one editor or interface. Shared packages power the CLI, VS Code extension, dashboard, and experimental MCP server.

• - Core package for shared types, configuration, and constants.
• - Scanner and tokenizer packages for discovery, ignore handling, classification, and estimates.
• - Model catalog and recommender packages for context fit, goal scoring, and cost estimates.
• - Repo-map, agent-rules, and report packages for reusable output formats.
• - Commander-based CLI and VS Code extension built on the same local core.
• - Experimental stdio MCP server with no hosted transport.

What I Built

The first usable path was the command line: scan a folder, inspect the largest paths, and compare models. I then built the VS Code quick start so the same flow could run against the open workspace without asking developers to memorize commands.

• - Workspace scans with included and excluded files, warnings, and token-heavy paths.
• - Goal-aware model recommendations with context fit and estimated cost.
• - Budgeted repo maps and generated agent rule files.
• - Markdown and JSON reports for review or automation.
• - VSIX packaging and controlled publishing workflows for VS Code and Open VSX.
• - CI, Vitest coverage, smoke checks, and a no-telemetry check.

Challenges & Tradeoffs

Token counts are estimates because tokenizers and model behavior vary. TCalc reports that uncertainty and keeps provider data in catalogs rather than hiding the numbers behind a single score. Model prices and context limits also change, so catalog validation is part of the maintenance work.

Local processing protects source code, but it rules out a hosted analysis shortcut. The scanner, report generation, and recommendations all have to run well on the developer's machine. The MCP server remains an experimental stdio-only feature for the same reason.

Results

TCalc shipped as an open-source VS Code extension and CLI with installable packages, documentation, automated tests, and repeatable publishing checks. A developer can now measure context pressure and prepare a focused starting map before asking an agent to work on the repository.

Tech Stack

• TypeScript
• Node.js
• pnpm
• Vitest
• VS Code API
• Commander.js
• MCP

The codebase is written in TypeScript and runs on Node.js. pnpm manages the monorepo, Vitest covers package behavior, Commander powers the CLI, and the VS Code API provides editor commands and the dashboard. A Next.js application hosts the product site and documentation.

Links

The product site explains the workflow and installation choices. The repository contains the packages, CLI commands, extension source, MCP documentation, tests, and release instructions.