tokenlean

60+ CLI tools + MCP server that let AI agents understand codebases without burning tokens

Why • Install • Quick Reference • All Tools • AI Integration • Workflows • Languages

---

Zero config — npm i -g tokenlean and you're done · Token-conscious — every tool outputs only what's needed · Fast — ripgrep-powered with disk caching · Multi-language — JS/TS, Python, Go, Rust, Ruby · MCP native — structured tool access, no shell overhead · Minimal deps — installs in seconds

---

The Problem

If you've ever checked your usage quota at 2 PM and decided whether to debug now or wait for the reset — this is for you. Enterprise teams with unlimited API keys don't feel the burn. Solo devs, small teams, anyone on a Pro subscription does. Every cat of a 2000-line file when you needed one function, every 300-line test run when only 3 lines failed, every full directory read to find a signature — that's your working day getting shorter.

tokenlean fixes this:

Instead of...	Use	Savings
Reading a 500-line file for signatures	tl symbols	~90% fewer tokens
Reading all files to find exports	tl exports	~95% fewer tokens
Guessing what a change might break	tl impact	Know for sure
Reading a file to extract one function	tl snippet	~85% fewer tokens
Running npm test and reading all output	tl run "npm test"	Errors only
Scanning long logs for real failures	tl tail app.log	Errors/warns + dedupe

How much are you wasting?

Find out in one command, no install needed:

npx tokenlean audit --all --savings --claudecode

Summary (348 Claude Code sessions)
Opportunities:
Category Count Actual Saveable Suggestion
----------------------------------------------------------------------------
read-large-file 75x 253.4k 202.7k -> tl symbols + tl snippet
build-test-output 34x 28.2k 18.3k -> tl run
tail-command 7x 4.8k 3.3k -> tl tail
curl-command 13x 3.2k 2.3k -> tl browse
cat-large-file 1x 1.1k 902 -> tl symbols + tl snippet
webfetch 4x 1.2k 823 -> tl browse
head-command 11x 3.8k 759 -> Read tool (with limit)
Still saveable: 243.6k of 363.9k (67%)
Already saved by tokenlean:
Tool Count Compressed Raw estimate Saved
------------------------------------------------------------------
tl snippet 233x 215.7k 2.2M 1.9M
tl symbols 93x 59.0k 295.0k 236.0k
tl run 98x 28.7k 82.0k 53.3k
Tokens saved: 2.2M (424 uses)
Capture rate: 90% of potential savings realized

Install

npm install -g tokenlean

Requires Node.js >= 18, ripgrep for search tools, and git for history tools.

Use tl as the global entry point — one command, many subcommands:

tl # List all available commands
tl doctor # Verify Node.js, ripgrep, git, hooks, and config
tl doctor --agents # Check MCP, hooks, skills, and project instructions
tl update # Update the global tokenlean install
tl completions bash|zsh # Tab completions for subcommands and flags

Development setup

git clone https://github.com/edimuj/tokenlean.git
cd tokenlean
npm link

Quick Reference

# What's in this file? tl symbols src/auth.ts# Functions only (dir/multi-file) tl symbols src/ --filter function# Extract just one function tl snippet handleSubmit# What does this module export? tl exports src/lib/# How many tokens will this cost? tl context src/api/# What's the project shape? tl structure# What depends on this file? tl impact src/auth.ts# How complex is this code? tl complexity src/auth.ts# Where are the tests? tl related src/Button.tsx# What changed recently? tl diff --staged# Is it safe to commit? tl guard # Caps noisy details; use --full for all# Any duplicate functions? tl dupes src/ --near # Copy-paste, renamed clones, repeated names# Does this helper exist yet? tl lookup "strip ansi" # Search before writing — prevents dupes# Find real usage examples tl example useAuth# Summarize noisy logs tl tail logs/app.log# What's the tech stack? tl stack# Workflow-ready briefing tl pack refactor src/auth.ts# Area refactor briefing tl pack refactor src/# What should I run next? tl advise "debug npm test"# Commit + push in one call tl push "fix: race condition" src/worker.mjs# Publish, wait, reinstall tl publish patch --install-globally

Every tool supports -l N (limit lines), -t N (limit tokens), -j (JSON output), -q (quiet), and -h (help).

See all tools for the complete reference.

AI Agent Integration

Add tokenlean instructions to your AI tool's config with a single command:

AI Tool	Command
Claude Code	tl prompt >> CLAUDE.md
Codex	tl prompt --codex >> AGENTS.md
Cursor	tl prompt --minimal >> .cursorrules
GitHub Copilot	tl prompt >> .github/copilot-instructions.md
Windsurf	tl prompt --minimal >> .windsurfrules

MCP Server — expose tokenlean as native MCP tools for structured, faster access with no CLI overhead:

# Add to any project's .mcp.json (Claude Code, Codex, etc.)
{
"mcpServers": {
"tokenlean": { "command": "tl mcp" }
}
}
# Or pick just the tools you need
{ "command": "tl mcp", "args": ["--tools", "symbols,snippet,run"] }

MCP tools include the core context reducers (tl_symbols, tl_snippet, tl_run, tl_impact, tl_browse, tl_tail, tl_guard, tl_diff), workflow routers (tl_advise, tl_pack), briefing tools (tl_analyze, tl_related, tl_context, tl_structure, tl_entry), and GitHub operations (tl_gh_issue_read, tl_gh_issue_close, tl_gh_issue_add_sub, tl_gh_issue_close_batch, tl_gh_issue_label_batch, tl_gh_project_add_batch, tl_gh_issue_create_batch). Structured JSON in/out — no bash command construction, no argument parsing, no stdout scraping.

The tl_gh_* tools accept both their native repo: "owner/repo" shape and the GitHub-MCP convention (split owner + bare repo, issue_number). Input schemas are strict: unknown keys and conflicting aliases are rejected instead of silently discarded. Single-issue mutations such as tl_gh_issue_close require a scalar identifier; use the explicit batch tool for arrays.

All MCP tools accept an optional cwd argument for shared-server setups where the MCP server process is not already running in the target repo. Structured responses default to 100 primary items and about 8,000 aggregate tokens; read-only tools accept maxItems, maxTokens, and directly callable continuation arguments. Commands and mutations are token-bounded but non-pageable so following a continuation cannot replay a side effect. Responses distinguish success, empty, partial, failed, and unsupported; actionable errors include a stable code, absolute effective cwd, and recovery call. For tl_run, use commandTimeoutMs or commandTimeoutSeconds to control the child command runtime; avoid a generic timeout argument because some MCP clients treat that as the request envelope timeout. For commands likely to exceed a client tools/call watchdog, start them with async: true; tokenlean long-polls under the watchdog and returns either the result or a jobId to poll again with a long waitSeconds value. For tl_pack debug packs, pass command when you want to execute a command; prose target values are kept as context instead of being treated as shell commands.

Hooks — automatically nudge agents toward token-efficient tool usage:

tl hook install claude-code # PreToolUse nudges for Claude Code
tl hook install codex # PreToolUse nudges for Codex CLI
tl hook status --all # Check hook adapters
tl hook run -j # Structured policy decision for adapters/MCP
tl audit --all --savings # Measure actual savings across sessions
tl audit --all --plan # Turn audit findings into prioritized fixes

Each client receives the correct hook output format automatically — Claude Code uses hookSpecificOutput.permissionDecision, Codex uses systemMessage. The installer wires --target so the same policy engine serves both.

See measuring token savings for full audit and hook setup details.

Agent Skills

Ready-made workflows following the Agent Skills open format. Each workflow ships in Claude Code and Codex variants with runtime-specific wording, but the underlying method is the same: gather narrow context first, then act.

Workflow	Use it when...	Claude Code	Codex
Code review	Reviewing a PR or local diff with risk-first context gathering	code-review	code-review
Explore codebase	Understanding an unfamiliar repo without reading everything	explore-codebase	explore-codebase
Safe refactor	Renaming, moving, extracting, or reshaping shared code	safe-refactor	safe-refactor
Add feature	Implementing behavior after locating existing patterns	add-feature	add-feature
Debug bug	Reproducing, tracing, fixing, and verifying defects	debug-bug	debug-bug
Debug performance	Measuring before optimizing, then confirming wins	debug-performance	debug-performance
Write tests	Adding behavior-focused tests that match project conventions	write-tests	write-tests
Upgrade deps	Auditing usage and changelogs before dependency bumps	upgrade-deps	upgrade-deps
Migrate framework	Running incremental migrations in dependency-safe batches	migrate-framework	migrate-framework
Dedup	Acting on tl dupes — triage, consolidate the second home, ratchet it shut	dedup	dedup

Install the variant for your agent:

# Copy all workflows
cp -r node_modules/tokenlean/skills/claude/*~/.claude/skills/
cp -r node_modules/tokenlean/skills/codex/*~/.codex/skills/
# Or copy one workflow
cp -r node_modules/tokenlean/skills/claude/code-review ~/.claude/skills/
cp -r node_modules/tokenlean/skills/codex/code-review ~/.codex/skills/

When working from a clone, replace node_modules/tokenlean with the local repo path.

Design Principles

1. Single purpose — one tool, one job
2. Minimal output — show what's needed, nothing more
3. Composable — every tool supports -j for JSON piping
4. Fast — no heavy parsing, no external services, aggressive caching
5. Multi-language — JS/TS first, expanding to Python, Go, Rust, Ruby

More

• All tools — complete tool reference with examples
• Workflows — task-oriented recipes (refactoring, PR review, releases, etc.)
• Language support — compatibility matrix across languages
• Configuration — .tokenleanrc.json schema and caching

Also by Exelerus

Project	Description
claude-rig	Run multiple Claude Code profiles side-by-side — isolate or share settings, plugins, MCPs per rig
agent-awareness	Modular awareness plugins for AI coding agents
claude-mneme	Persistent memory for Claude Code — context across sessions
claude-simple-status	Minimal statusline — model, context usage, quota at a glance
vexscan-claude-code	Security scanner for untrusted plugins, skills, MCPs, and hooks

Contributing

Contributions are welcome! See CONTRIBUTING.md for guidelines on adding tools, code style, and submitting PRs.

License

MIT © Edin Mujkanovic