> ## Documentation Index > Fetch the complete documentation index at: https://docs.marginfront.com/llms.txt > Use this file to discover all available pages before exploring further. # Code Cost Clarity on Windows (WSL) > What works, what does not, and the exact setup that captures spend on a Windows machine # 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 | Piece | Windows native | WSL | | ---------------- | -------------- | --------------------------- | | `init` | Refused | Works (with the flag below) | | Collector | Not available | Works | | Foreground `run` | Not available | Works | | Background meter | Not available | **Does not exist** | **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**: ```powershell theme={null} wsl -l -v ``` If everything listed is a `docker-desktop*` entry, you have no general-purpose distro. Install one in **PowerShell**: ```powershell theme={null} wsl --install -d Ubuntu ``` 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**: ```bash theme={null} npx @marginfront/code-cost-clarity@latest init --no-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: ```bash theme={null} nano ~/.marginfront-ccc/.env ``` The line reads: ``` MARGINFRONT_API_KEY=mf_sk_your_key_here ``` 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**: ```bash theme={null} npx @marginfront/code-cost-clarity@latest run ``` This holds the terminal. You will see a line per turn as usage arrives: ``` [14:22:07] recorded developer@example.com · in=3210 out=287 · server=$0.0232 · cc=$0.0236 event=9f0c2a71-... ``` 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](https://developers.openai.com/codex/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: ```bash theme={null} claude ``` or: ```bash theme={null} codex ``` *** ## 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](/tools/code-cost-clarity). Everything there about the background meter and login auto-start is macOS-only.