Skip to main content

​
Code Cost Clarity on Windows (WSL)

Code Cost Clarity runs on Windows through WSL (Windows Subsystem for Linux). It does not run on Windows natively. Read this page before you start. Windows capture works, but it works differently than it does on macOS, and one of the differences decides whether your spend gets recorded at all.

​
What works today

Native Windows is refused on purpose. The collector this tool downloads is published for macOS and Linux only, so init stops with an error naming the platform instead of installing something that cannot work. On WSL there is no background meter. The auto-start meter on macOS is a launchd job, and launchd is macOS-only. Nothing equivalent is installed on Linux or WSL.

​
The one thing that decides whether this works

On macOS the meter runs in the background and captures your spend whether or not you are thinking about it. On WSL, capture happens only while run is open in a terminal. Usage that happens while run is not open is lost, not buffered. There is no queue that catches up later. If you close the terminal, code for three hours, and reopen it, that three hours is gone and nothing will report it. Plan around that. Start run in a dedicated terminal window when you begin work, and leave it open.

​
Before you start: you need a general-purpose distro

If you have Docker Desktop, you do not 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 are not general-purpose Linux environments, and this tool does not 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 does not disturb your Docker setup. Open the distro when it finishes. Every remaining command on this page runs at the Ubuntu shell prompt, not in PowerShell.

​
Setup

You need Node.js inside the distro. Check with node -v at the Ubuntu prompt and install it there if it is missing. Node installed on the Windows side does not count: the distro is a separate environment with its own programs.

​
1. Run init without the prompt

At the Ubuntu prompt:
Use --no-prompt. It is not optional here. The reason is worth understanding, because it also tells you what to avoid later. init installs the background meter whenever a MarginFront key is present, and that install is the launchd step, which does not exist on Linux. It throws. What decides the outcome is whether a key is present, not which flag you passed. On a fresh machine no key is saved yet, so --no-prompt skips the paste, leaves the key absent, and init finishes cleanly. Plain init would have you paste a key and then fail on the launchd step.
Once your key is saved in step 2, do not run init again on WSL. A key already sitting in ~/.marginfront-ccc/.env counts as present, so any later init reaches the launchd step and throws, with --no-prompt or without it. The error mentions launchctl or a path under ~/Library/LaunchAgents, and the run can leave a stray macOS-style .plist file in your Linux home directory. That file does nothing on Linux and is safe to delete. To change a setting later, edit ~/.marginfront-ccc/.env directly instead of re-running init.

​
2. Add your MarginFront key

init created ~/.marginfront-ccc/.env inside the distro. Open it and put your secret key on the MARGINFRONT_API_KEY line:
The line reads:
Use a secret key (mf_sk_...). A publishable key (mf_pk_...) is rejected. Get one from the dashboard under Build → API keys.

​
3. Start the meter and leave it open

At the Ubuntu prompt:
This holds the terminal. You will see a line per turn as usage arrives:
Ctrl-C stops it and shuts the collector down with it. Nothing is captured after that until you start it again. Do not run npx @marginfront/code-cost-clarity start on WSL. That command installs the background meter, which is the macOS-only piece. stop is still useful here. If run says a forwarder is already running and refuses to start a second one, stop ends that process and clears the leftover pid file, after which run starts cleanly.

​
Run your coding agent in the same distro

Your coding agent has to run inside the same WSL distro as this tool. A coding agent running on the Windows side is invisible to it. The reason is plumbing, not policy. init writes its telemetry settings into config files under your home directory, and the agent sends usage to a collector listening on 127.0.0.1:4318. Inside the distro, that home directory and that address belong to the distro. A Windows-side agent reads a different home directory and reaches a different localhost, so it never sees the settings and never finds the collector. This matters most for Codex, because Codex does not need WSL. OpenAI supports running Codex natively on Windows with a PowerShell sandbox, and separately inside WSL2 (Codex on Windows). Both are supported ways to run Codex. Only the WSL2 one can be metered by this tool. So the choice is yours to make with open eyes: run your coding agent inside the distro and get spend tracking, or run it natively on Windows and go without. Start your agent from the same Ubuntu prompt, in a second terminal, with run still going in the first:
or:

​
Checking it is working

With run open in one terminal and your coding agent working in another, you should see a recorded line appear in the run terminal. Reporting is on a timer rather than per message, and the default interval is 5 minutes, so wait that long before deciding nothing happened. If nothing appears, work through these in order:
  • Is run still open? If the terminal closed or Ctrl-C was pressed, capture stopped.
  • Is the coding agent in the same distro? Run wsl -l -v in PowerShell to confirm you have one general-purpose distro, then confirm the agent was started from that distro’s prompt and not from PowerShell or a Docker distro.
  • Did the agent start before init? Telemetry settings are read at launch. Quit the agent and start it again.
  • Is the key saved? Check that ~/.marginfront-ccc/.env has your mf_sk_... key on the MARGINFRONT_API_KEY line.

​
What this does not do on Windows

  • No auto-start. Nothing runs at login. You start run yourself.
  • No capture when run is closed. That usage is lost rather than delayed.
  • No coverage of Windows-side tools. Anything running outside the distro is not visible, including a natively installed coding agent.
  • No spend caps that survive a closed terminal. Spend Control depends on the same local pieces, so a machine with run closed is a machine with nothing watching it.
For the full command list, what gets captured, and Spend Control, see the main Code Cost Clarity page. Everything there about the background meter and login auto-start is macOS-only.