@marginfront/code-cost-clarity

See what your team spends on Claude Code and Codex: who spent it, on which model, and how much. It lands in MarginFront on its own while your team just codes.

You're watching your own team's AI spend here. Nobody gets charged, and nobody gets cut off unless you turn on spend caps.

Your Anthropic and OpenAI keys stay yours. This tool never reads, needs, or transmits them. The only credential it uses is your MarginFront key, and only to send usage to MarginFront.

What it keeps on your disk. The meter writes a local capture file of what your coding agents report. Claude Code puts your prompt, the model's reply, and each tool call's input on those same records, and a tool call's input can be the contents of a file the agent edited. A shell call goes one further: the command it ran arrives a second time, in the tool parameters. The meter deletes all of that before the file is written, so none of it is stored and none of it is sent. One record keeps its tool parameters: an MCP tool call. They are the only place the name of an MCP tool call appears, because Claude Code labels every one of them mcp_tool and puts the server and tool it really called in those parameters, so dropping them would turn every MCP tool on your bill into one unnamed line. Capture files written before version 0.16.0 still hold what they captured, and uninstall deletes them.

Beta (pilot software). Pin a version, expect rough edges, and report issues.

Runs on macOS, Windows, and Linux. Needs Node 18 or newer.

Install

First, get your MarginFront secret key (mf_sk_*). Sign in at app.marginfront.com and go to Build -> API keys -> "Create key pair". Direct link: https://app.marginfront.com/build?tab=keys

Then run this. It's the whole setup:

npx @marginfront/code-cost-clarity init

init downloads the collector it needs (~360 MB, one time), asks you to paste that secret key, and saves it to ~/.marginfront-ccc/.env, a file only you can read. Then it shows you every change it wants to make and asks before making any of them. Answer n and nothing outside ~/.marginfront-ccc is touched.

When it finishes, quit and reopen Claude Code and Codex, and start a fresh terminal. They read the new settings at launch, so anything already open won't report a thing until you reopen it.

Then just code:

claude          # or: codex, or the desktop apps

Your spend shows up in MarginFront under your teammate email.

On macOS and Windows a background meter does the work, so there's no terminal to keep open. Windows needs no WSL. The meter starts when you sign in and runs with no window, so after sign-in nothing appears on your screen and there is nothing to close. stop pauses it and start brings it back. Run status once after your first sign-in to see it working. On both macOS and Windows the meter writes what it has to say about itself to ~/.marginfront-ccc/forwarder.out.log and forwarder.err.log, and status shows you the last lines of each under "Recent output" and "Recent errors".

On Linux there's no background meter. Keep npx @marginfront/code-cost-clarity run open in a terminal while you work. Usage that happens while it's closed is lost, not buffered.

Check on it anytime:

npx @marginfront/code-cost-clarity status

If your coding agent runs inside WSL

Windows itself doesn't need WSL. This is only for people whose Claude Code or Codex already lives inside a distro. Install and run this in that same distro, because that's where those agents send telemetry and where the collector's localhost is.

You need a general-purpose distro (wsl --install -d Ubuntu). Docker Desktop's docker-desktop distro is an appliance for running Docker, and this tool doesn't work inside it, even though wsl -l -v lists it and makes WSL look ready. There's no background meter in WSL either, so keep run open. Full steps: https://docs.marginfront.com/tools/code-cost-clarity-windows

Use npx, not npm install. This is a CLI tool, and installing it into a project pulls in dependencies you don't want. The npm i box on npmjs.com is npm's default for every package. Ignore it here.

The commands

Each one runs as npx @marginfront/code-cost-clarity <command>.

| Command | What it does | | ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | init | The one setup command. It checks your pasted key with MarginFront before saving it. Safe to re-run: it never re-asks for a saved key that still works and never clobbers a setting you changed. | | status | Are you set up and is it capturing? Key, Meter, Claude Code and Codex lines, then your work item and whether finished-work counting is on. A Queue line appears whenever turns or finished things are parked waiting to send. Recent activity and errors follow. | | run | Streams your live spend in this terminal instead of the background meter. Ctrl-C stops it. | | start | Resumes the background meter after stop. init already starts it for you. | | stop | Pauses the meter, both the background one and any foreground run, until start or your next sign-in. On Windows this can lose the last moments of usage, because the collector there has to be forced down rather than asked. | | work ["<name>"] | Puts this machine's spend on a piece of work. No name prints the one in effect; --clear removes it. Nothing to restart. | | done "<name>" [n] | Counts something you finished, so ROI in your dashboard's left menu can show what one cost on its Finished work tab. It costs nothing on its own. --setup turns finished-work counting on or off. | | preview <capture.json> | Prints the exact record it would send for one captured snapshot. Needs no key, so it's a safe dry run. | | uninstall | Undoes every change init made and reclaims the ~360 MB. Keeps your saved key. | | help, version | What you'd expect. |

run prints a line per turn, so you can watch it land:

[14:22:07] recorded [email protected] · in=3210 out=287 · server=$0.0232 · cc=$0.0236 event=9f0c2a71-...

Options

| Option | Where | What it does | | -------------- | ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | --control | init | Also turn on spend caps. See below. | | --no-prompt | init | Skip every question, for CI and scripts. It still wires your config, and it prints the same list of changes. Paste your key into ~/.marginfront-ccc/.env separately. | | --fold-cache | run, preview | Round-up mode for a model MarginFront can't price yet. The default is more accurate, so reach for this only when a model has no cache price. | | --agent | done | Which assistant this finished thing rolls up under: claude-code or codex. Needed only when both are installed and the meter has not seen either working yet. | | --clear | work | Removes the work item from this machine. | | --setup | done | Asks the two finished-work questions again, so you can turn counting on or off later. | | --purge | uninstall | Also delete your saved settings and MarginFront key. | | CCC_IGNORE_REPOS | ~/.marginfront-ccc/.env | A setting, not a flag: the repos this machine never sends spend from, comma-separated owner/repo. See below. |

Label this machine's spend with a work item

By default the meter can tell you what this machine spent. It can't tell you which job the money went to. One line in ~/.marginfront-ccc/.env fixes that:

CCC_WORK_ID=LOWAI-677

A work item is whatever you bill AI work against: a project, a ticket, a client engagement. Pick a short name for it, a ticket number or plain words. Every record this machine sends from then on carries that name, tokens and tool calls, Claude Code and Codex alike, and MarginFront adds up what each one cost.

One thing to get right: use the same spelling every time, capital letters included. lowai-677 and LOWAI-677 are two different things here, and they add up as two separate jobs.

This line is about spend. Counting what you finish is a separate switch, off until you turn it on, and the next section covers it.

There's nothing to restart. Change the line, save the file, and the meter picks up the new name on the next usage it sends. No stop, no start. Blank the line out, or delete it, and this machine is metered exactly as it was before.

You don't have to open the file at all. These do the same thing:

npx @marginfront/code-cost-clarity work "LOWAI-677"   # set it
npx @marginfront/code-cost-clarity work               # see what's in effect
npx @marginfront/code-cost-clarity work --clear       # remove it

status reads the line back to you, so you can check it without opening the file.

CCC_WORK_ID needs version 0.18.0 or newer. Older installs keep working: CCC_MATTER_ID was the older name for this line, and a machine still on it reports exactly as it does today. To get the newer name on this machine, update it:

npx @marginfront/code-cost-clarity@latest init

Your settings file is kept as it is, so CCC_MATTER_ID stays where you put it and keeps working. If both lines carry a value, CCC_WORK_ID is the one used.

Keep a repo off the meter

Some repos you will never report on: a customer's checkout you've agreed to keep out of your own reporting, a personal project on a work laptop. Until now the answers were to meter it anyway or turn the meter off, and turning it off loses the rest of the machine with it. One line in ~/.marginfront-ccc/.env names the repos this machine never sends from:

CCC_IGNORE_REPOS=acme-corp/billing,acme-corp/website

Write each one as owner/repo, spelled the way the repo's remote spells it, separated by commas. Capital letters make no difference here: Acme-Corp/Billing and acme-corp/billing are the same repo to the meter.

A session in a named repo produces nothing at all. No record is built, nothing is posted, and nothing sits in the outbox waiting to go out later. Every other repo on this machine keeps being metered exactly as it was.

That covers what you type by hand too. Run npx @marginfront/code-cost-clarity done "<name>" inside a named repo and it counts nothing, sends nothing, and tells you which line stopped it. And if records from that repo were already waiting in the outbox from an earlier outage, naming the repo drops them instead of sending them.

A session the meter can't place in a repo is still sent. That one is deliberate. The meter comes up empty-handed for plenty of ordinary reasons: a folder outside any repo, a checkout with no remote, a git that won't answer. Holding all of those back would quietly stop metering a whole machine, and the first sign you'd get is a spend number drifting to zero with nothing to explain it. A session is held back only when the meter can name the repo it matched.

There's nothing to restart. Add a repo, save the file, and the next record obeys the new line. No stop, no start. Blank the line out and this machine is metered exactly as it was before.

status reads the rule back to you, so you can check it without opening the file. It also names any entry that isn't owner/repo, because an entry like that is ignoring nothing and looks no different in the file from one that works. It flags an entry that looks like a pasted web address the same way, like github.com/acme-corp/billing, because that one sits in the list looking right and matches nothing at all.

CCC_IGNORE_REPOS needs version 0.19.0 or newer. On an older install the line sits there doing nothing. To get it:

npx @marginfront/code-cost-clarity@latest init

init writes the line blank into a settings file it creates. It never rewrites a settings file you already have, so on an existing install you add the line yourself.

Count what you finish

Counting spend needs nothing from you and never will. This is the other half: what your team actually finished, so you can see what one of those cost in AI.

Two commands:

npx @marginfront/code-cost-clarity work "Q3 pricing model"
npx @marginfront/code-cost-clarity done "paper reviewed"

work says what you're working on now. done says you finished one of the things you named. Add a number to count several at once: done "paper reviewed" 3.

On your MarginFront dashboard, open ROI in the left menu (ask whoever owns your MarginFront account if you don't see it), then the Finished work tab, to see each one with its AI cost beside it.

A finished thing costs nothing on its own. MarginFront prices it at zero, so recording one can never move your spend number. What shows up beside it is the AI cost attributed to it: what the same developer's AI spent on the same work item across those dates, split by count across the things they finished on it. The tab says so itself, and the data behind it (/api/roi/report) stamps every number with where it came from, measured, attributed, or your own estimate, so an attributed cost is never quoted as a measured one.

Turning it on

init asks once, at the end, and on a machine that is not counting yet the answer defaults to no:

Want to count finished work too, not only spend? (y/N)

On a machine that already counts finished work, the question shows your names and defaults to yes, so pressing Enter on an upgrade keeps it on. Typing n still turns it off.

Say yes and it asks what you finish, a few words each, comma-separated. It saves those names and adds a short note to your coding assistant's memory file, ~/.claude/CLAUDE.md for Claude Code and ~/.codex/AGENTS.md for Codex, telling it to run the two commands as it works. uninstall takes that note back out, byte for byte.

Changed your mind, either direction:

npx @marginfront/code-cost-clarity done --setup

status tells you which mode this machine is in.

What to know before you type it

• Who it lands under is the developer the meter already uses: CCC_DEVELOPER_EMAIL from your settings file. If that line is blank, done records nothing and tells you to run init, rather than putting the count under a name your spend never lands under.
• Which assistant it rolls up under is the installed one. With both installed it's whichever the meter last saw working, and on a machine that has seen neither work yet, done asks you to say which with --agent claude-code or --agent codex. On a machine with both, each assistant's own note already carries its own flag, so the assistant never meets that question.
• Offline it waits. It goes into the same outbox your turns use, and the meter sends it the next time it's running. On Linux and WSL that means the next time you run npx @marginfront/code-cost-clarity run. status shows the queue.
• Reuse the same name. The page groups by name and ignores capitals, so Paper reviewed and paper reviewed are one row on it.
• Needs version 0.18.0 or newer. Update with npx @marginfront/code-cost-clarity@latest init.

Spend caps (optional)

By default this only watches. Add --control and it can also stop a Claude Code or Codex tool call when the cap your admin set is reached:

npx @marginfront/code-cost-clarity init --control

It installs one small check that Claude Code and Codex run before every tool call. This gets its own consent question, on its own screen, because it's the one that turns a meter that watches you into one that can stop you.

This is a guardrail, not a hard limit. It stops TOOL CALLS, not tokens, so a prompt that's already running is already billed. It never sees hosted tools, meaning work a provider runs on its own servers like a provider-side web search. It can't stop charges at Anthropic or OpenAI, and it can't do anything about a machine that never installed it. For a hard ceiling, set a spend limit in your Anthropic Console or OpenAI account.

Codex needs one more step: run /hooks once inside codex and trust the MarginFront cap check. Until you do, Codex spend is metered but its tool calls aren't paused. status tells you where each tool stands.

uninstall removes the hooks, the Codex entry, and the script completely.

Everything a cap does and doesn't cover: https://docs.marginfront.com/tools/code-cost-clarity#spend-control-opt-in-caps

What init changes

The consent screen points here. This is the whole list, and uninstall reverses every line of it.

1. ~/.claude/settings.json gets these eight settings added to its "env" block, and nothing else, and only if Claude Code is on the machine (a Codex-only machine gets no Claude file and is never asked how it signs in to Claude):

   CLAUDE_CODE_ENABLE_TELEMETRY=1
   OTEL_METRICS_EXPORTER=otlp
   OTEL_LOGS_EXPORTER=otlp
   OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf
   OTEL_EXPORTER_OTLP_ENDPOINT=http://127.0.0.1:4318
   OTEL_METRIC_EXPORT_INTERVAL=300000
   OTEL_LOGS_EXPORT_INTERVAL=300000
   OTEL_LOG_TOOL_DETAILS=1

   That switches usage reporting on for EVERY claude session on this machine, the command line and the desktop app both. One exception, and only if you set it up: a repo named in CCC_IGNORE_REPOS sends nothing, which is what "Keep a repo off the meter" above is about. Your MarginFront key is never written here. It stays in ~/.marginfront-ccc/.env.

2. ~/.codex/config.toml gets one small [otel] block, and only if Codex is on the machine. If you already have your own [otel] settings, init leaves the file alone and prints the block for you to paste.

3. A background helper so the meter runs on its own, set to start when you sign in. A LaunchAgent on macOS, a Task Scheduler logon task named ai.marginfront.ccc on Windows that runs the meter with no window. On Linux and WSL there's nothing to install it into, and init says so and tells you to use run instead.

4. With --control only: a cap-check script in ~/.marginfront-ccc/control/, a pre-tool-call hook in ~/.claude/settings.json if Claude Code is here, and a matching Codex entry if Codex is here. Claude Code and Codex run that same one file, so you can open it and read it.

5. Only if you say yes to counting finished work: one short note, fenced between two comment lines, in ~/.claude/CLAUDE.md if Claude Code is here and ~/.codex/AGENTS.md if Codex is here. It tells your assistant to run work and done as it goes, and nothing else in those files is touched. The question is the last one init asks, it defaults to no until you turn it on, and --no-prompt never sees it.

If neither Claude Code nor Codex is on the machine, init still saves your key and installs the background helper, touches no coding-agent file, and tells you to run it again after you install one.

What each of those does, and exactly what leaves your machine: https://docs.marginfront.com/tools/code-cost-clarity

Learn more

The docs site has the rest: https://docs.marginfront.com/tools/code-cost-clarity

• How it works, and what it captures
• Per-teammate attribution, and teams sharing one login
• Cache pricing, and which cache-write rate you pay
• Codex: how its numbers are counted, and when your email shows up
• Billable tool calls, and how the catalog prices them
• Privacy: what leaves your machine, and what it doesn't
• Troubleshooting
• Security
• For developers: the input shapes and the ingest contract

Windows setup, start to finish: https://docs.marginfront.com/tools/code-cost-clarity-windows