Track token usage and API costs for your Claude Code sessions.

Tokenyst is a lightweight CLI tool that runs alongside Claude Code, automatically capturing token consumption and calculating spend against your budget. Perfect for indie developers, agents, and teams managing API costs.

Features

• Automatic tracking — Runs silently after each Claude Code session, capturing tokens and costs
• Budget management — Set per-task budgets and monitor spend in real-time
• Cost calculation — Built-in pricing for all Claude models, including prompt cache multipliers
• Local-first — All data stored in ~/.tokenyst/ on your machine (no cloud required)
• Session summaries — See token usage and budget progress at a glance

Installation

npm install -g tokenyst
# or
pnpm add -g tokenyst

You'll need Node.js 18+ and Claude Code already installed.

Quick Start

1. Define a task and set a budget:

tkst -t "Issue-243" -b 5
# Create a budget of $5.00 for "Issue-243"  

All future session costs will be automatically allocated to your active task.

2. Initialize and start tracking:

tkst claude
# or
claude

This spawns Claude Code with budget tracking enabled. After each prompt, the prompt's cost is displayed along with the budget progress. After your session ends, a cost summary is displayed.

💡 Note: Running claude on its own will still enable budget tracking. However, the post-prompt and post-session summaries will not show.

3. Check your progress:

tkst -t
# ┌─────────┬────────────────────────────────┐
# │ Task    │ Issue-243                      │
# ├─────────┼────────────────────────────────┤
# │ Budget  │ $3.24 / $5.00 ▓▓▓▓▓▓▓▓░░░░ 65% │
# └─────────┴────────────────────────────────┘

Use tkst -l to see all tasks, their budgets, spend, and remaining balance.

Example Usage

Live budget updates:

tkst -t "Fix header buttons" -b 2
#  Created task "Fix header buttons" with budget $2.00

tkst claude
# [Claude Code prompt]
# ⎿  Stop says: +$0.861 (turn) | Budget: $0.86 / $2.00 (43%)

# [Claude Code prompt]
# ⎿  Stop says: +$0.344 (turn) | Budget: $1.21 / $2.00 (60%)

/exit
#  Budget Summary:
# ┌─────────┬────────────────────────────────┐
# │ Task    │ Fix header buttons             │
# ├─────────┼────────────────────────────────┤
# │ Budget  │ $1.21 / $2.00 ▓▓▓▓▓▓▓░░░░░ 60% │
# ├─────────┼────────────────────────────────┤
# │ Session │ $1.21                          │
# └─────────┴────────────────────────────────┘

Initializing Claude Code with tkst will provide post-prompt and post-session summaries.

Set / Update / Delete a task:

# Change tasks
tkst -t "Add unit tests"

# Update budget to $3.00
tkst -u "Add unit tests" -b 3

# Delete a task
tkst -d "Fix header buttons"

View / Update / Reset allocations:

tkst -a
# View allocations for the current task

tkst -a --all
# View allocations for all tasks

tkst -ra "Add landing page" "Issue-243"
# Re-allocate from one task to another

tkst -a "Add landing page" --delete
# Delete an allocation from a task

tkst -r "Add Landing page"
# Delete all allocations from a task

All commands

tkst task (-t) -n <name> -b <amount>
# ⎿ Create a task with a budget cap

tkst claude (-c)
# ⎿ Run Claude Code with budget tracking

tkst list (-l)
# ⎿ List all tasks

tkst delete (-d) <name> [--yes] [--all]
# ⎿ Delete a task and its history

tkst update (-u) <name> [-b <amount>] [-n <new_name>] [-a <add_amount>]
# ⎿ Change budget cap, rename, and/or manually add an allocation

tkst allocations (-a) [<task>] [--all] [--delete]
# ⎿ View or delete allocations

tkst reallocate (-ra) <from> <to>
# ⎿ Move an allocation between tasks

tkst reset (-r) <name> [--yes]
# ⎿ Wipe spending history for a task

tkst --enable
# ⎿ Re-enable tracking and stop hook

tkst --disable
# ⎿ Disable tracking and remove stop hook                        

How It Works

1. You run tkst claude to start a Claude Code session
2. Tokenyst spawns Claude with inherited stdio, letting you work normally
3. When you exit Claude, Tokenyst automatically:
   • Finds your session transcript in ~/.claude/projects/
   • Parses token usage from the last assistant turn(s)
   • Calculates cost using the current Claude model pricing
   • Deducts the cost from your active task budget
   • Shows a summary with remaining balance
4. All data is saved locally in ~/.tokenyst/config.json

Configuration

Your data lives here:

• ~/.tokenyst/config.json — All tasks, budgets, and spend allocations
• ~/.tokenyst/recorded-turns.json — Internal dedup tracking (you can ignore this)
• ~/.tokenyst/hook.log — Debug logs from the Stop hook integration

Requirements

• Node.js 18.0.0 or later
• Claude Code (via claude command in your PATH)
• pnpm, npm, or yarn (for installation)