Guide · Agent skill
How to use the Claude Code Cost Tracking agent skill
Updated · written with AI from the project's own documentation and checked against our catalogue data
The cost-tracking skill lets Claude Code answer questions about your own spending: how much you have used today, which projects, tools, sessions or dates account for the most cost, and what a CSV-style export of recent usage looks like. It reads a local SQLite database that a separate cost-tracking hook or plugin has already filled in, so it only helps if you already have that tracker running. After this guide you will know what the skill does, how to install it, how to ask for reports in plain language, and what it needs and does on your machine.
Claude Code Cost Trackingaffaan-m/ECC · MIT Download the skill Quick start
- 1Check the prerequisites. Confirm that the sqlite3 command is available and that ~/.claude-cost-tracker/usage.db exists. If the database is missing, install or enable a cost-tracking hook or plugin first.
- 2Download and unzip the skill. Download the cost-tracking ZIP from this page and unzip it so that SKILL.md sits in a cost-tracking folder.
- 3Place the folder in the right location. Put the cost-tracking folder in ~/.claude/skills/ for personal use, or in a project's .claude/skills/ folder for one project.
- 4Or upload it in the Claude apps. In the Claude apps, go to Settings → Capabilities → Skills and upload the skill.
- 5Ask a natural question. Request something like "How much have I spent today compared with yesterday?" and the agent will decide whether to use the skill.
- 6Narrow the report. Ask for a specific project, session, tool or date range to keep the output focused and the query fast.
What is an agent skill, and what does this one do?
An agent skill is a folder containing a SKILL.md file that tells Claude Code when and how to perform a task. When a request matches the skill's description, Claude Code follows the instructions in that file.
The cost-tracking skill is written for questions about cost, spend, usage, tokens, budgets, or cost breakdowns by project, tool, session or date. Its instructions tell the agent to run read-only SQL queries with the sqlite3 command against ~/.claude-cost-tracker/usage.db, then summarise the results.
- Reports today's spend compared with yesterday.
- Shows total tracked spend across the database.
- Ranks top projects and top tools by cost.
- Lists the last 7 days of cost and call counts.
- Gives per-session cost, start and end times, and average cost per session when there is enough data.
- Produces CSV-style exports of recent usage records.
What you need before installing
The skill does not track costs itself. It expects a usage table in a SQLite database at ~/.claude-cost-tracker/usage.db, written by a separate cost-tracking hook or plugin that is not included in this skill. Without that database the skill will tell you tracking is not set up instead of inventing numbers.
You also need the sqlite3 command-line tool. The skill checks for it before running queries.
- The sqlite3 command-line tool.
- A local SQLite database at ~/.claude-cost-tracker/usage.db, created by a separate cost-tracking hook or plugin.
- Claude Code, or the Claude apps with Skills support.
command -v sqlite3 >/dev/null && echo "sqlite3 available" || echo "sqlite3 missing"
test -f ~/.claude-cost-tracker/usage.db && echo "Database found" || echo "Database not found"Install the cost-tracking skill
Download the cost-tracking ZIP from this page and unzip it. The package contains a single file, SKILL.md. Choose one of the following locations depending on how you want to use it.
For a personal install available in all your projects, place the cost-tracking folder inside ~/.claude/skills/. For a single project, place it inside that project's .claude/skills/ folder. In the Claude apps, you can instead upload the skill under Settings → Capabilities → Skills.
- Personal install: unzip into ~/.claude/skills/ so the folder is ~/.claude/skills/cost-tracking/.
- Project install: unzip into the project's .claude/skills/ folder.
- Claude apps: upload the skill under Settings → Capabilities → Skills.
Trigger the skill with natural requests
You do not need to type a command. Ask in ordinary language and the agent will decide whether the skill applies. The skill's guidance covers questions about spending, session cost, token usage, budgets and limits, per-project or per-tool breakdowns, comparing today with yesterday, recent trends, and CSV exports.
Be specific about the slice you want. Naming a project, session, or date range helps the agent choose the right query.
- "How much have I spent today compared with yesterday?"
- "Which projects cost the most this month?"
- "What did the session I ran this morning cost?"
- "Break down my spend by tool."
- "Export my last 50 usage records as CSV."
Example queries the skill runs
The skill ships with example queries. Each one is a read-only SELECT against the usage table. You can run them yourself to check the output or to see what the agent is doing.
The usage table is assumed to have these columns, although column names depend on your tracker: timestamp, project, tool_name, input_tokens, output_tokens, cost_usd, session_id and model. The skill prefers the cost_usd value your tracker already calculated over estimating cost from token counts.
- Quick summary: today's cost, total cost, number of calls and number of sessions.
- Cost by project, ordered from highest to lowest.
- Cost by tool, ordered from highest to lowest.
- Last 7 days, grouped by date.
- Session detail: start, end, cost and calls for the 10 most recent sessions.
sqlite3 -header -column ~/.claude-cost-tracker/usage.db "
SELECT project, ROUND(SUM(cost_usd), 4) AS cost, COUNT(*) AS calls
FROM usage
GROUP BY project
ORDER BY cost DESC;
"Safety notes: scripts and network
The skill runs scripts: it executes sqlite3 commands on your machine. It does not use the network, according to the skill's documentation. Its queries are read-only SELECT statements.
The skill's own guidance warns against unrestricted SELECT * exports on large databases, because they can be slow. It also says not to install unreviewed hooks or plugins that run arbitrary code, so check any tracker you install before you rely on it.
- Runs sqlite3 commands locally against your database.
- Does not use the network.
- Avoid asking for unlimited full-table exports on a large database.
- Review the cost-tracking hook or plugin you use to fill the database.
Tips for useful cost reports
Treat the numbers as the tracker's view of your spend. The skill relies on cost_usd values written by a third-party tracker, which may not match Anthropic's bills. The skill also says not to hardcode current model prices in its answers, because prices change over time.
For a clear report, ask for today compared with yesterday, the top projects, the top tools, and session averages together. Small amounts are shown to four decimal places and larger ones to two, according to the skill's formatting guidance.
- Use it for spending summaries and breakdowns, not invoice reconciliation.
- Ask for a time range or project name to keep results small.
- If the agent says the database is missing, set up your cost tracker first.
What people use it for
- Checking how much today's Claude Code work has cost compared with yesterday.
- Comparing spend across several projects when managing a budget.
- Finding which sessions or tools account for the highest costs.
- Exporting recent usage records as CSV for your own spreadsheet analysis.
Frequently asked questions
Is the cost-tracking skill free to use?
The skill is published under the MIT licence, as stated on this page. It runs locally and does not use the network, but it still needs a cost-tracking hook or plugin that writes to ~/.claude-cost-tracker/usage.db.
What do I need to install before using this skill?
You need the sqlite3 command-line tool and a local SQLite database at ~/.claude-cost-tracker/usage.db. That database must be created by a separate cost-tracking hook or plugin, which is not included in the skill.
Where do I put the cost-tracking skill folder?
Unzip it into ~/.claude/skills/ for a personal install, or into a project's .claude/skills/ folder for one project. In the Claude apps you can upload it under Settings → Capabilities → Skills.
Why does the skill say the database is not found?
The skill only reads data and does not create it. If ~/.claude-cost-tracker/usage.db is missing, no cost tracking has been set up, so you need to install or enable a cost-tracking hook or plugin that writes to that file.
Does this skill match my Anthropic bill?
Not necessarily. It relies on the cost_usd values written by a third-party tracker, which may differ from Anthropic's invoices. Use it for spending summaries, not official billing reconciliation.
Can it track costs for me without another tool?
No. The skill reads an existing database and cannot record usage on its own. It is designed for people who already run a Claude Code cost-tracking hook or plugin.
New agent skills, repos and AI tools — every week
The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.
Our verdict
This skill suits developers who already run a local Claude Code cost-tracking hook or plugin and want quick spending summaries by project, tool, session or date. It is not useful if you have no usage database, if you need official billing figures, or if you want an unreviewed tracker installed alongside it, so pick a different tool in those cases.
Download the skill