aimpg 0.6.0__tar.gz → 0.6.2__tar.gz

{aimpg-0.6.0 → aimpg-0.6.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: aimpg
-Version: 0.6.0
+Version: 0.6.2
 Summary: Real-world energy per solved task for AI coding agents
 Project-URL: Homepage, https://github.com/kumarganduri/aimpg
 Project-URL: Issues, https://github.com/kumarganduri/aimpg/issues
@@ -26,25 +26,27 @@ Description-Content-Type: text/markdown
 uvx aimpg report
 ```
 
+**New here? [aimpg in 5 minutes](https://kumarganduri.github.io/aimpg-scoreboard/start/)** walks you from install to your first numbers, the live status line, and your team's GitHub Action, with copy buttons for every command.
+
 ```
 YOUR AI CODING
-  Energy   14.46 kWh – 130.59 kWh
-           ≈ boiling a litre of water in a kettle 140–1,300 times · driving an electric car 85–770 km · 6.6–59.8 kg CO₂
-  Money    $1,284 API-equivalent (Anthropic's published prices)
-  Output   353 commits made with AI help
+  Energy   17.31 kWh – 156.95 kWh
+  Money    $1,567 at API list prices (Anthropic's and OpenAI's; a subscription costs less)
+  Output   454 commits made with AI help
 
-  A typical kept commit:  36.6 Wh – 313.0 Wh ≈ 2–18 full phone charges · $2.05
+  A typical kept commit:  20.0 Wh – 179.3 Wh · $1.63
 
 WHAT WOULD HAVE SAVED THE MOST (measured on your logs; upper bounds that overlap)
-  1. Start a fresh session after each commit: up to 45% less energy, $397
-     45% of your AI energy went to re-reading conversation from before your last commit.
-     → After committing, start a new session (or /clear) for the next task.
-  2. Use a mid-size model for routine work: up to 16% less energy, $333
-     94% of your AI energy ran on the largest models (Opus/Fable class).
-     → Check a cheaper model is good enough on your own commits: `aimpg replay models`.
+  1. Start a fresh session after each commit: up to 41%–46% less energy, up to $457
+     57% of the tokens your agents processed were conversation carried over from before your last commit.
+     A fresh session has to rebuild some context, which isn't counted here, so the real saving is smaller.
+     → After committing, start a new session (or /clear) for the next task, and give it a one-line summary if needed.
+  2. Use a mid-size model for routine work: up to 17% less energy, $408
+     95% of your AI energy ran on the largest models (Opus/Fable class).
+     → Try Sonnet for routine fixes; check it's good enough on your own commits with `aimpg replay` (model picker).
 
 WORKING CHANGES (commits that shipped and lasted 30 days)
-  Available on 2026-10-22: aimpg is keeping your history so it can tell.
+  Available on 2026-10-13: aimpg is keeping your history so it can tell.
 ```
 
 *(Real output from the author's last 30 days.)*
@@ -68,7 +70,11 @@ aimpg report --cursor-usage ~/Downloads/usage-events.csv --cursor-repo ~/code/my
 Team export? Add `--cursor-user "Your Name"` to count only your rows.
 
 ### 1. See your AI footprint in terms you can picture
-`aimpg report` reads the Claude Code (and Codex CLI) logs already on your machine and ties every AI request to the git commit it produced. Energy is shown as an honest range and translated into kettles, phone charges, EV kilometres and CO₂. Money is the API-equivalent cost at Anthropic's published prices (for subscribers, what the same work would cost on the API).
+`aimpg report` reads the Claude Code (and Codex CLI) logs already on your machine and ties every AI request to the git commit it produced. Energy is shown as an honest range and translated into kettles, phone charges, EV kilometres and CO₂. Money is the cost at Anthropic's and OpenAI's API list prices; on a subscription you pay less, so read it as the value of the work, not your bill.
+
+`aimpg report --share` also writes a card to post, with totals only (no repo names, commit messages or code), and prints a one-line post to go with it:
+
+![aimpg share card](docs/receipt-card.png)
 
 ### 2. Get tips measured on your own habits, not generic advice
 The receipt replays your own logs under "what if" rules and tells you what would have saved the most, in Wh and dollars. For example: how much energy went into re-reading old conversation in long sessions, or into running the biggest model for routine fixes.
@@ -113,7 +119,7 @@ VERDICT: NOT PROVEN
 
   Energy, same tasks: +10% (interval -11%…+35%, 17 shared solved commits)
 ```
-That's the real result on the author's Legwork repo: no saving shown, far from the advertised 60–90%. Your repo may differ, and now you can check.
+That's the real result on the author's Legwork repo: no reliable energy saving shown on one repo (RTK advertises token savings; a larger, pre-registered study across several public repos is under way). Your repo may differ, and now you can check.
 
 Every run writes a **record** (`~/.aimpg/verify/*.record.json`) holding versions, both setups, each run's tokens, $ and outcome, and the verdict, but never code, diffs or commit messages. Repo and commits are hashed unless you add `--public`. Anyone can recheck the math and the record's consistency for free with `aimpg verify --check record.json` (it can't prove the runs happened), and rerun a public record on their own machine with `aimpg verify --rerun record.json --repo <clone>`, which first shows every command, hook and prompt the record would run and asks before running them. Private records keep only fingerprints (SHA-256) of your prompts, CLAUDE.md, settings and commands, never the text. Records also list every redone attempt and excluded commit.
 
@@ -147,7 +153,7 @@ jobs:
     steps:
       - uses: actions/checkout@v4
         with: {fetch-depth: 0}
-      - uses: kumarganduri/aimpg@v0.6.0
+      - uses: kumarganduri/aimpg@v0.6.2   # or pin a commit SHA: it runs with your repo token
         with:
           mode: ${{ github.event_name == 'pull_request' && 'pr' || 'rollup' }}
           comment: "true"
@@ -177,14 +183,17 @@ For a standard figure, `aimpg sci --json sci.json` reports your carbon intensity
 
 **Working changes:** aimpg keeps a small history of what each commit cost (never prompts or code), because Claude Code deletes its own logs after 30 days. Once a commit is 30 days old, it is judged: still on the main branch and not reverted or largely rewritten counts as a *working change*. The receipt then shows **cost per working change** and a **waste ratio** (AI spend on work that didn't last).
 
-**Energy:** a physical formula, not a price proxy. Prefill compute for new input, one KV-cache re-read per output token (so long contexts cost more), plus datacenter overhead. Model sizes aren't public, so every number is a range. Overheads follow Google's full-stack measurement of a median Gemini prompt (chips, host CPU and memory, idle capacity, cooling ≈ 1.7× the chips alone), and a chat-sized prompt on a mid-size model comes out at 0.017–0.34 Wh, bracketing Google's disclosed 0.24 Wh ([arXiv 2508.15734](https://arxiv.org/pdf/2508.15734)). Sources for every factor are in [`aimpg/factors.json`](aimpg/factors.json), [`aimpg/prices.json`](aimpg/prices.json) and [`aimpg/equivalences.json`](aimpg/equivalences.json).
+**Energy:** an estimate with stated assumption ranges, not a measurement: a physical formula, not a price proxy. Prefill compute for new input, one KV-cache re-read per output token (so long contexts cost more), plus datacenter overhead. Model sizes aren't public, so every number is a range. Overheads follow Google's full-stack measurement of a median Gemini prompt (chips, host CPU and memory, idle capacity, cooling ≈ 1.7× the chips alone), and a chat-sized prompt on a mid-size model comes out at 0.017–0.34 Wh, bracketing Google's disclosed 0.24 Wh ([arXiv 2508.15734](https://arxiv.org/pdf/2508.15734)). Sources for every factor are in [`aimpg/factors.json`](aimpg/factors.json), [`aimpg/prices.json`](aimpg/prices.json) and [`aimpg/equivalences.json`](aimpg/equivalences.json).
 
 **Replays:** each run starts from the code just before your commit, in a fresh, history-free copy, inside a sandbox (Seatbelt on macOS, bubblewrap on Linux). The only network allowed is the model API, through an allowlisting proxy. Your own tests judge the result, and edited tests are always restored before judging. Every token count is cross-checked against Claude Code's own totals. Details are in [docs/designs/aimpg-design.md](docs/designs/aimpg-design.md).
 
+Questions people ask (is it sponsored, are the energy numbers guesses, is it safe to run): see the [FAQ](docs/FAQ.md).
+
 ## Limits (honest list)
 
 - Claude Code and Codex CLI logs are read automatically. Cursor keeps token usage on its servers, so it needs its usage export (below), and that export doesn't say which folder the work was in: give `--cursor-repo` and requests are matched to your next own commit there by time alone (shown as "by time only"). Replays and `verify` need macOS or Linux and an API key (about $0.10–0.30 per run). On Linux install bubblewrap (`sudo apt install bubblewrap`); Ubuntu 24.04+ also needs a one-time AppArmor rule for bwrap, which aimpg prints if it's missing.
-- Energy is an estimate with a wide range; dollars are close (within about 7% of Claude Code's own session totals on the author's logs).
+- Windows: `report`, `live` and the team commands are untested there; replays and `verify` need macOS or Linux.
+- Energy is an estimate with a wide range (model sizes are guesses within stated bounds); dollars are close (within about 7% of Claude Code's own session totals on the author's logs).
 - Tips are upper bounds and overlap; they can't be added together.
 - Replays from commit messages alone are hard (12% solved on the author's repo); `--task-mode tests` shows the agent the tests, which makes tasks easier than real work but keeps comparisons fair.
 

{aimpg-0.6.0 → aimpg-0.6.2}/README.md

@@ -6,25 +6,27 @@
 uvx aimpg report
 ```
 
+**New here? [aimpg in 5 minutes](https://kumarganduri.github.io/aimpg-scoreboard/start/)** walks you from install to your first numbers, the live status line, and your team's GitHub Action, with copy buttons for every command.
+
 ```
 YOUR AI CODING
-  Energy   14.46 kWh – 130.59 kWh
-           ≈ boiling a litre of water in a kettle 140–1,300 times · driving an electric car 85–770 km · 6.6–59.8 kg CO₂
-  Money    $1,284 API-equivalent (Anthropic's published prices)
-  Output   353 commits made with AI help
+  Energy   17.31 kWh – 156.95 kWh
+  Money    $1,567 at API list prices (Anthropic's and OpenAI's; a subscription costs less)
+  Output   454 commits made with AI help
 
-  A typical kept commit:  36.6 Wh – 313.0 Wh ≈ 2–18 full phone charges · $2.05
+  A typical kept commit:  20.0 Wh – 179.3 Wh · $1.63
 
 WHAT WOULD HAVE SAVED THE MOST (measured on your logs; upper bounds that overlap)
-  1. Start a fresh session after each commit: up to 45% less energy, $397
-     45% of your AI energy went to re-reading conversation from before your last commit.
-     → After committing, start a new session (or /clear) for the next task.
-  2. Use a mid-size model for routine work: up to 16% less energy, $333
-     94% of your AI energy ran on the largest models (Opus/Fable class).
-     → Check a cheaper model is good enough on your own commits: `aimpg replay models`.
+  1. Start a fresh session after each commit: up to 41%–46% less energy, up to $457
+     57% of the tokens your agents processed were conversation carried over from before your last commit.
+     A fresh session has to rebuild some context, which isn't counted here, so the real saving is smaller.
+     → After committing, start a new session (or /clear) for the next task, and give it a one-line summary if needed.
+  2. Use a mid-size model for routine work: up to 17% less energy, $408
+     95% of your AI energy ran on the largest models (Opus/Fable class).
+     → Try Sonnet for routine fixes; check it's good enough on your own commits with `aimpg replay` (model picker).
 
 WORKING CHANGES (commits that shipped and lasted 30 days)
-  Available on 2026-10-22: aimpg is keeping your history so it can tell.
+  Available on 2026-10-13: aimpg is keeping your history so it can tell.
 ```
 
 *(Real output from the author's last 30 days.)*
@@ -48,7 +50,11 @@ aimpg report --cursor-usage ~/Downloads/usage-events.csv --cursor-repo ~/code/my
 Team export? Add `--cursor-user "Your Name"` to count only your rows.
 
 ### 1. See your AI footprint in terms you can picture
-`aimpg report` reads the Claude Code (and Codex CLI) logs already on your machine and ties every AI request to the git commit it produced. Energy is shown as an honest range and translated into kettles, phone charges, EV kilometres and CO₂. Money is the API-equivalent cost at Anthropic's published prices (for subscribers, what the same work would cost on the API).
+`aimpg report` reads the Claude Code (and Codex CLI) logs already on your machine and ties every AI request to the git commit it produced. Energy is shown as an honest range and translated into kettles, phone charges, EV kilometres and CO₂. Money is the cost at Anthropic's and OpenAI's API list prices; on a subscription you pay less, so read it as the value of the work, not your bill.
+
+`aimpg report --share` also writes a card to post, with totals only (no repo names, commit messages or code), and prints a one-line post to go with it:
+
+![aimpg share card](docs/receipt-card.png)
 
 ### 2. Get tips measured on your own habits, not generic advice
 The receipt replays your own logs under "what if" rules and tells you what would have saved the most, in Wh and dollars. For example: how much energy went into re-reading old conversation in long sessions, or into running the biggest model for routine fixes.
@@ -93,7 +99,7 @@ VERDICT: NOT PROVEN
 
   Energy, same tasks: +10% (interval -11%…+35%, 17 shared solved commits)
 ```
-That's the real result on the author's Legwork repo: no saving shown, far from the advertised 60–90%. Your repo may differ, and now you can check.
+That's the real result on the author's Legwork repo: no reliable energy saving shown on one repo (RTK advertises token savings; a larger, pre-registered study across several public repos is under way). Your repo may differ, and now you can check.
 
 Every run writes a **record** (`~/.aimpg/verify/*.record.json`) holding versions, both setups, each run's tokens, $ and outcome, and the verdict, but never code, diffs or commit messages. Repo and commits are hashed unless you add `--public`. Anyone can recheck the math and the record's consistency for free with `aimpg verify --check record.json` (it can't prove the runs happened), and rerun a public record on their own machine with `aimpg verify --rerun record.json --repo <clone>`, which first shows every command, hook and prompt the record would run and asks before running them. Private records keep only fingerprints (SHA-256) of your prompts, CLAUDE.md, settings and commands, never the text. Records also list every redone attempt and excluded commit.
 
@@ -127,7 +133,7 @@ jobs:
     steps:
       - uses: actions/checkout@v4
         with: {fetch-depth: 0}
-      - uses: kumarganduri/aimpg@v0.6.0
+      - uses: kumarganduri/aimpg@v0.6.2   # or pin a commit SHA: it runs with your repo token
         with:
           mode: ${{ github.event_name == 'pull_request' && 'pr' || 'rollup' }}
           comment: "true"
@@ -157,14 +163,17 @@ For a standard figure, `aimpg sci --json sci.json` reports your carbon intensity
 
 **Working changes:** aimpg keeps a small history of what each commit cost (never prompts or code), because Claude Code deletes its own logs after 30 days. Once a commit is 30 days old, it is judged: still on the main branch and not reverted or largely rewritten counts as a *working change*. The receipt then shows **cost per working change** and a **waste ratio** (AI spend on work that didn't last).
 
-**Energy:** a physical formula, not a price proxy. Prefill compute for new input, one KV-cache re-read per output token (so long contexts cost more), plus datacenter overhead. Model sizes aren't public, so every number is a range. Overheads follow Google's full-stack measurement of a median Gemini prompt (chips, host CPU and memory, idle capacity, cooling ≈ 1.7× the chips alone), and a chat-sized prompt on a mid-size model comes out at 0.017–0.34 Wh, bracketing Google's disclosed 0.24 Wh ([arXiv 2508.15734](https://arxiv.org/pdf/2508.15734)). Sources for every factor are in [`aimpg/factors.json`](aimpg/factors.json), [`aimpg/prices.json`](aimpg/prices.json) and [`aimpg/equivalences.json`](aimpg/equivalences.json).
+**Energy:** an estimate with stated assumption ranges, not a measurement: a physical formula, not a price proxy. Prefill compute for new input, one KV-cache re-read per output token (so long contexts cost more), plus datacenter overhead. Model sizes aren't public, so every number is a range. Overheads follow Google's full-stack measurement of a median Gemini prompt (chips, host CPU and memory, idle capacity, cooling ≈ 1.7× the chips alone), and a chat-sized prompt on a mid-size model comes out at 0.017–0.34 Wh, bracketing Google's disclosed 0.24 Wh ([arXiv 2508.15734](https://arxiv.org/pdf/2508.15734)). Sources for every factor are in [`aimpg/factors.json`](aimpg/factors.json), [`aimpg/prices.json`](aimpg/prices.json) and [`aimpg/equivalences.json`](aimpg/equivalences.json).
 
 **Replays:** each run starts from the code just before your commit, in a fresh, history-free copy, inside a sandbox (Seatbelt on macOS, bubblewrap on Linux). The only network allowed is the model API, through an allowlisting proxy. Your own tests judge the result, and edited tests are always restored before judging. Every token count is cross-checked against Claude Code's own totals. Details are in [docs/designs/aimpg-design.md](docs/designs/aimpg-design.md).
 
+Questions people ask (is it sponsored, are the energy numbers guesses, is it safe to run): see the [FAQ](docs/FAQ.md).
+
 ## Limits (honest list)
 
 - Claude Code and Codex CLI logs are read automatically. Cursor keeps token usage on its servers, so it needs its usage export (below), and that export doesn't say which folder the work was in: give `--cursor-repo` and requests are matched to your next own commit there by time alone (shown as "by time only"). Replays and `verify` need macOS or Linux and an API key (about $0.10–0.30 per run). On Linux install bubblewrap (`sudo apt install bubblewrap`); Ubuntu 24.04+ also needs a one-time AppArmor rule for bwrap, which aimpg prints if it's missing.
-- Energy is an estimate with a wide range; dollars are close (within about 7% of Claude Code's own session totals on the author's logs).
+- Windows: `report`, `live` and the team commands are untested there; replays and `verify` need macOS or Linux.
+- Energy is an estimate with a wide range (model sizes are guesses within stated bounds); dollars are close (within about 7% of Claude Code's own session totals on the author's logs).
 - Tips are upper bounds and overlap; they can't be added together.
 - Replays from commit messages alone are hard (12% solved on the author's repo); `--task-mode tests` shows the agent the tests, which makes tasks easier than real work but keeps comparisons fair.
 

{aimpg-0.6.0 → aimpg-0.6.2}/action.yml

@@ -27,7 +27,9 @@ outputs:
 runs:
   using: composite
   steps:
-    - uses: astral-sh/setup-uv@v6
+    - uses: astral-sh/setup-uv@d0cc045d04ccac9d8b7881df0226f9e82c39688e  # v6, pinned: users run this with their repo's token
+      with:
+        version: "0.11.29"
     - name: fetch aimpg notes
       shell: bash
       working-directory: ${{ inputs.path }}

aimpg-0.6.2/aimpg/card.py

@@ -0,0 +1,151 @@
+"""`aimpg report --share`: a receipt card for social posts (1200×630, the size link
+previews use). Totals only: never repo names, commit messages, paths or code.
+
+Writes an SVG (always) and a PNG next to it when the machine can render one
+(macOS Quick Look, rsvg-convert, or cairosvg), and returns a one-line post.
+"""
+
+from __future__ import annotations
+
+import html
+import re
+import shutil
+import statistics
+import subprocess
+import tempfile
+import time
+from dataclasses import dataclass
+from pathlib import Path
+
+from aimpg.coach import tips as coach_tips
+from aimpg.cost import total_cost
+from aimpg.energy import total_wh
+from aimpg.receipt import KEPT, task_energy
+
+W, H = 1200, 630
+
+
+@dataclass
+class CardNumbers:
+    days: int
+    usd: float
+    commits: int
+    kwh: tuple[float, float]
+    typical_usd: float | None
+    typical_label: str
+    tip: str | None
+    cost_per_working: float | None
+
+
+def numbers(parsed, attribution, since: float, now: float, judged=None) -> CardNumbers:
+    in_window = [r for r in parsed.requests if r.ts >= since]
+    energies = task_energy(attribution.tasks)
+    usd, _ = total_cost(in_window)
+    wh = total_wh(in_window)
+    with_work = [e for e in energies if e.task.requests]
+    kept = [e for e in with_work if e.task.status in KEPT]
+    pool = kept if len(kept) >= 5 else with_work
+    typical = statistics.median(e.usd for e in pool) if pool else None
+    found = coach_tips(in_window, attribution)
+    tip = None
+    fresh = next((t for t in found if t.title.startswith("Start a fresh session")), None)
+    pct = re.match(r"\d+%", fresh.measured) if fresh else None
+    if pct:
+        tip = f"{pct.group(0)} of my agents' tokens re-read conversation from before my last commit"
+    cpw = judged.cost_per_durable() if judged is not None and judged.judged else None
+    return CardNumbers(round((now - since) / 86400), usd, len(energies), (wh.low / 1000, wh.high / 1000), typical,
+                       "per kept commit" if pool is kept else "per commit", tip, cpw)
+
+
+def _money(x: float) -> str:
+    return f"${x:,.0f}" if x >= 100 else f"${x:,.2f}"
+
+
+def svg(n: CardNumbers) -> str:
+    e = html.escape
+    big = _money(n.cost_per_working) if n.cost_per_working is not None else (_money(n.typical_usd) if n.typical_usd else "—")
+    big_label = "per working change (still standing after 30 days)" if n.cost_per_working is not None else n.typical_label
+    kwh = f"{n.kwh[0]:,.1f}–{n.kwh[1]:,.0f} kWh" if n.kwh[1] >= 10 else f"{n.kwh[0]:,.2f}–{n.kwh[1]:,.1f} kWh"
+    rows = [("AI spend at API list prices", _money(n.usd)), ("Commits made with AI help", f"{n.commits:,}"),
+            ("Energy (estimate, range)", kwh)]
+    row_svg = "".join(
+        f'<text x="72" y="{392 + i * 52}" class="k">{e(k)}</text><text x="1128" y="{392 + i * 52}" class="v" text-anchor="end">{e(v)}</text>'
+        f'<line x1="72" y1="{408 + i * 52}" x2="1128" y2="{408 + i * 52}" class="rule"/>'
+        for i, (k, v) in enumerate(rows))
+    tip = f'<text x="72" y="566" class="tip">↺ {e(n.tip)}</text>' if n.tip else ""
+    return f'''<svg xmlns="http://www.w3.org/2000/svg" width="{W}" height="{H}" viewBox="0 0 {W} {H}">
+<style>
+.bg{{fill:#10292a}} .k{{font:500 26px "IBM Plex Sans",Helvetica,Arial,sans-serif;fill:#9fb9b2}}
+.v{{font:600 28px "IBM Plex Mono",Menlo,monospace;fill:#e2ece8}} .rule{{stroke:#24433f;stroke-width:1.5}}
+.eyebrow{{font:600 22px "IBM Plex Mono",Menlo,monospace;fill:#f0ad3a;letter-spacing:3px}}
+.big{{font:800 132px "Archivo","Helvetica Neue",Arial,sans-serif;fill:#ffffff}}
+.biglabel{{font:500 30px "IBM Plex Sans",Helvetica,Arial,sans-serif;fill:#e2ece8}}
+.tip{{font:500 24px "IBM Plex Sans",Helvetica,Arial,sans-serif;fill:#f0ad3a}}
+.foot{{font:500 22px "IBM Plex Mono",Menlo,monospace;fill:#9fb9b2}}
+</style>
+<rect class="bg" width="{W}" height="{H}"/>
+<rect x="0" y="0" width="{W}" height="8" fill="#f0ad3a"/>
+<text x="72" y="92" class="eyebrow">MY AI CODING · LAST {n.days} DAYS</text>
+<text x="66" y="236" class="big">{e(big)}</text>
+<text x="72" y="290" class="biglabel">{e(big_label)}</text>
+{row_svg}
+{tip}
+<text x="1128" y="606" class="foot" text-anchor="end">see yours: uvx aimpg report</text>
+</svg>
+'''
+
+
+def post_text(n: CardNumbers) -> str:
+    head = (f"My AI coding costs {_money(n.cost_per_working)} per working change"
+            if n.cost_per_working is not None else
+            f"My AI coding: {_money(n.typical_usd)} {n.typical_label}" if n.typical_usd else "My AI coding")
+    return (f"{head} ({_money(n.usd)} over {n.commits} commits in {n.days} days, at API list prices). "
+            "Measured from my own Claude Code/Codex logs with aimpg. See yours: uvx aimpg report")
+
+
+CHROMES = ("/Applications/Google Chrome.app/Contents/MacOS/Google Chrome",
+           "/Applications/Chromium.app/Contents/MacOS/Chromium",
+           "/Applications/Microsoft Edge.app/Contents/MacOS/Microsoft Edge",
+           "/Applications/Brave Browser.app/Contents/MacOS/Brave Browser",
+           "google-chrome", "chromium", "chromium-browser", "microsoft-edge")
+
+
+def to_png(svg_path: Path) -> Path | None:
+    """Best effort, no new dependencies: rsvg-convert, a headless Chrome-family browser, or cairosvg."""
+    png = svg_path.with_suffix(".png")
+    if shutil.which("rsvg-convert"):
+        if subprocess.run(["rsvg-convert", "-w", str(W), "-o", str(png), str(svg_path)], capture_output=True).returncode == 0:
+            return png
+    for browser in CHROMES:
+        exe = browser if Path(browser).exists() else shutil.which(browser)
+        if not exe:
+            continue
+        png.unlink(missing_ok=True)
+        with tempfile.TemporaryDirectory() as profile:
+            proc = subprocess.Popen([exe, "--headless", "--disable-gpu", "--hide-scrollbars", "--no-first-run",
+                                     "--no-default-browser-check", "--disable-extensions", f"--user-data-dir={profile}",
+                                     f"--window-size={W},{H}", f"--screenshot={png}", svg_path.resolve().as_uri()],
+                                    stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL, stdin=subprocess.DEVNULL)
+            # Chrome sometimes writes the screenshot and then doesn't exit: wait for the file, then stop it
+            deadline = time.time() + 60
+            while time.time() < deadline and proc.poll() is None and not (png.exists() and png.stat().st_size > 0):
+                time.sleep(0.25)
+            time.sleep(0.5)
+            if proc.poll() is None:
+                proc.kill()
+                proc.wait(timeout=10)
+        if png.exists() and png.stat().st_size > 0:
+            return png
+    try:
+        import cairosvg  # type: ignore
+
+        cairosvg.svg2png(url=str(svg_path), write_to=str(png), output_width=W)
+        return png
+    except Exception:
+        return None
+
+
+def write(n: CardNumbers, path: Path) -> tuple[Path, Path | None]:
+    path = path.with_suffix(".svg")
+    path.write_text(svg(n))
+    return path, to_png(path)

{aimpg-0.6.0 → aimpg-0.6.2}/aimpg/cli.py

@@ -53,7 +53,10 @@ def _analyze(args):
 def main(argv: list[str] | None = None) -> int:
     parser = argparse.ArgumentParser(prog="aimpg", description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
     sub = parser.add_subparsers(dest="command", required=True)
-    _common(sub.add_parser("report", help="print the energy receipt"), 30)
+    report_p = sub.add_parser("report", help="print the energy receipt")
+    _common(report_p, 30)
+    report_p.add_argument("--share", type=Path, nargs="?", const=Path("aimpg-receipt.svg"), default=None, metavar="FILE",
+                          help="also write a share card (totals only; SVG, plus PNG where possible)")
 
     pr = sub.add_parser("pr", help="AI energy and cost of this branch's commits, as a PR comment")
     _common(pr, 90)
@@ -98,6 +101,9 @@ def main(argv: list[str] | None = None) -> int:
     verify_mod.add_parser(sub)
     scoreboard_mod.add_parsers(sub)
     defaults_mod.add_parser(sub)
+    from aimpg.replay import study_cli
+
+    study_cli.add_parser(sub)
     args = parser.parse_args(argv)
     if args.command == "replay":
         return replay_cli.main(args)
@@ -107,6 +113,10 @@ def main(argv: list[str] | None = None) -> int:
         return scoreboard_mod.main(args)
     if args.command == "defaults":
         return defaults_mod.main(args)
+    if args.command == "study":
+        from aimpg.replay import study_cli
+
+        return study_cli.main(args)
     if args.command in ("statusline", "hook", "live"):
         from aimpg import live as live_mod
 
@@ -219,6 +229,17 @@ def main(argv: list[str] | None = None) -> int:
     ledger.record(task_energy(attribution.tasks))
     judged = durable.judge(ledger.load(), now)
     sys.stdout.write(render(parsed, attribution, since, now, judged))
+    if args.share:
+        from aimpg import card
+
+        n = card.numbers(parsed, attribution, since, now, judged)
+        try:
+            svg_path, png_path = card.write(n, args.share)
+        except Exception as exc:  # the receipt above is already printed; a renderer problem must not hide it
+            svg_path, png_path = args.share.with_suffix(".svg"), None
+            print(f"\n(Couldn't render the PNG: {exc}; the SVG is still written.)")
+        print(f"\nShare card: {png_path or svg_path} (totals only: no repo names, commit messages or code)")
+        print(f"Post text:  {card.post_text(n)}")
     return 0
 
 

{aimpg-0.6.0 → aimpg-0.6.2}/aimpg/coach.py

@@ -12,9 +12,12 @@ the receipt, so it's never generic advice:
        request after c2 re-reads:  base + (everything up to c2) + new work
        fresh session after c2:     base + new work
 
-   The carried-over part is removed from that request's cache reads (and from
-   the context each output token attends over). It's an upper bound on the
-   saving: some of that history is genuinely useful to the next task.
+   The carried-over part is removed from that request's cache reads. What's
+   measured is the share of tokens carried over; the saving is an upper bound,
+   because a fresh session has to rebuild some context (re-reading files,
+   CLAUDE.md, a summary), which this doesn't charge. In energy it depends on
+   what re-reading cached context costs, so it's given as a range across the
+   energy assumptions, from nearly nothing (cache still in fast memory) to a lot.
 
 2. Model size. Requests on large-class models (Opus, Fable) re-priced and
    re-estimated as if they had run on a mid-class model (Sonnet). Also an upper
@@ -42,7 +45,9 @@ class Tip:
     action: str  # what to do
     saving_wh: WhRange
     saving_usd: float
-    share: float  # of the window's energy (mid estimate)
+    share: float  # of the window's energy (mid estimate), for ordering
+    saving_text: str = ""  # how the saving is stated, when a single % would overclaim
+    caveat: str = ""
 
 
 def _sum(requests: list[Request]) -> tuple[WhRange, float]:
@@ -64,6 +69,7 @@ def fresh_session_tip(requests: list[Request], attribution: Attribution) -> Tip
         by_session[r.session_id].append(r)
 
     actual, simulated = [], []
+    carried_tokens = 0
     for session, reqs in by_session.items():
         reqs.sort(key=lambda r: r.ts)
         main = [r for r in reqs if not r.is_sidechain]
@@ -83,22 +89,32 @@ def fresh_session_tip(requests: list[Request], attribution: Attribution) -> Tip
                 simulated.append(r)
                 continue
             cut = min(carried_at[i], r.usage.cache_read)
+            carried_tokens += cut
             simulated.append(replace(r, usage=replace(r.usage, cache_read=r.usage.cache_read - cut)))
     (a_wh, a_usd), (s_wh, s_usd) = _sum(actual), _sum(simulated)
     saved = WhRange(a_wh.low - s_wh.low, a_wh.high - s_wh.high)
     if a_wh.mid == 0 or saved.mid / a_wh.mid < 0.02:
         return None
     share = saved.mid / a_wh.mid
+    tokens = sum(r.usage.ctx_len + r.usage.output for r in actual)
+    lo, hi = sorted((saved.low / a_wh.low if a_wh.low else 0.0, saved.high / a_wh.high if a_wh.high else 0.0))
+    usd = a_usd - s_usd
     return Tip(
         title="Start a fresh session after each commit",
-        measured=f"{share:.0%} of your AI energy went to re-reading conversation from before your last commit",
+        measured=f"{carried_tokens / tokens:.0%} of the tokens your agents processed were conversation carried over from before your last commit",
         action="After committing, start a new session (or /clear) for the next task, and give it a one-line summary if needed",
         saving_wh=saved,
-        saving_usd=a_usd - s_usd,
+        saving_usd=usd,
         share=share,
+        saving_text=f"up to {lo:.0%}–{hi:.0%} less energy, up to {_usd_short(usd)}",
+        caveat="A fresh session has to rebuild some context, which isn't counted here, so the real saving is smaller",
     )
 
 
+def _usd_short(x: float) -> str:
+    return f"${x:,.0f}" if x >= 100 else f"${x:,.2f}"
+
+
 def model_size_tip(requests: list[Request]) -> Tip | None:
     large = [r for r in requests if model_class(r.model)[0] == "large"]
     if not large:

{aimpg-0.6.0 → aimpg-0.6.2}/aimpg/cost.py

@@ -31,6 +31,9 @@ def usage_cost(usage: Usage, model: str) -> float | None:
     p = price_for(model)
     if p is None:
         return None
+    tier = p.get("long_prompt")
+    if tier and usage.ctx_len > tier["over_tokens"]:  # e.g. Haiku 5.5: the whole request at the higher prices
+        p = tier
     one_hour = min(usage.cache_write_1h, usage.cache_write)
     return (
         usage.fresh_in * p["input"]

{aimpg-0.6.0 → aimpg-0.6.2}/aimpg/live.py

@@ -20,6 +20,7 @@ Nothing here talks to the network or changes how the agent works.
 from __future__ import annotations
 
 import json
+import shlex
 import os
 import statistics
 import subprocess
@@ -259,7 +260,7 @@ def status_line(data: dict, state: SessionState, usual: float | None) -> str:
         else:
             parts.append(f"ctx {_k(ctx)}")
         if share >= CLEAR_HINT_SHARE and len(state.task) <= 3:
-            parts.append(f"/clear ≈ -{share:.0%} per request")
+            parts.append("next task? /clear")
     five = ((data.get("rate_limits") or {}).get("five_hour") or {}).get("used_percentage")
     if isinstance(five, (int, float)):
         parts.append(f"5h {five:.0f}%")
@@ -270,7 +271,8 @@ def commit_note(done: dict) -> str:
     msg = f"aimpg: that commit cost {_usd(done['cost'])} over {done['requests']} AI requests."
     share = done.get("stale_share", 0.0)
     if share >= CLEAR_HINT_SHARE:
-        msg += f" {share:.0%} of the context is from earlier work: /clear before the next task saves ~{share:.0%} per request."
+        msg += (f" {share:.0%} of the context is from earlier work. If the next task doesn't need it, /clear"
+                " (with a one-line summary) stops re-reading it on every request.")
     return msg
 
 
@@ -338,9 +340,17 @@ PREVIOUS = LIVE_DIR / "previous_statusline.json"
 OURS = ("aimpg statusline", "aimpg hook post-commit")
 
 
+def _write_json(path: Path, data: dict) -> None:
+    """Write via a temp file and rename, so Claude Code never reads a half-written settings file."""
+    tmp = path.with_name(f".{path.name}.aimpg-tmp")
+    tmp.write_text(json.dumps(data, indent=2) + "\n")
+    os.replace(tmp, path)
+
+
 def planned_settings(current: dict, exe: str) -> dict:
     """The settings after install: our status line (wrapping any existing one) + a commit hook."""
     new = json.loads(json.dumps(current))
+    exe = shlex.quote(exe)  # a path with spaces or quotes must stay one argument
     new["statusLine"] = {"type": "command", "command": f"{exe} statusline"}
     hooks = new.setdefault("hooks", {}).setdefault("PostToolUse", [])
     if not any(h.get("command", "").endswith("hook post-commit") for e in hooks for h in e.get("hooks", [])):
@@ -366,7 +376,7 @@ def install(settings: Path = SETTINGS, exe: str = "aimpg", *, confirm=input) ->
         backup = settings.with_suffix(f".json.aimpg-backup-{int(time.time())}")
         backup.write_text(settings.read_text())
     settings.parent.mkdir(parents=True, exist_ok=True)
-    settings.write_text(json.dumps(new, indent=2) + "\n")
+    _write_json(settings, new)
     return "Installed. It shows up after the next AI message. Undo any time with `aimpg live uninstall`."
 
 
@@ -388,7 +398,7 @@ def uninstall(settings: Path = SETTINGS) -> str:
             current["hooks"].pop("PostToolUse")
             if not current["hooks"]:
                 current.pop("hooks")
-    settings.write_text(json.dumps(current, indent=2) + "\n")
+    _write_json(settings, current)
     PREVIOUS.unlink(missing_ok=True)
     return "Removed. Your previous status line (if any) is back."
 

{aimpg-0.6.0 → aimpg-0.6.2}/aimpg/prices.json

@@ -1,6 +1,6 @@
 {
-  "version": "2026-10-03b",
-  "source": "https://platform.claude.com/docs/en/about-claude/pricing (Model pricing table, fetched 2026-10-03)",
+  "version": "2026-10-11",
+  "source": "https://platform.claude.com/docs/en/about-claude/pricing (Model pricing table, fetched 2026-10-11). Claude Haiku 5.5 is priced by prompt length: a request whose prompt (all input incl. cache reads and writes) is over 100,000 tokens pays the long_prompt prices.",
   "unit": "USD per million tokens",
   "note": "Standard (global) API prices. For subscription users this is the API-equivalent value of the work, not a bill.",
   "models": {
@@ -101,6 +101,21 @@
       "cache_write_1h": 1.75,
       "cache_read": 0.175,
       "output": 14.0
+    },
+    "claude-haiku-5-5": {
+      "input": 0.1,
+      "cache_write_5m": 0.125,
+      "cache_write_1h": 0.2,
+      "cache_read": 0.01,
+      "output": 0.5,
+      "long_prompt": {
+        "over_tokens": 100000,
+        "input": 0.5,
+        "cache_write_5m": 0.625,
+        "cache_write_1h": 1.0,
+        "cache_read": 0.05,
+        "output": 2.5
+      }
     }
   },
   "openai_source": "https://developers.openai.com/api/docs/pricing (Standard tier, fetched 2026-10-03). gpt-5.3-codex lists no cache-write price; writes are priced as input."

{aimpg-0.6.0 → aimpg-0.6.2}/aimpg/receipt.py

@@ -59,7 +59,7 @@ def summary(in_window, energies: list[TaskEnergy]) -> list[str]:
         "YOUR AI CODING",
         f"  Energy   {_fmt_wh(everything)}",
         f"           ≈ {equivalence.everyday(everything)}",
-        f"  Money    {_usd(usd)} API-equivalent (Anthropic's and OpenAI's published prices"
+        f"  Money    {_usd(usd)} at API list prices (Anthropic's and OpenAI's; a subscription costs less"
         + (f"; {unknown} requests from unpriced models left out)" if unknown else ")"),
         f"  Output   {len(energies)} commits made with AI help",
     ]
@@ -134,8 +134,10 @@ def render(parsed: ParseResult, attribution: Attribution, since: float, now: flo
             add("")
             add("WHAT WOULD HAVE SAVED THE MOST (measured on your logs; upper bounds that overlap)")
             for i, t in enumerate(found, 1):
-                add(f"  {i}. {t.title}: up to {t.share:.0%} less energy, {_usd(t.saving_usd)}")
+                add(f"  {i}. {t.title}: {t.saving_text or f'up to {t.share:.0%} less energy, {_usd(t.saving_usd)}'}")
                 add(f"     {t.measured}.")
+                if t.caveat:
+                    add(f"     {t.caveat}.")
                 add(f"     ≈ {equivalence.everyday(t.saving_wh)}")
                 add(f"     → {t.action}.")
         if judged is not None: