agentledger-cli 0.1.0__tar.gz

agentledger_cli-0.1.0/.gitignore

@@ -0,0 +1,9 @@
+snowflake.local.yml
+output/**
+__pycache__/
+*.pyc
+.venv/
+.venv-dashboard/
+.DS_Store
+client/dist/
+.wrangler/

agentledger_cli-0.1.0/PKG-INFO

@@ -0,0 +1,53 @@
+Metadata-Version: 2.5
+Name: agentledger-cli
+Version: 0.1.0
+Summary: Report Claude Code, Cursor, Gemini CLI and Cortex Code sessions to the AgentLedger Snowflake Native App.
+Requires-Python: >=3.10
+Requires-Dist: snowflake-connector-python>=3.12
+Description-Content-Type: text/markdown
+
+# agentledger
+
+Reports your Claude Code, Cursor CLI, Gemini CLI and Cortex Code sessions to the AgentLedger Snowflake
+Native App, so your team sees agent cost, prompts and tool use per developer, repo, branch and
+pull request.
+
+```bash
+uv tool install agentledger-cli    # or: pipx install agentledger-cli
+agentledger install
+```
+
+`install` checks that your Snowflake connection can report to the app, then sets up every agent
+it finds:
+
+| Agent | What it adds |
+|---|---|
+| Claude Code | `Stop` and `SessionEnd` hooks in `~/.claude/settings.json` |
+| Cursor CLI | `stop` and `sessionEnd` hooks in `~/.cursor/hooks.json` |
+| Gemini CLI | `AfterAgent` and `SessionEnd` hooks in `~/.gemini/settings.json` (`$GEMINI_CLI_HOME` moves it); Gemini CLI runs hooks in trusted folders |
+| Cortex Code | the app's git plugin (`cortex plugin install <APP>.PLUGINS.AGENTLEDGER`); Snowflake records its sessions already |
+
+After each turn the hook queues the session and returns at once. A background process loads it
+into the app over your own connection, at most every two minutes per agent, so a session is
+always stored as yours. Logs are in `~/.cache/agentledger/`.
+
+## Requirements
+
+- A Snowflake connection in `~/.snowflake/connections.toml` that works without a prompt (key
+  pair or cached SSO), whose role an admin has granted the reporter role:
+  `GRANT APPLICATION ROLE AGENTLEDGER.APP_REPORTER TO ROLE <role>;`
+- Python 3.10 or later.
+
+## Options
+
+```bash
+agentledger install --connection work --role DEVELOPER   # pick the connection and role
+agentledger install --only ~/work                        # report only sessions in these folders
+agentledger install --app AGENTLEDGER_PROD               # the app's name, if it isn't AGENTLEDGER
+agentledger status                                       # what's set up, and each agent's latest report
+agentledger upload claude ~/.claude/projects/*/*.jsonl   # report earlier sessions
+agentledger upload gemini ~/.gemini/tmp/*/chats/*.jsonl
+agentledger uninstall                                    # remove the hooks and the plugin
+```
+
+Settings live in `~/.snowflake/agentledger.json`, which the Cortex Code plugin reads too.

agentledger_cli-0.1.0/README.md

@@ -0,0 +1,45 @@
+# agentledger
+
+Reports your Claude Code, Cursor CLI, Gemini CLI and Cortex Code sessions to the AgentLedger Snowflake
+Native App, so your team sees agent cost, prompts and tool use per developer, repo, branch and
+pull request.
+
+```bash
+uv tool install agentledger-cli    # or: pipx install agentledger-cli
+agentledger install
+```
+
+`install` checks that your Snowflake connection can report to the app, then sets up every agent
+it finds:
+
+| Agent | What it adds |
+|---|---|
+| Claude Code | `Stop` and `SessionEnd` hooks in `~/.claude/settings.json` |
+| Cursor CLI | `stop` and `sessionEnd` hooks in `~/.cursor/hooks.json` |
+| Gemini CLI | `AfterAgent` and `SessionEnd` hooks in `~/.gemini/settings.json` (`$GEMINI_CLI_HOME` moves it); Gemini CLI runs hooks in trusted folders |
+| Cortex Code | the app's git plugin (`cortex plugin install <APP>.PLUGINS.AGENTLEDGER`); Snowflake records its sessions already |
+
+After each turn the hook queues the session and returns at once. A background process loads it
+into the app over your own connection, at most every two minutes per agent, so a session is
+always stored as yours. Logs are in `~/.cache/agentledger/`.
+
+## Requirements
+
+- A Snowflake connection in `~/.snowflake/connections.toml` that works without a prompt (key
+  pair or cached SSO), whose role an admin has granted the reporter role:
+  `GRANT APPLICATION ROLE AGENTLEDGER.APP_REPORTER TO ROLE <role>;`
+- Python 3.10 or later.
+
+## Options
+
+```bash
+agentledger install --connection work --role DEVELOPER   # pick the connection and role
+agentledger install --only ~/work                        # report only sessions in these folders
+agentledger install --app AGENTLEDGER_PROD               # the app's name, if it isn't AGENTLEDGER
+agentledger status                                       # what's set up, and each agent's latest report
+agentledger upload claude ~/.claude/projects/*/*.jsonl   # report earlier sessions
+agentledger upload gemini ~/.gemini/tmp/*/chats/*.jsonl
+agentledger uninstall                                    # remove the hooks and the plugin
+```
+
+Settings live in `~/.snowflake/agentledger.json`, which the Cortex Code plugin reads too.

agentledger_cli-0.1.0/pyproject.toml

@@ -0,0 +1,30 @@
+[project]
+name = "agentledger-cli"
+dynamic = ["version"]
+description = "Report Claude Code, Cursor, Gemini CLI and Cortex Code sessions to the AgentLedger Snowflake Native App."
+readme = "README.md"
+requires-python = ">=3.10"
+dependencies = ["snowflake-connector-python>=3.12"]
+
+[project.scripts]
+agentledger = "agentledger.cli:main"
+
+# The distribution is agentledger-cli (agent-ledger on PyPI is someone else's); the module and the
+# command stay agentledger.
+[tool.hatch.build.targets.wheel]
+packages = ["src/agentledger"]
+
+[tool.hatch.version]
+path = "src/agentledger/__init__.py"
+
+# src/agentledger/git_context.py links to the Cortex Code plugin's hook, which the app also ships;
+# the source distribution carries the file itself.
+[tool.hatch.build.targets.sdist]
+exclude = ["src/agentledger/git_context.py"]
+
+[tool.hatch.build.targets.sdist.force-include]
+"../plugin/scripts/git_context.py" = "src/agentledger/git_context.py"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"

agentledger_cli-0.1.0/src/agentledger/__init__.py

@@ -0,0 +1,2 @@
+"""Report coding-agent sessions to the AgentLedger Snowflake Native App."""
+__version__ = "0.1.0"

agentledger_cli-0.1.0/src/agentledger/__main__.py

@@ -0,0 +1,3 @@
+from .cli import main
+
+main()

agentledger_cli-0.1.0/src/agentledger/agents/__init__.py

@@ -0,0 +1,8 @@
+"""The agents agentledger sets up. Each module names itself (ID, NAME) and can tell whether the
+agent is on this machine (detected), whether it's set up (hooked), and install / uninstall
+itself. Agents whose sessions are loaded from the machine also turn a hook call into a job
+(job), find their newest session (newest), and read a session into the app's shape (payload)."""
+from . import claude, cortex, cursor, gemini
+
+AGENTS = {agent.ID: agent for agent in (claude, cursor, gemini, cortex)}
+REPORTERS = {id: agent for id, agent in AGENTS.items() if hasattr(agent, "payload")}

agentledger_cli-0.1.0/src/agentledger/agents/claude.py

@@ -0,0 +1,258 @@
+"""Claude Code sessions, hooked from ~/.claude/settings.json (Stop and SessionEnd).
+
+The transcript is ~/.claude/projects/<project>/<session id>.jsonl. Claude Code writes each API
+response as several lines (thinking, text, tool calls) sharing one message id, with the final
+usage on the last of them; each response becomes one of the app's model calls, with its model,
+token counts and timing. A prompt the developer typed starts a turn (step 0). Background-task
+notices and Claude Code's own meta messages continue the current turn, and local slash commands
+and interrupts are left out. Tool calls keep their arguments and results (clipped); names are
+mapped to the ones the trace's file cards understand, Read results are renumbered in Cortex
+Code's "12... text" form, and Edit results get the "Edit location" line Cortex Code's carry.
+Thinking is not loaded, and <system-reminder> blocks and client harness context (T3 Code's
+attachment notes) are removed from prompts. The session is attributed to the git repository its
+tool calls touched most, else each prompt to the folder it ran in.
+"""
+import json
+import os
+import re
+from collections import OrderedDict
+from datetime import datetime
+from pathlib import Path
+
+from .. import hooks
+from ..repo import PATH_ARGS, repo_of_paths, repo_state, toplevel
+from ..trace import RESULT_CHARS, clip, clip_args, request
+
+ID, NAME = "claude", "Claude Code"
+HOME = Path(os.environ.get("CLAUDE_CONFIG_DIR") or Path.home() / ".claude").expanduser()
+SETTINGS = HOME / "settings.json"
+PROJECTS = HOME / "projects"
+EVENTS = ("Stop", "SessionEnd")
+
+TOOL_NAMES = {"Read": "read", "Edit": "edit", "Write": "write", "Bash": "bash", "Grep": "grep", "Glob": "glob",
+              "Skill": "skill", "Agent": "task", "Task": "task", "WebFetch": "web_fetch", "WebSearch": "web_search",
+              "AskUserQuestion": "ask_user_question", "NotebookEdit": "notebook_edit", "TodoWrite": "todo_write"}
+READ_LINES = 400
+REMINDER = re.compile(r"<system-reminder>.*?</system-reminder>\s*", re.S)
+# Context a client harness adds around the typed prompt (T3 Code's attachment metadata).
+HARNESS = re.compile(r"<t3_context\b.*?</t3_context>\s*|^\[Attached image .*? is saved at: .*?\]\s*$", re.S | re.M)
+CLAUDE_READ_LINE = re.compile(r"^\s*(\d+)\t(.*)$")
+# User messages that aren't prompts to the agent: local slash commands and their output, interrupts.
+NOT_PROMPTS = ("<command-name>", "<local-command-stdout>", "<local-command-caveat>", "[Request interrupted by user")
+
+
+def detected():
+    return HOME.is_dir()
+
+
+def hooked():
+    return hooks.present(SETTINGS, nested=True)
+
+
+def install(command, config):
+    if hooks.install(SETTINGS, EVENTS, command, nested=True):
+        return f"hook added to {SETTINGS}"
+    return None
+
+
+def uninstall(config):
+    return hooks.remove(SETTINGS, nested=True)
+
+
+def job(hook):
+    """The session a Stop / SessionEnd hook is about, or None."""
+    transcript = Path(hook.get("transcript_path") or "").expanduser().resolve()
+    if transcript.suffix != ".jsonl" or PROJECTS.resolve() not in transcript.parents or not transcript.is_file():
+        return None
+    cwd = hook.get("cwd") if isinstance(hook.get("cwd"), str) else None
+    return {"path": str(transcript), "label": transcript.stem, "folders": [cwd] if cwd else [], "folder": cwd}
+
+
+def newest():
+    return max(PROJECTS.glob("*/*.jsonl"), key=lambda p: p.stat().st_mtime, default=None)
+
+
+def _ts(value):
+    """Transcript timestamps (2026-10-09T00:50:29.548Z) as the naive UTC text Snowflake parses."""
+    return datetime.fromisoformat(value.replace("Z", "+00:00")).strftime("%Y-%m-%d %H:%M:%S.%f")[:-3]
+
+
+def _text(content):
+    """Text of a message's content: a string, or its text blocks; images become "[image]" only when
+    there's no text (a prompt names its own attachments)."""
+    if isinstance(content, str):
+        return content
+    blocks = [b for b in content if isinstance(b, dict)] if isinstance(content, list) else []
+    texts = [b.get("text", "") for b in blocks if b.get("type") == "text"]
+    return "\n".join(texts) if any(t.strip() for t in texts) else "\n".join(
+        "[image]" for b in blocks if b.get("type") == "image")
+
+
+def prompt_of(entry):
+    """The prompt a user line carries, or None when it isn't one the developer typed."""
+    if entry.get("isMeta") or entry.get("turnOrigin") == "task_notification":
+        return None
+    content = entry["message"].get("content")
+    if isinstance(content, list) and any(isinstance(b, dict) and b.get("type") == "tool_result" for b in content):
+        return None
+    text = HARNESS.sub("", REMINDER.sub("", _text(content))).strip()
+    if not text or text.startswith(NOT_PROMPTS) or text.startswith("<task-notification>"):
+        return None
+    return text
+
+
+def edit_location(patch, old_string, new_string):
+    """Where an Edit's new text landed, from the structured patch Claude Code keeps beside the result,
+    in the words Cortex Code's edit results use ("Edit location: lines 12-16"), so the trace's diff
+    card can number its lines. None without a patch."""
+    old = (old_string or "").split("\n")
+    skip = next((i for i, line in enumerate(old) if line.strip()), 0)  # leading blank lines
+    for hunk in patch or []:
+        n = hunk.get("oldStart")
+        for line in hunk.get("lines") or []:
+            if line[:1] not in (" ", "-"):
+                continue
+            if n is not None and line[1:] == old[skip]:
+                start = n - skip
+                return f"Edit location: lines {start}-{start + max(len((new_string or '').split(chr(10))), 1) - 1}"
+            n = None if n is None else n + 1
+    return None
+
+
+def _result(name, block, tool_result=None, args=None):
+    text = _text(block.get("content"))
+    if name == "edit" and isinstance(tool_result, dict):
+        if where := edit_location(tool_result.get("structuredPatch"), (args or {}).get("old_string"),
+                                  (args or {}).get("new_string")):
+            text = f"{text}\n{where}"
+    if name == "read":
+        lines = text.splitlines()[:READ_LINES]
+        numbered = [CLAUDE_READ_LINE.match(line) for line in lines]
+        if numbered and all(numbered):
+            text = "\n".join(f"{m.group(1)}... {m.group(2)}" for m in numbered)
+    # The trace marks a tool call failed when its result reads as an error.
+    if block.get("is_error") and not text.lstrip().lower().startswith("error"):
+        text = "Error: " + text
+    return clip(text, RESULT_CHARS)
+
+
+def model_calls(entries):
+    """One dict per API response on the main thread, in order: prompt (for turn starts), step,
+    model, usage, response text, tool calls, start (when its input was sent) and end."""
+    calls = OrderedDict()
+    results = {}
+    last_input, step, pending_prompt = None, 0, None
+    for e in entries:
+        if e.get("isSidechain"):
+            continue
+        kind = e.get("type")
+        if kind == "user":
+            last_input = e["timestamp"]
+            content = e["message"].get("content")
+            for block in content if isinstance(content, list) else []:
+                if isinstance(block, dict) and block.get("type") == "tool_result":
+                    # Claude Code writes each result on its own line, with its details (an edit's
+                    # structured patch) in toolUseResult.
+                    results[block.get("tool_use_id")] = (block, e.get("toolUseResult"))
+            if (prompt := prompt_of(e)) is not None:
+                # Prompts sent before the agent answered (e.g. after an interrupt) open one turn together.
+                pending_prompt = prompt if pending_prompt is None else f"{pending_prompt}\n\n{prompt}"
+                step = 0
+        elif kind == "assistant":
+            m = e["message"]
+            if m.get("model") == "<synthetic>" or not m.get("id"):
+                continue
+            call = calls.get(m["id"])
+            if call is None:
+                call = calls[m["id"]] = {"prompt": pending_prompt, "step": step, "model": m.get("model"),
+                                         "start": last_input or e["timestamp"], "end": e["timestamp"],
+                                         "usage": {}, "texts": [], "tools": [], "error": e.get("isApiErrorMessage")}
+                pending_prompt, step = None, step + 1
+            call["end"] = e["timestamp"]
+            usage = m.get("usage") or {}
+            if (usage.get("output_tokens") or 0) >= (call["usage"].get("output_tokens") or 0):
+                call["usage"] = usage
+            for block in m.get("content") or []:
+                if block.get("type") == "text" and block.get("text", "").strip():
+                    call["texts"].append(block["text"].strip())
+                elif block.get("type") == "tool_use":
+                    name = block.get("name") or "tool"
+                    call["tools"].append({"id": block.get("id"), "name": TOOL_NAMES.get(name, name.lower()),
+                                          "args": clip_args(block.get("input"))})
+    for call in calls.values():
+        for tool in call["tools"]:
+            block = results.get(tool["id"])
+            tool["result"] = _result(tool["name"], block[0], block[1], tool["args"]) if block else None
+    return list(calls.values())
+
+
+def to_requests(calls, session_id):
+    requests = []
+    for i, call in enumerate(calls):
+        u = call["usage"]
+        cache_read, cache_write = u.get("cache_read_input_tokens") or 0, u.get("cache_creation_input_tokens") or 0
+        requests.append(request(
+            f"claude-{session_id[:8]}-{i}", call["step"], _ts(call["start"]), _ts(call["end"]),
+            call["prompt"] if call["step"] == 0 else None, "\n\n".join(call["texts"]) or None, call["tools"],
+            model=call["model"],
+            status="ERROR" if call["error"] else "SUCCESS",
+            # The app's input count includes cached input, as Snowflake's telemetry does.
+            input_tokens=(u.get("input_tokens") or 0) + cache_read + cache_write,
+            output_tokens=u.get("output_tokens") or 0,
+            cache_read_tokens=cache_read,
+            cache_write_tokens=cache_write))
+    return requests
+
+
+def git_reports(entries, repo_dir=None):
+    """One report per prompt, like the git hook's UserPromptSubmit: the git state of the folder the
+    prompt ran in (or of repo_dir), with the running prompt count. The branch is the one Claude Code
+    recorded with the prompt when it ran in that repository, so work on earlier branches keeps its
+    branch; the commit and dirty flag are known only for the branch checked out now."""
+    reports, states, tops = [], {}, {}
+    for e in entries:
+        if e.get("type") != "user" or e.get("isSidechain") or prompt_of(e) is None:
+            continue
+        folder = repo_dir or e.get("cwd")
+        if folder not in states:
+            states[folder] = repo_state(folder)
+        state = states[folder]
+        if not state:
+            continue
+        report = {"observed_at": _ts(e["timestamp"]), "prompt_seq": len(reports) + 1, **state}
+        cwd, recorded = e.get("cwd"), e.get("gitBranch")
+        if recorded and cwd:
+            for path in {cwd, folder}:
+                if path not in tops:
+                    tops[path] = toplevel(path)
+            if tops[cwd] and tops[cwd] == tops[folder]:
+                branch = None if recorded == "HEAD" else recorded
+                if branch != state["branch"]:
+                    report.update(branch=branch, head_sha=None, is_dirty=None)
+        reports.append(report)
+    return reports
+
+
+def payload(path, repo_dir=None, folder=None):
+    """The session for core.ingest_external_session. `repo_dir` pins its repository. Claude Code
+    records each prompt's folder itself, so `folder` isn't needed."""
+    entries = [json.loads(line) for line in Path(path).read_text().splitlines() if line.strip()]
+    entries = [e for e in entries if e.get("type") in ("user", "assistant") and e.get("timestamp")]
+    session_id = next(e["sessionId"] for e in entries if e.get("sessionId"))
+    calls = model_calls(entries)
+    models = [c["model"] for c in calls if c["model"]]
+    repo_dir = repo_dir or repo_of_paths(
+        (block.get("input") or {}).get(key)
+        for e in entries if e.get("type") == "assistant" and isinstance((e.get("message") or {}).get("content"), list)
+        for block in e["message"]["content"] if isinstance(block, dict) and block.get("type") == "tool_use"
+        for key in PATH_ARGS)
+    return {
+        "session_id": session_id,
+        "agent": "claude-code",
+        "agent_name": NAME,
+        "model": max(set(models), key=models.count) if models else None,
+        "started_at": _ts(entries[0]["timestamp"]),
+        "prompts": sum(1 for c in calls if c["step"] == 0 and c["prompt"]),
+        "git_reports": git_reports(entries, repo_dir),
+        "requests": to_requests(calls, session_id),
+    }

agentledger_cli-0.1.0/src/agentledger/agents/cortex.py

@@ -0,0 +1,42 @@
+"""Cortex Code. Its sessions reach the app through Snowflake's own telemetry; what it needs on the
+developer machine is the git hook plugin the app publishes as a Cortex Extension."""
+import re
+import shutil
+import subprocess
+
+ID, NAME = "cortex", "Cortex Code"
+PLUGIN = "agentledger"
+
+
+class SetupError(Exception):
+    pass
+
+
+def _plugin(*args):
+    return subprocess.run(["cortex", "plugin", *args], capture_output=True, text=True, timeout=180)
+
+
+def detected():
+    return shutil.which("cortex") is not None
+
+
+def hooked():
+    return bool(re.search(rf"^\s*{PLUGIN} v\S+ \[enabled", _plugin("list").stdout, re.M))
+
+
+def install(command, config):
+    if hooked():
+        return None
+    fqn = f"{config['app']}.PLUGINS.AGENTLEDGER"
+    out = _plugin("install", fqn, *(["-c", config["connection"]] if config["connection"] else []))
+    if out.returncode:
+        reason = (out.stderr or out.stdout).strip().splitlines()[-1:] or ["no output"]
+        raise SetupError(f"couldn't install the git plugin {fqn} ({reason[0]}). An app admin publishes it "
+                         "from the dashboard's Setup page, under Git integration.")
+    return f"git plugin {fqn} installed"
+
+
+def uninstall(config):
+    if not re.search(rf"^\s*{PLUGIN} v", _plugin("list").stdout, re.M):
+        return False
+    return _plugin("uninstall", PLUGIN).returncode == 0