compact-code 0.1.0__tar.gz → 0.2.1__tar.gz

{compact_code-0.1.0 → compact_code-0.2.1}/PKG-INFO

@@ -1,7 +1,10 @@
 Metadata-Version: 2.4
 Name: compact-code
-Version: 0.1.0
+Version: 0.2.1
 Summary: Dense Python for AI agents, readable view for humans. Same logic, ~30-55% fewer tokens.
+Project-URL: Homepage, https://github.com/EmmanuelFreund/compact-code
+Project-URL: Repository, https://github.com/EmmanuelFreund/compact-code
+Project-URL: Issues, https://github.com/EmmanuelFreund/compact-code/issues
 Author-email: Emmanuel Freund <freund.emmanuel@gmail.com>
 License: MIT
 License-File: LICENSE
@@ -61,10 +64,22 @@ Codebase density gain: -19% to -41% tokens depending on the project (less if doc
 | `compact-code compact --check` | dry run: report savings without writing |
 | `compact-code compact --keep-docstrings` | keep docstrings (use when they are functional: CLI help text, doctests, flit) |
 | `compact-code expand <file>` | print a readable 4-space-indented view (`--write` to rewrite in place) |
-| `compact-code stats` | tokens and $ saved per full codebase read |
+| `compact-code stats` | tokens and $ saved: per full read + cumulative real agent reads |
+| `compact-code install-hook` | install a Claude Code hook that counts **real** savings on every agent read (`--project` for project-level) |
 
 Install `compact-code[exact]` for exact token counts (tiktoken).
 
+## The live savings counter
+
+```
+compact-code install-hook    # one-time, hooks into Claude Code
+# ... let your agent work ...
+compact-code stats
+# Agent savings so far: 142 reads of compacted files, 87,310 tokens saved (~$0.26).
+```
+
+The hook fires on every `Read` Claude Code performs; if the file is in this project's compaction manifest, the per-file saving (prorated for partial reads) is credited to a local ledger. No network, no telemetry — everything stays in `.compact-code.json`.
+
 ## The honest fine print
 
 - The gain is proportional to how much code your agent actually **reads**. Exploration-heavy and read-heavy sessions save the most; one-file quick fixes save nothing.

{compact_code-0.1.0 → compact_code-0.2.1}/README.md

@@ -43,10 +43,22 @@ Codebase density gain: -19% to -41% tokens depending on the project (less if doc
 | `compact-code compact --check` | dry run: report savings without writing |
 | `compact-code compact --keep-docstrings` | keep docstrings (use when they are functional: CLI help text, doctests, flit) |
 | `compact-code expand <file>` | print a readable 4-space-indented view (`--write` to rewrite in place) |
-| `compact-code stats` | tokens and $ saved per full codebase read |
+| `compact-code stats` | tokens and $ saved: per full read + cumulative real agent reads |
+| `compact-code install-hook` | install a Claude Code hook that counts **real** savings on every agent read (`--project` for project-level) |
 
 Install `compact-code[exact]` for exact token counts (tiktoken).
 
+## The live savings counter
+
+```
+compact-code install-hook    # one-time, hooks into Claude Code
+# ... let your agent work ...
+compact-code stats
+# Agent savings so far: 142 reads of compacted files, 87,310 tokens saved (~$0.26).
+```
+
+The hook fires on every `Read` Claude Code performs; if the file is in this project's compaction manifest, the per-file saving (prorated for partial reads) is credited to a local ledger. No network, no telemetry — everything stays in `.compact-code.json`.
+
 ## The honest fine print
 
 - The gain is proportional to how much code your agent actually **reads**. Exploration-heavy and read-heavy sessions save the most; one-file quick fixes save nothing.

{compact_code-0.1.0 → compact_code-0.2.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "compact-code"
-version = "0.1.0"
+version = "0.2.1"
 description = "Dense Python for AI agents, readable view for humans. Same logic, ~30-55% fewer tokens."
 readme = "README.md"
 requires-python = ">=3.9"
@@ -19,6 +19,11 @@ classifiers = [
     "Topic :: Software Development :: Code Generators",
 ]
 
+[project.urls]
+Homepage = "https://github.com/EmmanuelFreund/compact-code"
+Repository = "https://github.com/EmmanuelFreund/compact-code"
+Issues = "https://github.com/EmmanuelFreund/compact-code/issues"
+
 [project.optional-dependencies]
 exact = ["tiktoken>=0.5"]
 

{compact_code-0.1.0 → compact_code-0.2.1}/src/compact_code/__init__.py

@@ -3,5 +3,5 @@
 from .compactor import compact_source, verify_equivalence
 from .expand import expand_source
 
-__version__ = "0.1.0"
+__version__ = "0.2.1"
 __all__ = ["compact_source", "verify_equivalence", "expand_source", "__version__"]

{compact_code-0.1.0 → compact_code-0.2.1}/src/compact_code/cli.py

@@ -6,7 +6,7 @@ import json
 import os
 import sys
 
-from . import compactor, expand, tokens
+from . import compactor, expand, hooks, ledger, tokens
 
 MANIFEST = ".compact-code.json"
 EXCLUDED_DIRS = {
@@ -115,11 +115,43 @@ def cmd_stats(args):
     print(f"Codebase: {before:,} -> {after:,} tokens ({pct:.1f}% smaller, {len(files)} files)")
     print(f"Every full read of this codebase by your agent now saves "
           f"{saved:,} tokens (~${dollars:.2f} at ${args.price}/Mtok input).")
+    led = manifest.get("ledger")
+    if led and led.get("reads"):
+        led_saved = int(led["tokens_saved"])
+        led_dollars = led_saved / 1_000_000 * args.price
+        print(f"Agent savings so far: {led['reads']:,} reads of compacted files, "
+              f"{led_saved:,} tokens saved (~${led_dollars:.2f}).")
+    else:
+        print("No agent reads recorded yet. Run `compact-code install-hook` to start "
+              "counting real savings (Claude Code).")
     print("Sessions that read a lot of code (exploration, onboarding, refactors) "
           "benefit the most; surgical one-file fixes benefit little.")
     return 0
 
 
+def cmd_hook(args):
+    try:
+        payload = json.load(sys.stdin)
+        tool_input = payload.get("tool_input", {})
+        path = tool_input.get("file_path")
+        if path and path.endswith(".py"):
+            ledger.record_read(path, limit=tool_input.get("limit"))
+    except Exception:
+        pass
+    return 0
+
+
+def cmd_install_hook(args):
+    path, installed = hooks.install(project=args.project)
+    if installed:
+        print(f"Hook installed in {path}.")
+        print("Claude Code will now credit real savings on every read of a "
+              "compacted file. Restart Claude Code (or open /hooks) to activate.")
+    else:
+        print(f"Hook already installed in {path}.")
+    return 0
+
+
 def main(argv=None):
     parser = argparse.ArgumentParser(
         prog="compact-code",
@@ -145,6 +177,15 @@ def main(argv=None):
                    help="USD per million input tokens (default: 3.0)")
     p.set_defaults(func=cmd_stats)
 
+    p = sub.add_parser("hook", help="(internal) Claude Code PostToolUse hook, reads JSON on stdin")
+    p.set_defaults(func=cmd_hook)
+
+    p = sub.add_parser("install-hook",
+                       help="install the Claude Code hook that counts real savings")
+    p.add_argument("--project", action="store_true",
+                   help="install in ./.claude/settings.json instead of ~/.claude/settings.json")
+    p.set_defaults(func=cmd_install_hook)
+
     args = parser.parse_args(argv)
     return args.func(args)
 

compact_code-0.2.1/src/compact_code/hooks.py

@@ -0,0 +1,49 @@
+"""Install the Claude Code hook that feeds the savings ledger."""
+
+import json
+import os
+import shutil
+
+HOOK_COMMAND = "compact-code hook"
+
+
+def _hook_command():
+    """Absolute path to the executable: hooks run in shells whose PATH may differ."""
+    exe = shutil.which("compact-code")
+    if exe:
+        return f'"{exe.replace(os.sep, "/")}" hook'
+    return HOOK_COMMAND
+
+
+def settings_path(project=False):
+    if project:
+        return os.path.join(".claude", "settings.json")
+    return os.path.join(os.path.expanduser("~"), ".claude", "settings.json")
+
+
+def install(project=False):
+    """Merge the PostToolUse/Read hook into Claude Code settings.
+
+    Returns (path, installed) — installed is False if it was already there.
+    """
+    path = settings_path(project)
+    settings = {}
+    if os.path.exists(path):
+        with open(path, encoding="utf-8") as f:
+            content = f.read().strip()
+        if content:
+            settings = json.loads(content)
+    post = settings.setdefault("hooks", {}).setdefault("PostToolUse", [])
+    for matcher in post:
+        for hook in matcher.get("hooks", []):
+            cmd = hook.get("command", "")
+            if "compact-code" in cmd and cmd.endswith(" hook"):
+                return path, False
+    post.append({
+        "matcher": "Read",
+        "hooks": [{"type": "command", "command": _hook_command()}],
+    })
+    os.makedirs(os.path.dirname(path), exist_ok=True)
+    with open(path, "w", encoding="utf-8", newline="\n") as f:
+        json.dump(settings, f, indent=2)
+    return path, True

compact_code-0.2.1/src/compact_code/ledger.py

@@ -0,0 +1,52 @@
+"""Cumulative savings ledger: records real agent reads of compacted files."""
+
+import json
+import os
+
+MANIFEST = ".compact-code.json"
+
+
+def find_manifest(start_dir):
+    """Walk up from start_dir looking for a manifest. Returns its path or None."""
+    current = os.path.abspath(start_dir)
+    while True:
+        candidate = os.path.join(current, MANIFEST)
+        if os.path.isfile(candidate):
+            return candidate
+        parent = os.path.dirname(current)
+        if parent == current:
+            return None
+        current = parent
+
+
+def record_read(file_path, limit=None):
+    """Credit the savings of one agent read of file_path, if it was compacted.
+
+    Returns the tokens credited (0 if the file is not in any manifest).
+    """
+    file_path = os.path.abspath(file_path)
+    manifest_path = find_manifest(os.path.dirname(file_path))
+    if manifest_path is None:
+        return 0
+    with open(manifest_path, encoding="utf-8") as f:
+        manifest = json.load(f)
+    root = os.path.dirname(manifest_path)
+    key = os.path.relpath(file_path, root).replace("\\", "/")
+    entry = manifest.get("files", {}).get(key)
+    if entry is None:
+        return 0
+    saved = entry["before"] - entry["after"]
+    if limit is not None:
+        try:
+            with open(file_path, encoding="utf-8", errors="replace") as f:
+                total_lines = sum(1 for _ in f)
+            if total_lines > 0:
+                saved = saved * min(1.0, limit / total_lines)
+        except OSError:
+            pass
+    ledger = manifest.setdefault("ledger", {"reads": 0, "tokens_saved": 0})
+    ledger["reads"] += 1
+    ledger["tokens_saved"] = round(ledger["tokens_saved"] + saved, 1)
+    with open(manifest_path, "w", encoding="utf-8", newline="\n") as f:
+        json.dump(manifest, f, indent=1)
+    return saved

compact_code-0.2.1/tests/test_ledger.py

@@ -0,0 +1,102 @@
+import io
+import json
+
+import pytest
+
+from compact_code import cli, hooks, ledger
+
+SRC = "def f(x: int) -> int:\n    \"\"\"Doubles.\"\"\"\n    # comment\n    return x * 2\n"
+
+
+@pytest.fixture
+def compacted(tmp_path, monkeypatch):
+    (tmp_path / "pkg").mkdir()
+    (tmp_path / "pkg" / "mod.py").write_text(SRC, encoding="utf-8")
+    monkeypatch.chdir(tmp_path)
+    cli.main(["compact"])
+    return tmp_path
+
+
+def _ledger(root):
+    manifest = json.loads((root / cli.MANIFEST).read_text(encoding="utf-8"))
+    return manifest.get("ledger")
+
+
+def test_record_read_accumulates(compacted):
+    target = compacted / "pkg" / "mod.py"
+    saved1 = ledger.record_read(str(target))
+    saved2 = ledger.record_read(str(target))
+    assert saved1 == saved2 > 0
+    led = _ledger(compacted)
+    assert led["reads"] == 2
+    assert led["tokens_saved"] == pytest.approx(saved1 * 2)
+
+
+def test_record_read_unknown_file(compacted):
+    other = compacted / "pkg" / "other.py"
+    other.write_text("x = 1\n", encoding="utf-8")
+    assert ledger.record_read(str(other)) == 0
+    assert _ledger(compacted) is None
+
+
+def test_record_read_no_manifest(tmp_path):
+    f = tmp_path / "a.py"
+    f.write_text("x = 1\n", encoding="utf-8")
+    assert ledger.record_read(str(f)) == 0
+
+
+def test_record_read_partial_prorated(compacted):
+    target = compacted / "pkg" / "mod.py"
+    full = ledger.record_read(str(target))
+    total_lines = len(target.read_text(encoding="utf-8").splitlines())
+    partial = ledger.record_read(str(target), limit=1)
+    assert 0 < partial < full
+    assert partial == pytest.approx(full / total_lines)
+
+
+def test_hook_command_credits_read(compacted, monkeypatch):
+    target = compacted / "pkg" / "mod.py"
+    payload = {"tool_name": "Read", "tool_input": {"file_path": str(target)}}
+    monkeypatch.setattr("sys.stdin", io.StringIO(json.dumps(payload)))
+    assert cli.main(["hook"]) == 0
+    assert _ledger(compacted)["reads"] == 1
+
+
+def test_hook_command_survives_garbage(compacted, monkeypatch):
+    monkeypatch.setattr("sys.stdin", io.StringIO("not json"))
+    assert cli.main(["hook"]) == 0
+
+
+def test_stats_shows_cumulative(compacted, capsys):
+    ledger.record_read(str(compacted / "pkg" / "mod.py"))
+    capsys.readouterr()
+    cli.main(["stats"])
+    out = capsys.readouterr().out
+    assert "Agent savings so far: 1" in out
+
+
+def test_install_hook_project(compacted, capsys):
+    assert cli.main(["install-hook", "--project"]) == 0
+    settings = json.loads(
+        (compacted / ".claude" / "settings.json").read_text(encoding="utf-8"))
+    cmds = [h["command"]
+            for m in settings["hooks"]["PostToolUse"] for h in m["hooks"]]
+    assert any("compact-code" in c and c.endswith(" hook") for c in cmds)
+
+
+def test_install_hook_idempotent_and_merging(compacted):
+    claude = compacted / ".claude"
+    claude.mkdir()
+    existing = {"permissions": {"allow": ["Bash(git *)"]},
+                "hooks": {"PostToolUse": [
+                    {"matcher": "Write", "hooks": [{"type": "command", "command": "echo hi"}]}]}}
+    (claude / "settings.json").write_text(json.dumps(existing), encoding="utf-8")
+    cli.main(["install-hook", "--project"])
+    cli.main(["install-hook", "--project"])
+    settings = json.loads((claude / "settings.json").read_text(encoding="utf-8"))
+    assert settings["permissions"]["allow"] == ["Bash(git *)"]
+    post = settings["hooks"]["PostToolUse"]
+    assert len(post) == 2
+    cmds = [h["command"] for m in post for h in m["hooks"]]
+    ours = [c for c in cmds if "compact-code" in c and c.endswith(" hook")]
+    assert len(ours) == 1 and "echo hi" in cmds

{compact_code-0.1.0 → compact_code-0.2.1}/uv.lock

@@ -138,7 +138,7 @@ wheels = [
 
 [[package]]
 name = "compact-code"
-version = "0.1.0"
+version = "0.2.1"
 source = { editable = "." }
 
 [package.optional-dependencies]