aimpg 0.1.0__tar.gz

aimpg-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,17 @@
+name: publish
+on:
+  push:
+    tags: ["v*"]
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write  # PyPI trusted publishing, no API token stored
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+      - run: git config --global user.email ci@example.com && git config --global user.name CI
+      - run: uv run --group dev pytest -q
+      - run: uv build
+      - run: uv publish --trusted-publishing always

aimpg-0.1.0/.github/workflows/test.yml

@@ -0,0 +1,17 @@
+name: test
+on:
+  push:
+    branches: [main]
+  pull_request:
+jobs:
+  test:
+    strategy:
+      matrix:
+        os: [ubuntu-latest, macos-latest]
+        python: ["3.10", "3.13"]
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+      - run: git config --global user.email ci@example.com && git config --global user.name CI
+      - run: uv run --python ${{ matrix.python }} --group dev pytest -q

aimpg-0.1.0/.gitignore

@@ -0,0 +1,6 @@
+.venv/
+__pycache__/
+*.egg-info/
+.pytest_cache/
+dist/
+evals/data/

aimpg-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kumar Ganduri
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

aimpg-0.1.0/PKG-INFO

@@ -0,0 +1,93 @@
+Metadata-Version: 2.5
+Name: aimpg
+Version: 0.1.0
+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
+Author: Kumar Ganduri
+License-Expression: MIT
+License-File: LICENSE
+Keywords: ai,carbon,claude-code,energy,llm,sustainability
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# aimpg
+
+**Miles per gallon for AI coding.** Find out how much energy your AI coding agent used, and which of your commits it went into.
+
+```bash
+uvx aimpg report
+```
+
+Example output:
+
+```
+AI energy in window .......................... 6.99 kWh – 57.39 kWh  (4,744 requests)
+  matched to commits ......................... 5.87 kWh – 47.96 kWh  (223 commits: 223 exact, 0 fuzzy, 0 grace)
+  exact-match share of in-repo energy: 84%, any match: 84%
+  no commit from this session yet ............ 1.11 kWh – 9.38 kWh  (609 requests)
+
+Median direct energy per kept commit: 27.2 Wh – 212.9 Wh
+
+Most energy-hungry commits:
+       213.2 Wh – 1.71 kWh  my-app 2ef4297 fix: date parsing for day-first locales
+```
+
+## What it does
+
+`aimpg` reads the Claude Code session logs already on your machine (`~/.claude/projects`). It works out which AI requests produced which of your git commits, and prints an energy receipt:
+
+- **Energy per kept commit**, as a low–high range in Wh
+- **Discarded work**: energy that went into commits that never reached your main branch
+- **The most and least energy-hungry commits**
+- **Unmatched energy**: work that produced no commit (yet), shown openly rather than hidden
+
+## Privacy
+
+Everything runs locally. `aimpg report` makes no network calls (unless you pass `--fetch`, which runs `git fetch`). Nothing is uploaded, and your code and prompts never leave your machine.
+
+## How it matches requests to commits
+
+1. **Exact:** when the agent runs `git commit`, the commit lands while that tool call is running. We match commits to those call windows, including slow commits where pre-commit hooks run for minutes.
+2. **Time segments:** within a session, the requests made since the previous commit belong to the next one, in whatever repo it lands. A 2h+ break starts a new work burst. Only the final burst counts as the commit's *direct* energy, and earlier bursts are shown as *lead-up*.
+3. **Fuzzy (fallback):** commits you make by hand are matched only if you authored them (your `user.email`), within 2 hours of the session, and only if they touch files the session edited. Teammates' commits are never claimed.
+
+On the author's own history, a hand-labeled check of 20 commits matched 20/20 to the right session (`evals/`).
+
+## How energy is estimated
+
+Model sizes for Claude aren't public, so every number is a **range**, never a single figure. The formula is physical, not price-based:
+
+- **Prefill:** compute energy for every fresh or cache-written input token.
+- **Decode:** each output token re-reads the model weights and the whole KV cache, so long contexts make every output token more expensive.
+- **Cache reads:** free when the cache is still in GPU memory, a reload when it isn't.
+- **Overhead:** server and datacenter overhead (PUE) on top.
+
+Per-operation energy comes from [From Tokens to Watt-hours](https://arxiv.org/html/2607.26571v1). Server overhead and PUE come from [EcoLogits](https://ecologits.ai/latest/methodology/llm_inference/). Model-size classes are labeled assumptions. Every coefficient and its source is in [`aimpg/factors.json`](aimpg/factors.json).
+
+## Options
+
+```
+aimpg report [--days 30] [--logs ~/.claude/projects] [--fetch]
+```
+
+## Limits (honest list)
+
+- Claude Code logs only, for now.
+- Work before a 2h+ break is reported as a commit's *lead-up*, separate from its *direct* energy. A multi-day feature that genuinely needed that earlier work will look cheaper in the direct number, so check the lead-up too.
+- Commits less than 7 days old show as `pending` until we can tell whether they were kept.
+
+## Roadmap
+
+Next is `aimpg replay`: rerun your own past commits through different setups (for example Claude Code with and without a token saver) to prove which one saves energy without breaking your tests. See [docs/designs/aimpg-design.md](docs/designs/aimpg-design.md).
+
+## License
+
+MIT

aimpg-0.1.0/README.md

@@ -0,0 +1,73 @@
+# aimpg
+
+**Miles per gallon for AI coding.** Find out how much energy your AI coding agent used, and which of your commits it went into.
+
+```bash
+uvx aimpg report
+```
+
+Example output:
+
+```
+AI energy in window .......................... 6.99 kWh – 57.39 kWh  (4,744 requests)
+  matched to commits ......................... 5.87 kWh – 47.96 kWh  (223 commits: 223 exact, 0 fuzzy, 0 grace)
+  exact-match share of in-repo energy: 84%, any match: 84%
+  no commit from this session yet ............ 1.11 kWh – 9.38 kWh  (609 requests)
+
+Median direct energy per kept commit: 27.2 Wh – 212.9 Wh
+
+Most energy-hungry commits:
+       213.2 Wh – 1.71 kWh  my-app 2ef4297 fix: date parsing for day-first locales
+```
+
+## What it does
+
+`aimpg` reads the Claude Code session logs already on your machine (`~/.claude/projects`). It works out which AI requests produced which of your git commits, and prints an energy receipt:
+
+- **Energy per kept commit**, as a low–high range in Wh
+- **Discarded work**: energy that went into commits that never reached your main branch
+- **The most and least energy-hungry commits**
+- **Unmatched energy**: work that produced no commit (yet), shown openly rather than hidden
+
+## Privacy
+
+Everything runs locally. `aimpg report` makes no network calls (unless you pass `--fetch`, which runs `git fetch`). Nothing is uploaded, and your code and prompts never leave your machine.
+
+## How it matches requests to commits
+
+1. **Exact:** when the agent runs `git commit`, the commit lands while that tool call is running. We match commits to those call windows, including slow commits where pre-commit hooks run for minutes.
+2. **Time segments:** within a session, the requests made since the previous commit belong to the next one, in whatever repo it lands. A 2h+ break starts a new work burst. Only the final burst counts as the commit's *direct* energy, and earlier bursts are shown as *lead-up*.
+3. **Fuzzy (fallback):** commits you make by hand are matched only if you authored them (your `user.email`), within 2 hours of the session, and only if they touch files the session edited. Teammates' commits are never claimed.
+
+On the author's own history, a hand-labeled check of 20 commits matched 20/20 to the right session (`evals/`).
+
+## How energy is estimated
+
+Model sizes for Claude aren't public, so every number is a **range**, never a single figure. The formula is physical, not price-based:
+
+- **Prefill:** compute energy for every fresh or cache-written input token.
+- **Decode:** each output token re-reads the model weights and the whole KV cache, so long contexts make every output token more expensive.
+- **Cache reads:** free when the cache is still in GPU memory, a reload when it isn't.
+- **Overhead:** server and datacenter overhead (PUE) on top.
+
+Per-operation energy comes from [From Tokens to Watt-hours](https://arxiv.org/html/2607.26571v1). Server overhead and PUE come from [EcoLogits](https://ecologits.ai/latest/methodology/llm_inference/). Model-size classes are labeled assumptions. Every coefficient and its source is in [`aimpg/factors.json`](aimpg/factors.json).
+
+## Options
+
+```
+aimpg report [--days 30] [--logs ~/.claude/projects] [--fetch]
+```
+
+## Limits (honest list)
+
+- Claude Code logs only, for now.
+- Work before a 2h+ break is reported as a commit's *lead-up*, separate from its *direct* energy. A multi-day feature that genuinely needed that earlier work will look cheaper in the direct number, so check the lead-up too.
+- Commits less than 7 days old show as `pending` until we can tell whether they were kept.
+
+## Roadmap
+
+Next is `aimpg replay`: rerun your own past commits through different setups (for example Claude Code with and without a token saver) to prove which one saves energy without breaking your tests. See [docs/designs/aimpg-design.md](docs/designs/aimpg-design.md).
+
+## License
+
+MIT

aimpg-0.1.0/TODOS.md

@@ -0,0 +1,27 @@
+# TODOS
+
+## Phase 2 (blocking the Phase 2 eng review)
+
+### Replay test leakage + model memorization
+- **What:** Run replays SWE-bench style. Copy the commit's test files into the clone only after the agent finishes, then run them as the judge. Prefer commits newer than the model's training cutoff, or private repos.
+- **Why:** At the parent commit, the commit's own tests don't exist yet. Adding them first leaks the answer; leaving them out means nothing judges pass/fail. Public repos (for example Legwork) may be in the model's training data, which inflates pass rates.
+- **Pros:** Replay pass rates become trustworthy, and the whole leaderboard rests on them.
+- **Cons:** Commits without test changes need another judge (a build check or a judge model), and the cutoff filter shrinks the candidate pool.
+- **Context:** Raised by the outside voice in the 2026-10-01 eng review (finding 2). The design doc's Phase 2 step 2 says "run the repo's tests (or the tests touched by the commit)" without specifying when they're applied.
+- **Depends on:** Phase 1 shipped; Phase 2 eng review.
+
+### Statistical stability gate
+- **What:** Replace "same order across 3 repeats" with a paired per-commit difference (setup A minus setup B) and a bootstrap 95% CI that must exclude 0. Re-cost the replay budget for 10+ commits.
+- **Why:** With 2 setups, "same order 3 times" happens by chance 25% of the time, so the Phase 3 gate would pass on noise.
+- **Pros:** Public rankings only appear when the difference is real.
+- **Cons:** More replays means more token spend; the budget is likely above the current $60-150 estimate.
+- **Context:** Outside voice finding 5, 2026-10-01 eng review. It affects Success Criteria (Phase 2) and the Phase 3 gate.
+- **Depends on:** Phase 2 harness.
+
+### Network-limit spike for the replay sandbox
+- **What:** A time-boxed spike to make the replay container reach only the model API. Docker can't restrict outbound traffic by domain on its own, so it needs an allowlisting CONNECT proxy on an internal Docker network. Check what Legwork's sandbox actually does first.
+- **Why:** The approved sandbox contract (eng review D7) promises "egress limited to the model API" but had no build plan or estimate.
+- **Pros:** Makes the "no GitHub cheating" promise real.
+- **Cons:** TLS through a proxy and the CLI's proxy settings can be fiddly per agent CLI.
+- **Context:** Outside voice finding 7. Estimate: human ~1-2 days / CC ~2 hrs. It should be the first task of Phase 2.
+- **Depends on:** Nothing. It can be spiked any time.

aimpg-0.1.0/aimpg/__init__.py

@@ -0,0 +1 @@
+"""aimpg: real-world energy per solved task for AI coding agents."""

aimpg-0.1.0/aimpg/attribution.py

@@ -0,0 +1,252 @@
+"""Tie AI requests to the commits they produced.
+
+Tier 1 (exact): a Bash tool call ran `git commit`, and a commit in that
+repo has a committer time inside the call's [start, end] interval (±2s
+for whole-second git timestamps). Measured 8/8 on real commit history,
+including a commit whose hooks made it land 147s after the call started.
+
+Energy split (time segments): within one session, the requests made after
+commit k-1 and up to commit k belong to commit k, whatever repo they ran
+in. A session's cwd is often not the repo it works on (absolute paths,
+`cd x && ...`), so grouping by folder would strand requests.
+
+    session s:   r r r [c1 in A] r r r r [c2 in B] r r
+                 └── c1 ───┘  └──── c2 ─────┘  └ no commit yet
+
+Long sessions: a 2h+ pause starts a new work burst. Only the final burst
+before a commit is its direct energy; earlier bursts since the previous
+commit are reported as its "lead-up", never dropped.
+
+Tier 2 (fuzzy): a session's leftover requests (after its last exact
+commit) go to commits in any repo it worked in, made between its first leftover
+request and 2h after its last, authored by you (repo user.email) that touch a file the session edited
+(Edit/Write tools or Bash: sed -i, redirects, mv/cp/rm). Several matches
+split the requests by lines changed. Commits after the session's last
+request are labeled "grace". Built because the first real run showed exact
+matches covered only ~48% of in-repo energy (design gate: 70%).
+"""
+
+from __future__ import annotations
+
+import os
+from collections import defaultdict
+from concurrent.futures import ThreadPoolExecutor
+from dataclasses import dataclass, field
+from typing import Callable
+
+from aimpg.gitkept import DAY, Commit, GitError, KeptChecker, load_commits, repo_root, user_email
+from aimpg.model import CommitCall, ParseResult, Request, Task
+
+PAD = 2.0  # seconds; git timestamps are whole seconds
+GRACE = 2 * 3600.0
+BREAK = 2 * 3600.0  # a pause this long between requests starts a new work burst  # hand commits often land a while after the session goes quiet
+
+NOT_IN_REPO = "not in a git repo (or repo moved/deleted)"
+NO_COMMIT_YET = "no commit from this session yet"
+GIT_FAILED = "git error"
+
+
+@dataclass
+class RepoInfo:
+    ref: str = ""
+    ref_updated: float = 0.0
+    error: str = ""
+
+
+@dataclass
+class Attribution:
+    tasks: list[Task] = field(default_factory=list)
+    unattributed: dict[str, list[Request]] = field(default_factory=dict)
+    repos: dict[str, RepoInfo] = field(default_factory=dict)
+    # session_id -> repos it committed in, ran in, or edited files in
+    session_repos: dict[str, set[str]] = field(default_factory=dict)
+
+
+def attribute(
+    parsed: ParseResult,
+    since: float,
+    now: float,
+    *,
+    refresh: bool = False,
+    find_root: Callable[[str], str | None] = repo_root,
+) -> Attribution:
+    roots: dict[str, str | None] = {}
+
+    def root(path: str) -> str | None:
+        if path not in roots:
+            roots[path] = find_root(path)
+        return roots[path]
+
+    result = Attribution()
+    by_session: dict[str, list[Request]] = defaultdict(list)
+    for r in parsed.requests:
+        if r.ts >= since:
+            by_session[r.session_id].append(r)
+
+    calls_by_session: dict[str, list[tuple[str, CommitCall]]] = defaultdict(list)
+    for call in parsed.commit_calls:
+        end = call.end if call.end is not None else call.start
+        repo = root(call.cwd) if end >= since else None
+        if repo is not None:
+            calls_by_session[call.session_id].append((repo, call))
+
+    # Repos each session may have worked in: where it committed, where its
+    # requests ran, and where the files it edited live. A session's cwd is
+    # often not the repo it worked on (absolute paths, `cd x && ...`).
+    session_repos: dict[str, set[str]] = {}
+    for session, group in by_session.items():
+        repos = {repo for repo, _ in calls_by_session.get(session, [])}
+        repos |= {root(r.cwd) for r in group} - {None}
+        for cwd, path in parsed.files_touched.get(session, set()):
+            full = path if os.path.isabs(path) else os.path.join(cwd, path)
+            repos |= {root(os.path.dirname(os.path.normpath(full)))} - {None}
+        session_repos[session] = repos
+    result.session_repos = session_repos
+
+    commits_by_repo: dict[str, dict[str, Commit]] = {}
+    status_by_repo: dict[str, dict[str, str]] = {}
+    all_repos = sorted(set().union(*session_repos.values()) if session_repos else set())
+    # git subprocesses release the GIL, so repos load in parallel
+    with ThreadPoolExecutor(max_workers=min(8, len(all_repos) or 1)) as pool:
+        loaded = list(pool.map(lambda repo: _load_repo(repo, since - DAY, now, refresh), all_repos))
+    for repo, (commits, statuses, info) in zip(all_repos, loaded):
+        commits_by_repo[repo] = {c.sha: c for c in commits}
+        status_by_repo[repo] = statuses
+        result.repos[repo] = info
+
+    def task_for(repo: str, commit: Commit, attribution: str) -> Task:
+        key = (repo, commit.sha)
+        if key not in tasks:
+            tasks[key] = Task(
+                repo=repo,
+                sha=commit.sha,
+                ts=commit.ts,
+                subject=commit.subject,
+                attribution=attribution,
+                status=status_by_repo.get(repo, {}).get(commit.sha, GIT_FAILED),
+            )
+        return tasks[key]
+
+    # Tier 1: time segments between the session's exact commits, in any repo.
+    tasks: dict[tuple[str, str], Task] = {}
+    leftovers: dict[str, list[Request]] = {}
+    for session, group in by_session.items():
+        group.sort(key=lambda r: r.ts)
+        i = 0
+        for repo, commit in _anchors(calls_by_session.get(session, []), commits_by_repo):
+            task = task_for(repo, commit, "exact")
+            j = i
+            while j < len(group) and group[j].ts <= commit.ts + PAD:
+                j += 1
+            _add_bursts(task, group[i:j], 1.0)
+            i = j
+        if i < len(group):
+            leftovers[session] = group[i:]
+
+    # Tier 2 runs after every exact anchor is known, so a Claude-made commit
+    # is never also claimed as someone's hand-made commit.
+    exact = set(tasks)
+    emails: dict[str, str] = {}
+    for session, rest in leftovers.items():
+        matches: list[tuple[str, Commit]] = []
+        for repo in sorted(session_repos.get(session, set())):
+            if repo not in emails:
+                emails[repo] = user_email(repo)
+            touched = _repo_relative(parsed.files_touched.get(session, set()), repo)
+            matches += [(repo, c) for c in _fuzzy(rest, touched, commits_by_repo.get(repo, {}), exact, repo, emails[repo])]
+        if not matches:
+            reason = NO_COMMIT_YET if session_repos.get(session) else NOT_IN_REPO
+            result.unattributed.setdefault(reason, []).extend(rest)
+            continue
+        total_lines = sum(max(c.lines_changed, 1) for _, c in matches)
+        for repo, commit in matches:
+            task = task_for(repo, commit, "fuzzy" if commit.ts <= rest[-1].ts + PAD else "grace")
+            share = max(commit.lines_changed, 1) / total_lines
+            _add_bursts(task, rest, share)
+
+    result.tasks = sorted(tasks.values(), key=lambda t: t.ts)
+    return result
+
+
+def _add_bursts(task: Task, segment: list[Request], weight: float) -> None:
+    """The final work burst before a commit is its direct cost; earlier bursts are lead-up.
+
+        r r r  ··· 2h+ break ···  r r  ··· 5h break ···  r r r [commit]
+        └ lead-up ┘                └ lead-up ┘           └ direct ┘
+    """
+    start = 0
+    for k in range(1, len(segment)):
+        if segment[k].ts - segment[k - 1].ts >= BREAK:
+            start = k
+    for k, r in enumerate(segment):
+        task.add(r, weight, lead_up=k < start)
+
+
+def _load_repo(repo: str, since: float, now: float, refresh: bool) -> tuple[list[Commit], dict[str, str], RepoInfo]:
+    info = RepoInfo()
+    commits: list[Commit] = []
+    statuses: dict[str, str] = {}
+    try:
+        commits = load_commits(repo, since)
+        checker = KeptChecker(repo, since, now, refresh=refresh, commits=commits)
+        info.ref, info.ref_updated = checker.ref, checker.ref_updated
+        statuses = {sha: s.value for sha, s in checker.classify(commits).items()}
+    except GitError as exc:
+        # Commits may still have loaded (e.g. no default branch): attribute
+        # them, and their status reads "git error" in the receipt.
+        info.error = str(exc)
+    return commits, statuses, info
+
+
+def _repo_relative(touched: set[tuple[str, str]], repo: str) -> set[str]:
+    out = set()
+    for cwd, path in touched:
+        full = os.path.normpath(path if os.path.isabs(path) else os.path.join(cwd, path))
+        full = os.path.realpath(full) if os.path.exists(full) else full
+        rel = os.path.relpath(full, repo)
+        if not rel.startswith(".."):
+            out.add(rel)
+    return out
+
+
+def _fuzzy(
+    rest: list[Request],
+    touched: set[str],
+    commits: dict[str, Commit],
+    exact: set[tuple[str, str]],
+    repo: str,
+    email: str,
+) -> list[Commit]:
+    """Your own hand-made commits in the session's window (+2h grace) that touch files it edited.
+
+    Authorship matters: after a pull, teammates' merged commits land inside the
+    window and touch the same files. Without a configured user.email we don't guess.
+    """
+    if not touched or not email:
+        return []
+    start, end = rest[0].ts - PAD, rest[-1].ts + GRACE
+    return sorted(
+        (
+            c
+            for c in commits.values()
+            if start <= c.ts <= end
+            and c.author_email == email
+            and (repo, c.sha) not in exact
+            and touched & set(c.files)
+        ),
+        key=lambda c: c.ts,
+    )
+
+
+def _anchors(calls: list[tuple[str, CommitCall]], commits_by_repo: dict[str, dict[str, Commit]]) -> list[tuple[str, Commit]]:
+    """(repo, commit) whose time falls inside one of the session's commit calls, oldest first."""
+    found: dict[tuple[str, str], tuple[str, Commit]] = {}
+    for repo, call in calls:
+        start = call.start - PAD
+        end = (call.end if call.end is not None else call.start) + PAD
+        for commit in commits_by_repo.get(repo, {}).values():
+            if start <= commit.ts <= end:
+                found[(repo, commit.sha)] = (repo, commit)
+    return sorted(found.values(), key=lambda rc: rc[1].ts)
+
+

aimpg-0.1.0/aimpg/cli.py

@@ -0,0 +1,40 @@
+"""`aimpg report`: print the fuel receipt for your local Claude Code usage."""
+
+from __future__ import annotations
+
+import argparse
+import sys
+import time
+from pathlib import Path
+
+from aimpg.attribution import attribute
+from aimpg.gitkept import DAY
+from aimpg.logs import DEFAULT_ROOT, iter_log_files, parse_logs
+from aimpg.receipt import render
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(prog="aimpg", description=__doc__)
+    sub = parser.add_subparsers(dest="command", required=True)
+    report = sub.add_parser("report", help="print the energy receipt")
+    report.add_argument("--days", type=int, default=30, help="window size in days (default 30)")
+    report.add_argument("--logs", type=Path, default=DEFAULT_ROOT, help="Claude Code projects dir")
+    report.add_argument("--fetch", action="store_true", help="git fetch each repo first (uses the network)")
+    args = parser.parse_args(argv)
+
+    if args.days <= 0:
+        parser.error("--days must be positive")
+    if not args.logs.is_dir():
+        print(f"No Claude Code logs found at {args.logs}. Nothing to report.")
+        return 0
+
+    now = time.time()
+    since = now - args.days * DAY
+    parsed = parse_logs(iter_log_files(args.logs))
+    attribution = attribute(parsed, since, now, refresh=args.fetch)
+    sys.stdout.write(render(parsed, attribution, since, now))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())