Pocket-TokenScope docs

Getting started

Pocket-TokenScope shows how many tokens your AI coding tools use, roughly what that costs, and where the tokens go. It works from the usage logs that Claude Code and Codex already keep on your Mac, so there is nothing to connect and nothing to sign in to.

Requirements

• A Mac with Apple Silicon or an Intel processor, running macOS 13 Ventura or later.
• Claude Code, Codex, or both, used on the same Mac and under the same macOS account. Pocket-TokenScope reads their logs from the default locations: ~/.claude/projects for Claude Code and ~/.codex/sessions for Codex.
• Optional: knowledge-graph builds made with graphify inside your Documents folder, if you want to see what they cost. See Usage, Savings, Models, and Sources.

Getting the app

Pocket-TokenScope isn't available to download yet. Version 1.0 is built and awaiting distribution. Email us and we'll tell you when you can get it.

Your first scan

1. Open Pocket-TokenScope. It opens on the Overview and starts reading your logs straight away. A progress panel shows Scanning Claude logs…, then Scanning Codex sessions…, then Aggregating….
2. When the panel closes, your dashboard is ready. The first scan reads every log file, so it takes longer than later ones.
3. Around the same time, macOS may ask whether Pocket-TokenScope can access files in your Documents folder. Choose Allow to include knowledge-graph build costs. If you don't allow it, everything else still works; only the build-cost list stays empty.

Finding your way around

The sidebar on the left lists the app's screens: Overview, Usage, Savings, Sources, Models, Alerts, Reports, and Settings. Click one to switch to it. Alerts and Reports aren't available in version 1.0; they show a Coming soon message.

Large numbers are shortened throughout: K for thousands, M for millions, and B for billions. The tables on Models and Sources show full numbers.

The Overview

The Overview is the main dashboard. Across the top are the date button and the Export Report button. Below them are four summary cards, two charts, and two lists.

Choose a date range

1. Click the date button at the top right of the Overview. It shows the dates you're looking at, such as Aug 28 – Sep 26, 2026.
2. Choose Last 7 days, Last 30 days, Last 90 days, Last 12 months, or All time.

Every range ends today and includes today. The app opens on Last 30 days. Days follow your Mac's time zone.

The range applies to the four summary cards, the Token Usage Over Time and Savings Over Time charts, and exported reports. Tokens by Model and Top Token Sources always cover your whole history.

Summary cards

Each card has a small trend line for the range and a change figure, such as 12.5% vs prior period, that compares the range with the period of the same length just before it. Green with an up arrow means higher; red with a down arrow means lower. The card shows a dash instead when the range is All time or there is nothing to compare against.

Token Usage Over Time

A stacked bar chart of your tokens, split into four kinds:

• Input — tokens Claude Code sent to the model, not counting cached input.
• Output — tokens the model wrote back.
• Cache — cached input, reads and writes combined.
• Codex — all Codex tokens, as a single figure.

Use the menu at the top right of the card to switch between Daily, Weekly, and Monthly bars. Weeks follow your Mac's calendar settings.

Savings Over Time

Two running totals in dollars across the range. Actual, the solid line, is the estimated cost of the tokens you used. Potential (w/o optimizations), the dashed line, is what it would have cost without graph lookups. The gap between them is the estimated saving, shown in the Total Savings box on the chart. This chart has its own Daily, Weekly, and Monthly menu.

The savings estimate is spread across the range in proportion to each period's requests, so busier days carry more of it.

Tokens by Model and Top Token Sources

Tokens by Model is a donut chart of your five largest models, with any others grouped as Other. The center shows your total tokens, and the legend gives each model's tokens and share.

Top Token Sources lists your five largest Claude Code projects by tokens, with each project's share of all project tokens.

For the full lists, choose Models or Sources in the sidebar. The View all labels on these two cards aren't links in version 1.0.

Usage, Savings, Models, and Sources

These four screens always cover your whole history. The date range on the Overview doesn't apply to them.

Usage

Usage shows Token Usage Over Time across all your history, with its own Daily, Weekly, and Monthly menu, and the Tokens by Model donut.

Savings

Savings shows Savings Over Time across all your history and the Savings Estimator, with its four sliders and the resulting Estimated tokens saved. These are the same sliders as on Settings, so a change in either place applies to both. How they work is covered in Cost and savings settings.

Models

Models shows the Tokens by Model donut and an All Models table that lists every model, largest first, with its Tokens and its share in the % column.

• Claude Code models appear under the names in your logs, such as claude-opus-4-8 or claude-sonnet-5. A response with no model name is counted as unknown.
• Codex sessions appear as Codex · followed by the model, such as Codex · gpt-5.5, so you can tell them apart from Claude Code. A session with no model name appears as Codex · codex.

Sources

Sources has two cards.

• Top Token Sources lists up to 20 of your Claude Code projects, largest first, with each one's tokens and share. Codex sessions aren't tied to a project, so they don't appear here.
• Graphify Build Cost lists the knowledge-graph builds Pocket-TokenScope found, one row per project, with the Input and Output tokens each build used. The combined total appears at the top right of the card.

How build costs are found

After your Claude Code and Codex figures appear, Pocket-TokenScope searches your Documents folder for files named cost.json inside folders named graphify-out. Each one it finds becomes a row, named after the folder that contains graphify-out. The search skips hidden folders and common dependency and build folders, such as node_modules, build, and DerivedData.

Build costs are shown in tokens and listed separately; they aren't added to your usage totals or charts. Only builds that used an AI model record a cost. Code-only builds are free.

Cost and savings settings

The Settings screen holds the cost model behind every dollar figure in the app: the Blended Cost Rate and the Savings Estimator. Changes take effect right away, everywhere in the app.

Blended Cost Rate

Drag the Rate slider to set what one million tokens costs you. The current value appears beside it — $1.50 per 1M tokens by default. The slider runs from $0.10 to $20.00, in steps of $0.05.

The same rate applies to every token — input, output, cache, and Codex — and to every model. It drives Est. Cost, Total Savings, the Savings Over Time charts, and the dollar figures in exported reports. It isn't per-model billing, so treat the results as a guide rather than a bill.

Claude Code use tends to be heavy on cached input, which is billed well below the price of fresh input, so a realistic blended rate sits well below a model's list input price. To tune it, divide what you paid for a month by that month's Total Tokens Used, counted in millions.

Savings Estimator

No log records which answers came from a knowledge graph instead of from reading files, so savings can't be measured. Pocket-TokenScope estimates them from four assumptions that you set with sliders:

The estimate is Queries answered via graph × (Files per query × Tokens per file − Graph answer tokens), and never less than zero. With the defaults, that is 200 × (18 × 1,600 − 1,200) = 5,520,000 tokens, shown as 5.5M saved. At the default rate, that is worth $8.28.

The same four sliders appear on the Savings screen, which also carries this reminder: Estimate only — Claude Code does not tag which tokens came from a graph-assisted lookup.

Exporting a report

You can save the figures behind the Overview as a CSV file that opens in Excel, Numbers, or any other spreadsheet app.

1. On the Overview, choose the date range you want.
2. On the Token Usage Over Time card, choose Daily, Weekly, or Monthly. The report uses the same grouping.
3. Click Export Report. The button briefly changes to Saved, and Finder opens with the file selected.

The report is saved as Pocket-TokenScope-Report.csv in your Downloads folder.

What's in the report

The first line reads Pocket-TokenScope Report. A summary follows:

Below the summary is a table with the columns Date, Input, Output, Cache, Codex, Total, and Requests, with one row per day, week, or month. Dates are written as year-month-day; for weeks and months, the date is the first day of the period. Periods with no activity have no row.

Reports don't include per-model or per-project figures. The dollar figures use your settings at the moment you export.

Privacy and your data

Pocket-TokenScope works entirely on your Mac. It never connects to the internet, has no account or sign-in, and sends nothing anywhere. The name at the bottom of the sidebar is your Mac account's name, labeled Local, and is there for display only.

What it reads

Your logs contain your conversations, but Pocket-TokenScope uses them only to count usage. It doesn't display or keep their text, and it never changes or deletes your logs.

What it saves

• A scan cache at ~/Library/Application Support/Pocket-TokenScope/scan-cache.json. For each log file, it holds the file's location, size, and last-modified time, plus the figures counted from it: dates, token and request counts, model names, and the project name. This is how later scans skip files that haven't changed. Entries for logs that no longer exist are dropped at the next scan.
• Exported reports, only when you click Export Report, saved to your Downloads folder.

Your settings aren't saved anywhere.

Documents folder access

Pocket-TokenScope asks for access to your Documents folder only to look for knowledge-graph build costs. To change your answer later, open System Settings, choose Privacy & Security, then Files & Folders, and turn the Documents Folder switch under Pocket-TokenScope on or off.

Removing Pocket-TokenScope and its data

1. Quit Pocket-TokenScope.
2. Move the app to the Trash.
3. Delete the folder ~/Library/Application Support/Pocket-TokenScope.
4. Delete any exported Pocket-TokenScope-Report.csv files you no longer want.

Your Claude Code and Codex logs are untouched. You can also delete just the scan cache at any time; the next scan rebuilds it and takes longer while it does.

Troubleshooting and FAQ

The charts say "No data in range"

There's no activity in the date range you chose. Try a longer range, such as All time. If everything is empty, check that you've used Claude Code or Codex on this Mac under your own macOS account, and that its logs are in ~/.claude/projects or ~/.codex/sessions. If you've set Claude Code or Codex to keep its data somewhere else, Pocket-TokenScope won't find it.

Today's work is missing

Pocket-TokenScope reads your logs when it opens and doesn't watch for new activity. Quit it with ⌘Q and open it again to pick up the latest. Only new or changed log files are read, so this is quick.

All time starts later than I expected

Pocket-TokenScope can only count what is still in your logs. If Claude Code or Codex has removed older log files, that history no longer appears; the app doesn't keep figures for logs that are gone. It also counts only this Mac, so activity on other computers isn't included.

Graphify Build Cost says "No graphify build costs found"

• Pocket-TokenScope may not have access to your Documents folder. See Privacy and your data to turn it on.
• It only looks inside your Documents folder, so builds in projects kept elsewhere aren't found.
• It only reads cost.json files in folders named graphify-out. Build output kept anywhere else, including a hidden folder such as .graphify, isn't found.
• Code-only builds don't record a cost.

If you've just allowed access, give the search a moment to finish, or quit and reopen the app.

My settings went back to the defaults

In version 1.0, the blended rate and the savings assumptions aren't saved between launches. Set them again after you open the app.

Est. Cost doesn't match my bill

Est. Cost applies one rate to every token, whatever the model or kind of token, while your provider prices each model and kind of token separately. Adjust the rate on Settings to bring the estimate closer to what you pay. See Cost and savings settings.

Total Savings doesn't change when I change the date range

That's expected. Total Savings comes from the savings estimator, which has no dates. The Savings Over Time chart spreads that same estimate across whichever range you choose.

Some project names look different from my folder names

Project names come from the folder names Claude Code uses for its logs, tidied for display. Hyphens appear as spaces, and a project outside your Documents folder shows more of its path.

Why don't Codex tokens appear in Top Token Sources?

Codex sessions aren't tied to a project, so Top Token Sources lists Claude Code projects only. Codex tokens still count toward your totals, the charts, and Models.

Can I set budgets or alerts?

Not in version 1.0. The Alerts and Reports screens are placeholders that show Coming soon.

Is there a light appearance?

No. Pocket-TokenScope always uses a dark appearance, whatever your Mac is set to.

Does it update itself?

No. Pocket-TokenScope never connects to the internet, so it can't check for updates. When a newer version is available, replace the app with it.

Getting help

If something doesn't work the way these docs describe, email us. It helps to tell us your macOS version, which screen you were on, and what you expected to see. A screenshot is welcome; please don't send your log files, because they contain your conversations.

To hear when Pocket-TokenScope becomes available, ask to be notified.