@marginfront/code-cost-clarity 0.5.4 → 0.6.1

package/README.md

@@ -2,7 +2,7 @@
 
 > See your Claude Code **and Codex** spend in MarginFront. One command wires your
 > coding-agent usage telemetry through a local collector and into MarginFront,
-> priced per engineer, per model, with **accurate prompt-cache token splitting**.
+> priced per developer, per model, with **accurate prompt-cache token splitting**.
 > One package, three modes: Claude Code only, Codex only, or both.
 
 > **⚠️ Beta (pilot software).** Under active development - pin a version, expect rough
@@ -17,8 +17,8 @@
 **📖 Full documentation:** https://docs.marginfront.com/tools/code-cost-clarity
 
 **This is internal cost visibility, not billing and not a spend cap.** The
-installing company watches its own AI coding spend (per engineer, per model,
-R&D-vs-COGS). It does not charge engineers and it does not cut anyone off.
+installing company watches its own AI coding spend (per developer, per model,
+R&D-vs-COGS). It does not charge developers and it does not cut anyone off.
 
 **Your LLM keys stay yours.** This tool never reads, needs, or transmits your
 Anthropic or OpenAI API key. The only credential it uses is your MarginFront key
@@ -28,7 +28,7 @@ Anthropic or OpenAI API key. The only credential it uses is your MarginFront key
 
 ## What this does (one sentence)
 
-Every time an engineer runs Claude Code, this connector captures the token usage
+Every time a developer runs Claude Code, this connector captures the token usage
 and sends it to MarginFront as a usage event, so you can see who used what, on
 which model, and how much it cost.
 
@@ -37,13 +37,13 @@ which model, and how much it cost.
 Think of it like a cash-register receipt system:
 
 1. **Claude Code** is the register. As it works, it broadcasts receipts
-   (OpenTelemetry exports): how many tokens, which model, which engineer.
+   (OpenTelemetry exports): how many tokens, which model, which developer.
 2. **The collector** (`otelcol-contrib`, open source) is the catcher. It runs in
    the background, catches the receipts, and writes them to a file.
 3. **The forwarder** (our glue, inside this package) reads those receipts and
    sends each one to MarginFront.
 4. **MarginFront** records the event, prices it, and shows it under the
-   engineer's email.
+   developer's email.
 
 ```
 Claude Code (your task)
@@ -103,7 +103,7 @@ claude          # or: codex   (or open the Claude/Codex desktop apps)
 > config when they launch, so anything that was already open won't emit until it's reopened.
 
 That's it. No `source`, no second terminal. Your spend shows up in MarginFront under
-your engineer email, automatically, and the background meter restarts itself at
+your developer email, automatically, and the background meter restarts itself at
 every login. Check on it anytime:
 
 ```bash
@@ -115,7 +115,7 @@ npx @marginfront/code-cost-clarity status
 stops it). You'll see a line per turn like:
 
 ```
-[14:22:07] recorded engineer@example.com · in=3210 out=287 · server=$0.0232 · cc=$0.0236 event=9f0c2a71-...
+[14:22:07] recorded developer@example.com · in=3210 out=287 · server=$0.0232 · cc=$0.0236 event=9f0c2a71-...
 ```
 
 **CI / scripted installs:** add `--no-prompt` to `init` to skip BOTH questions (the
@@ -180,34 +180,75 @@ It does **not** capture:
 
 ---
 
-## Per-engineer attribution is automatic
+## Per-developer attribution is automatic
 
 What makes "who spent what" work is `user.email`, and **Claude Code puts it in
-the telemetry on its own**. It's the engineer's logged-in Claude account email.
-There is no manual email config. Each engineer loads the telemetry settings
+the telemetry on its own**. It's the developer's logged-in Claude account email.
+There is no manual email config. Each developer loads the telemetry settings
 and runs Claude Code normally.
 
-**Works whether the engineer signs in with an org-managed seat or an interactive
+**Works whether the developer signs in with an org-managed seat or an interactive
 login.** On org-managed Claude seats the email is stamped for free. If an
-engineer's sign-in doesn't surface an email, the connector doesn't drop the
+developer's sign-in doesn't surface an email, the connector doesn't drop the
 usage. It attributes it to a clearly labeled placeholder customer
 (`claude-code-no-identity`) and prints how to fix it (sign in with an org-managed
 seat, or attach a customer mapping). You'll see the placeholder in `preview`/`run`
 output if it ever kicks in.
 
-> The MarginFront **API key** is separate from the engineer's identity: it's the
+> The MarginFront **API key** is separate from the developer's identity: it's the
 > connector's own credential for posting to MarginFront. `run` needs it;
 > `preview` does not.
 
 ---
 
+## Shared one login across the team? Set a per-machine developer (`CCC_DEVELOPER_EMAIL`)
+
+Some teams share **one** Claude/Codex login across the whole team. When that
+happens, every developer's telemetry carries the **same** `user.email`, so all the
+AI cost collapses onto one person and per-developer attribution breaks. CCC fixes
+this without any change to how you log in, because **CCC runs locally on each
+laptop** - so each laptop can carry its own developer identity.
+
+**During `init` we ask one question:** which developer this machine's AI cost should
+be attributed to. The prompt is pre-filled with your **global git email**
+(`git config --global user.email`), which is usually the right person sitting at
+this laptop. You have three choices:
+
+- **Press Enter** to accept the pre-filled email.
+- **Type a different email** to attribute this machine to someone else.
+- **Clear it and leave it blank** to keep the old behavior - auto-detect from
+  whatever email the coding-agent login reports.
+
+Whatever you choose is saved as **`CCC_DEVELOPER_EMAIL`** in
+`~/.marginfront-ccc/.env` (mode 600, right next to your key). To change it later,
+edit that one line and then `stop` + `start` (or just re-run `init`).
+
+**Precedence at send time (highest wins):**
+
+1. **`CCC_DEVELOPER_EMAIL`** (this machine's developer) - if set, it wins for **every**
+   record this machine sends, Claude **and** Codex, token turns **and** tool calls.
+2. Otherwise the email the coding-agent login reports (`user.email`).
+3. Otherwise the no-identity placeholder (`claude-code-no-identity` /
+   `codex-no-identity`).
+
+If you **don't** set it (leave it blank), nothing changes - attribution is
+byte-for-byte what it was before this feature: the login's own `user.email`, then
+the placeholder.
+
+> This is **internal cost visibility only**. `CCC_DEVELOPER_EMAIL` re-labels which
+> developer the cost shows up under in _your_ MarginFront - it does **not** change
+> who pays or any customer's bill. The `--no-prompt` (CI / scripted) install skips
+> this question and leaves `CCC_DEVELOPER_EMAIL` unset.
+
+---
+
 ## Privacy (read this)
 
 This tool is **internal cost visibility**, and being honest about what it turns on
 matters, so here is the full picture in plain English.
 
-**Your engineer email travels in the telemetry, in plaintext, on purpose.** That's
-the whole point: per-engineer cost attribution needs to know who ran the turn.
+**Your developer email travels in the telemetry, in plaintext, on purpose.** That's
+the whole point: per-developer cost attribution needs to know who ran the turn.
 Claude Code stamps `user.email` (your logged-in account email) onto the usage
 telemetry, the local collector writes it to a file on your machine, and the
 forwarder POSTs it to MarginFront so the spend lands under your name. It is **not**
@@ -304,7 +345,7 @@ silent charge). Free built-ins (file reads, shell, grep) are never forwarded.
 
 The same package captures **Codex** too. Nothing extra to install. Codex reports
 to the **same** local collector. You get three modes for free: Claude Code only,
-Codex only, or **both** (same engineer's name on all of it).
+Codex only, or **both** (same developer's name on all of it).
 
 **`init` turns it on for you** when you consent, it adds this `[otel]` block to
 your `~/.codex/config.toml` automatically:
@@ -350,8 +391,8 @@ the input rate and drops the cache-read field, so the number reads high, never l
 
 ### Identity by sign-in mode (org seat vs ChatGPT login)
 
-Per-engineer attribution rides on `user.email` from Codex's telemetry, same idea
-as Claude Code. Whether that email surfaces depends on how the engineer signs in
+Per-developer attribution rides on `user.email` from Codex's telemetry, same idea
+as Claude Code. Whether that email surfaces depends on how the developer signs in
 to Codex (an org-managed or API-key sign-in stamps it; some interactive ChatGPT
 logins may not). We never read that OpenAI key; the only thing that matters here is
 whether the telemetry carries an email. If it doesn't surface, the usage isn't
@@ -375,7 +416,7 @@ exactly like the Claude path.
 
 > **Confirm the dollar figure once.** The exact Codex dollar figure should be
 > confirmed against one real captured session: that Codex reports per-turn (not
-> session-cumulative) token counts on the log stream, and that your engineer email
+> session-cumulative) token counts on the log stream, and that your developer email
 > populates under your sign-in mode. The mapping above is the verified-safe
 > default; the confirmation is a one-session spike, not a blocker to installing.
 
@@ -454,7 +495,7 @@ curl -s -H "x-api-key: $KEY" \
 
 ---
 
-## For engineers (technical appendix)
+## For developers (technical appendix)
 
 **Input shape:** OTLP/JSON, tree `resourceMetrics[].scopeMetrics[].metrics[]`. Two
 metrics matter: `claude_code.token.usage` (one datapoint per `type` in

package/dist/cli.d.ts

@@ -33,6 +33,7 @@ interface PromptIO {
     terminal?: boolean;
 }
 declare function promptYesNo(promptText: string, io?: PromptIO, defaultYes?: boolean): Promise<boolean>;
+declare function promptVisible(promptText: string, defaultValue?: string, io?: PromptIO): Promise<string>;
 interface InitDeps {
     ensureConfigFiles?: () => void;
     ensureCollectorBinary?: () => void;
@@ -40,6 +41,9 @@ interface InitDeps {
     isTTY?: () => boolean;
     promptSecret?: (promptText: string) => Promise<string>;
     writeApiKey?: (value: string) => void;
+    gitDefaultEmail?: () => string;
+    promptDeveloperEmail?: (defaultValue: string) => Promise<string>;
+    writeDeveloperEmail?: (value: string) => void;
     hasApiKey?: () => boolean;
     promptConsent?: () => Promise<boolean>;
     writeClaudeTelemetry?: () => WriteClaudeSettingsResult;
@@ -83,8 +87,13 @@ interface UninstallDeps {
     purgeConfigDir?: () => void;
     findZshrcLines?: () => ZshrcSourceLineResult;
     unsetDesktopEnv?: () => void;
+    readForwarderPid?: () => number | null;
+    isForwarderAlive?: (pid: number) => boolean;
+    signalForwarder?: (pid: number, signal: "SIGTERM" | "SIGKILL") => void;
+    sleep?: (ms: number) => Promise<void>;
+    now?: () => number;
     log?: (message: string) => void;
 }
-declare function cmdUninstall(purge: boolean, deps?: UninstallDeps): number;
+declare function cmdUninstall(purge: boolean, deps?: UninstallDeps): Promise<number>;
 
-export { type InitDeps, type PromptIO, type StartDeps, type StopDeps, type UninstallDeps, cmdInit, cmdRun, cmdStart, cmdUninstall, promptYesNo, runningForwarderPid, stopForwarderThenStopCollector };
+export { type InitDeps, type PromptIO, type StartDeps, type StopDeps, type UninstallDeps, cmdInit, cmdRun, cmdStart, cmdUninstall, promptVisible, promptYesNo, runningForwarderPid, stopForwarderThenStopCollector };