Skip to main content

​
Code Cost Clarity on Windows

Code Cost Clarity runs on Windows. You install it from PowerShell, it meters your Claude Code and Codex spend in the background, and it starts itself again every time you sign in. You don’t need WSL. Setup is the same single command as macOS. This page covers what’s different about Windows: what to install first, what the background meter is, where your key lives, and the limits worth knowing before you start.

​
What you need first

Windows 11 or Windows 10. Node.js. Check it in PowerShell:
A version number means you’re set. “not recognized” means you need Node.js from nodejs.org first. Your MarginFront secret key. Log in at app.marginfront.com, go to Build → API keys, and copy the secret key (mf_sk_...). init asks you to paste it. A publishable key (mf_pk_...) is rejected.

​
Setup

One command, in PowerShell:
It asks for your secret key, wires telemetry into Claude Code and Codex, downloads the collector (about 360 MB, one time), and registers the background meter that starts at every sign-in. Then just code:
or:
That’s it. There’s no second terminal to keep open and nothing to start by hand. Your spend shows up in MarginFront under your developer email.
Already running Claude or Codex? Quit and reopen them after init, and open a fresh PowerShell window. Each session reads the telemetry config when it starts, so anything already open won’t report until you reopen it.
Use npx, not npm install. This is a command-line tool, not a library. The @latest skips a stale npx cache.
Check the meter anytime:

​
The background meter

init registers the meter with Windows Task Scheduler as a logon task under your own account. It starts when you sign in, and it starts again on its own if it ever stops unexpectedly. It needs no administrator rights, and it never flashes a console window at you. Want to see it for yourself? Open Task Scheduler and look for ai.marginfront.ccc at the top of the library. stop pauses the meter, start brings it back, and uninstall removes it along with the rest of the setup. Those commands mean the same thing here as they do on macOS.

​
Spend caps work on Windows

Caps are opt-in on Windows too, and the command is the one you already know:
You’ll see a consent prompt that spells out the change, because Control turns this from a meter that watches you into one that can stop you. Say y to arm it. For Claude Code it arms on your next claude session. For Codex there’s one extra step, and only you can do it: open codex, run /hooks, and approve the MarginFront cap check. There’s nothing extra to install on Windows. The cap check runs on Node, which you already have. Everything under Spend Control applies here, including the honest limits about what a cap can and can’t stop.

​
Where your key lives

init saves your key to C:\Users\<you>\.marginfront-ccc\.env and locks that file to your Windows account, so other accounts on the PC can’t read it. If Windows refuses that lock, init says so and prints the three clicks in File Explorer that fix it. Don’t skip that message. Your key is saved either way, but until the file’s locked, another account on that PC can open it. Rather keep nothing on disk? Delete the key line from that file and set MARGINFRONT_API_KEY as an environment variable instead.

​
Checking it’s working

Reporting runs on a timer rather than per message, and the default interval is 5 minutes, so give it that long before deciding nothing happened. Then:
If your spend still isn’t showing up, work through these in order:
  • Did you reopen Claude or Codex after init? Telemetry settings are read at launch. Quit the agent and start it again.
  • Is the meter running? status tells you. If it isn’t, npx @marginfront/code-cost-clarity@latest start brings it back.
  • Is your coding agent running on Windows itself? An agent running inside a WSL distro is invisible to the Windows meter. See Running inside WSL below.
  • Is the key saved? Check that C:\Users\<you>\.marginfront-ccc\.env has your mf_sk_... key on the MARGINFRONT_API_KEY line.

​
Known limitations

  • The desktop apps aren’t metered on Windows yet. Run Claude Code and Codex from a terminal there. What you do in the Claude and Codex desktop apps doesn’t reach the meter.
  • Nobody has watched a full sign-out and sign-in on a real desktop yet. Our tests confirm that Windows stored the meter as a logon task set to start when you sign in, which is the setting that makes it come back. Watching it happen on a physical PC is a check we haven’t done. So run status once after your next sign-in. If it says the meter isn’t running, start puts it back in a second, and we’d like to hear about it.
  • Stopping on purpose can drop the last moments of usage. On Windows, stop shuts the collector down hard instead of asking it to wrap up first, so usage from the seconds right before you stopped can go unsent. This applies to stop and uninstall only. Ordinary coding isn’t affected.

​
Running inside WSL

You need this section only if your coding agent runs inside a WSL distro. Running Claude Code or Codex on Windows itself is the simpler path, and it’s the one the rest of this page describes. A coding agent inside a distro is invisible to the Windows meter. The distro has its own home directory and its own localhost, so it never sees the settings init wrote on the Windows side and never finds the collector listening there. If that’s your setup, install the tool inside that same distro.

​
You need a general-purpose distro

If you have Docker Desktop, you don’t already have what you need. Docker Desktop installs its own internal WSL distributions (docker-desktop and, on older versions, docker-desktop-data). Those are managed appliances for running Docker itself. They aren’t general-purpose Linux environments, and this tool doesn’t work inside them. This trips people up because wsl -l -v lists the Docker distros, so WSL looks installed and ready. Check what you actually have. Run this in PowerShell:
If everything listed is a docker-desktop* entry, you have no general-purpose distro. Install one in PowerShell:
Ubuntu coexists with Docker Desktop. Installing it doesn’t disturb your Docker setup.

​
Setup inside the distro

Open the distro when it finishes installing. Every command below runs at the Ubuntu prompt, not in PowerShell. You need Node.js inside the distro as well. Check with node -v there and install it there if it’s missing. Node on the Windows side doesn’t count, because the distro is a separate environment with its own programs.
init wires up what it can and then tells you the background meter didn’t install. That’s expected: there’s no background meter inside a distro. Start the meter yourself instead, and leave it open:
This holds the terminal. You’ll see a line per turn as usage arrives:
Capture happens only while run is open. Usage that happens while it’s closed is lost, not buffered. There’s no queue that catches up later. Start run in a dedicated terminal when you begin work, and leave it there. Start your coding agent from a second Ubuntu prompt, with run still going in the first:
or:
For the full command list, what gets captured, and Spend Control, see the main Code Cost Clarity page.