Agent token usage skill

Skill DLYZZT/agent-token-usage-skill

Claude Code skill that reports local token usage (no API key, no network) for Codex, Claude Code, Pi, Grok, opencode, and openclaw sessions

Install

npx -y skills add DLYZZT/agent-token-usage-skill

Assembled from the repository path, not quoted from the project. Check it against their README if it does not work.

2 things to look at

no licenseNo license file was found in the repository. Code published without one is not open source by default, so using it at work is a question for whoever answers licensing questions where you are.
0 stars0 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.

What its author says it does

Copied from the file, not written here

Reports local token usage for coding-agent sessions (Codex, Claude Code, Pi, Grok, opencode, openclaw) by running the agent-token-usage CLI against the user's on-disk session logs — no network calls, no API keys. Use whenever the user asks how many tokens they've used, wants a usage/cost breakdown, or wants to check today's/this week's/a specific session's token consumption for any of these coding agents.

SKILL.md

4.1 KB, as published. Nobody here has run it

agent-token-usage — token usage skill

This skill answers questions about how many tokens a coding-agent CLI (Codex, Claude Code, Pi, Grok, opencode, openclaw) has used, by running the agent-token-usage binary against session logs already on the user's disk. It never calls out to any API and needs no credentials.

Setup (run once per machine)

Check whether the CLI is already installed:

command -v agent-token-usage || command -v atu

If neither is found, install it (macOS/Linux only):

curl -fsSL https://raw.githubusercontent.com/DLYZZT/agent-token-usage/main/install.sh | bash

This installs the binary to ~/.local/bin/agent-token-usage and symlinks ~/.local/bin/atu as a short alias. If atu --help still isn't found afterward, ~/.local/bin is likely not on PATH — either add it, or call the binary directly via ~/.local/bin/atu.

The installer is a bash script and only supports macOS and Linux. On Windows, tell the user to download the matching .exe asset manually from https://github.com/DLYZZT/agent-token-usage/releases/latest — do not attempt to run the curl script there.

Command shape

atu [OPTIONS] [PATHS...]

(atu and agent-token-usage are the same binary.) Default behavior with no flags: summary of the latest Codex session only.

Map the user's question to flags:

Which tool → --source <codex|claude|pi|grok|opencode|openclaw|all> (default codex)
Scope:
- most recent session only → default, or explicit --latest
- "all sessions" / "total" / "this week/month" → --all, combined with --since YYYY-MM-DD / --until YYYY-MM-DD for a date range
Granularity (only meaningful with --all):
- per-session breakdown → --by-session
- per-model-call breakdown → --calls
- omit both for one aggregated total
Machine-readable output (for you to parse/compute with, not to paste raw at the user) → --json or --csv
--limit N caps detail rows (0 = unlimited, default 20); --sort time|tokens orders them

Example mappings

User asks	Command
"我最近一次 Codex 会话用了多少 token"	`atu`
"Claude Code 最近一次会话用了多少"	`atu --source claude`
"这周 Claude Code 一共用了多少 token"	`atu --source claude --all --since <this Monday's date>`
"所有工具加起来一共用了多少"	`atu --source all --all`
"按会话列一下 opencode 的用量"	`atu --source opencode --all --by-session`
"看下每次模型调用的明细"	`atu --source <x> --all --calls`

When you need exact numbers to do further math or comparisons, add --json, parse it, then summarize in prose — don't dump raw JSON/CSV at the user unless they asked for exportable data.

Reading the output

Summary/detail columns:

Sessions / Calls — number of sessions / model calls counted
Input — input tokens (includes cached-hit portion)
Cached — the subset of Input that was a cache hit
Uncached — Input minus Cached
Output — output tokens
Reason — reasoning tokens (only present for models that report them)
Total — sum of tokens for the row

Prefer a short human summary ("your last Claude Code session used ~X input + Y output, ~Z tokens total") over pasting the raw table, unless the user explicitly asked for the full table/export.

Boundaries

The CLI only reads local session log files for whichever --source you pick; it never writes to them. If that tool has never run on this machine, the expected log directory may not exist and the command can error or return nothing — report that honestly rather than guessing a number.
Never modify the user's session log files.