absolutelyright 0.2.0a2__tar.gz

absolutelyright-0.2.0a2/.gitignore

@@ -0,0 +1,7 @@
+.venv/
+dist/
+__pycache__/
+*.egg-info/
+.pytest_cache/
+.ruff_cache/
+.env

absolutelyright-0.2.0a2/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 zzstoatzz
+
+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.

absolutelyright-0.2.0a2/PKG-INFO

@@ -0,0 +1,70 @@
+Metadata-Version: 2.4
+Name: absolutelyright
+Version: 0.2.0a2
+Summary: analytics over your claude code session transcripts
+Author-email: zzstoatzz <thrast36@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: analytics,claude,claude-code,cli,transcripts
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Requires-Dist: cyclopts>=4.17.0
+Requires-Dist: textual-plotext>=1.0.1
+Requires-Dist: textual>=8.2.7
+Description-Content-Type: text/markdown
+
+# absolutelyright
+
+analytics over your claude code session transcripts.
+
+claude code keeps a jsonl transcript of every session under `~/.claude/projects/`.
+absolutelyright separates what you actually typed from harness noise (tool results,
+slash-command expansions, subagent sidechains) and tells you things like:
+
+- your most-repeated literal prompts (everyone has a "make the PR description not suck")
+- how often you open with `no` / `wait` / `stop` / `actually`
+- where your prompts, interrupts, and output tokens go, per project
+- which tools claude leans on, and what hours you really work
+
+## install
+
+```bash
+uv tool install absolutelyright
+```
+
+## usage
+
+```bash
+absolutelyright report            # the whole picture, human-formatted
+absolutelyright prompts --pretty  # most-repeated literal prompts
+absolutelyright hours --pretty    # prompts by local hour of day
+absolutelyright overview --days 7 # recent only
+```
+
+machine-readable by default — lists are ndjson, single results are one json
+object — so output pipes straight into jq or an agent:
+
+```bash
+absolutelyright projects | jq -r '.project'
+```
+
+note: claude code prunes local transcripts (30 days by default, see
+`cleanupPeriodDays`), so absolutelyright sees a rolling window, not all time.
+
+## library
+
+```python
+from absolutelyright import load_sessions, repeated_prompts
+
+sessions = load_sessions(days=30)
+for text, count in repeated_prompts(sessions, top=10):
+    print(count, text)
+```

absolutelyright-0.2.0a2/README.md

@@ -0,0 +1,47 @@
+# absolutelyright
+
+analytics over your claude code session transcripts.
+
+claude code keeps a jsonl transcript of every session under `~/.claude/projects/`.
+absolutelyright separates what you actually typed from harness noise (tool results,
+slash-command expansions, subagent sidechains) and tells you things like:
+
+- your most-repeated literal prompts (everyone has a "make the PR description not suck")
+- how often you open with `no` / `wait` / `stop` / `actually`
+- where your prompts, interrupts, and output tokens go, per project
+- which tools claude leans on, and what hours you really work
+
+## install
+
+```bash
+uv tool install absolutelyright
+```
+
+## usage
+
+```bash
+absolutelyright report            # the whole picture, human-formatted
+absolutelyright prompts --pretty  # most-repeated literal prompts
+absolutelyright hours --pretty    # prompts by local hour of day
+absolutelyright overview --days 7 # recent only
+```
+
+machine-readable by default — lists are ndjson, single results are one json
+object — so output pipes straight into jq or an agent:
+
+```bash
+absolutelyright projects | jq -r '.project'
+```
+
+note: claude code prunes local transcripts (30 days by default, see
+`cleanupPeriodDays`), so absolutelyright sees a rolling window, not all time.
+
+## library
+
+```python
+from absolutelyright import load_sessions, repeated_prompts
+
+sessions = load_sessions(days=30)
+for text, count in repeated_prompts(sessions, top=10):
+    print(count, text)
+```

absolutelyright-0.2.0a2/justfile

@@ -0,0 +1,37 @@
+# run tests
+test:
+    uv run pytest tests/ -x
+
+# format and lint
+fmt:
+    uv run ruff format src/ tests/
+    uv run ruff check src/ tests/ --fix
+
+# type check
+check:
+    uv run ty check
+
+# tag the next alpha, build, publish to pypi (token from .env / ~/.env)
+release:
+    #!/usr/bin/env bash
+    set -euo pipefail
+    if [ -f .env ]; then source .env; elif [ -f ~/.env ]; then source ~/.env; fi
+    export UV_PUBLISH_TOKEN="${UV_PUBLISH_TOKEN:-${PYPI_API_TOKEN:?no pypi token in .env}}"
+    if [ -n "$(git status --porcelain)" ]; then
+        echo "working tree is dirty — commit first" >&2
+        exit 1
+    fi
+    last=$(git tag -l 'v*' --sort=-v:refname | head -1)
+    if [[ $last =~ ^v([0-9]+)\.([0-9]+)\.([0-9]+)a([0-9]+)$ ]]; then
+        next="v${BASH_REMATCH[1]}.${BASH_REMATCH[2]}.${BASH_REMATCH[3]}a$((BASH_REMATCH[4] + 1))"
+    elif [[ $last =~ ^v([0-9]+)\.([0-9]+)\.([0-9]+)$ ]]; then
+        next="v${BASH_REMATCH[1]}.$((BASH_REMATCH[2] + 1)).0a1"
+    else
+        next="v0.2.0a1"
+    fi
+    just test
+    git tag "$next"
+    rm -rf dist && uv build
+    uv publish
+    echo
+    echo "published ${next#v} — try it:  uvx absolutelyright@${next#v}"

absolutelyright-0.2.0a2/pyproject.toml

@@ -0,0 +1,100 @@
+[project]
+name = "absolutelyright"
+dynamic = ["version"]
+description = "analytics over your claude code session transcripts"
+readme = "README.md"
+authors = [{ name = "zzstoatzz", email = "thrast36@gmail.com" }]
+requires-python = ">=3.12"
+license = "MIT"
+
+keywords = ["claude", "claude-code", "transcripts", "analytics", "cli"]
+
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Typing :: Typed",
+]
+
+dependencies = [
+    "cyclopts>=4.17.0",
+    "textual>=8.2.7",
+    "textual-plotext>=1.0.1",
+]
+
+[project.scripts]
+absolutelyright = "absolutelyright.cli:main"
+
+[dependency-groups]
+dev = [
+    "pytest>=8.3.0",
+    "pytest-asyncio>=1.4.0",
+    "pytest-sugar",
+    "ruff>=0.12.0",
+    "ty>=0.0.1a25",
+]
+
+[build-system]
+requires = ["hatchling", "uv-dynamic-versioning>=0.7.0"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/absolutelyright"]
+
+[tool.hatch.version]
+source = "uv-dynamic-versioning"
+
+[tool.uv-dynamic-versioning]
+vcs = "git"
+style = "pep440"
+bump = true
+fallback-version = "0.0.0"
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+asyncio_default_fixture_loop_scope = "function"
+testpaths = ["tests"]
+python_files = ["test_*.py", "*_test.py"]
+python_classes = ["Test*"]
+python_functions = ["test_*"]
+
+[tool.ruff.lint]
+fixable = ["ALL"]
+ignore = [
+    "COM812",
+    "PLR0913", # Too many arguments
+    "SIM102",  # Dont require combining if statements
+    "ANN401",  # Any is allowed where it's the honest type (escape hatches)
+]
+extend-select = [
+    "ANN", # flake8-annotations: require complete signatures
+    "B",   # flake8-bugbear
+    "C4",  # flake8-comprehensions
+    "I",   # isort
+    "PIE", # flake8-pie
+    "RUF", # Ruff-specific
+    "SIM", # flake8-simplify
+    "UP",  # pyupgrade
+]
+
+[tool.ruff.lint.per-file-ignores]
+"__init__.py" = ["F401", "I001"]
+"tests/**/*.py" = ["S101"]       # Allow assert in tests
+
+[tool.ty.src]
+include = ["src", "tests"]
+exclude = [
+    "**/node_modules",
+    "**/__pycache__",
+    ".venv",
+    ".git",
+    "dist",
+]
+
+[tool.ty.environment]
+python-version = "3.12"

absolutelyright-0.2.0a2/src/absolutelyright/__init__.py

@@ -0,0 +1,29 @@
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("absolutelyright")
+except PackageNotFoundError:
+    __version__ = "0.0.0"
+
+from absolutelyright._records import (
+    Prompt,
+    Session,
+    load_sessions,
+    parse_session,
+    session_files,
+)
+from absolutelyright._stats import (
+    by_project,
+    claudeisms,
+    corrections,
+    daily_counts,
+    hour_histogram,
+    model_mix,
+    overview,
+    repeated_prompts,
+    session_rows,
+    shipped,
+    slash_counts,
+    tool_counts,
+    vibe,
+)

absolutelyright-0.2.0a2/src/absolutelyright/_records.py

@@ -0,0 +1,224 @@
+"""parsing for claude code session transcripts.
+
+each session is a jsonl file under ~/.claude/projects/<encoded-cwd>/<uuid>.jsonl.
+user-role records are a grab bag: typed prompts, tool results, slash-command
+expansions, bash passthroughs, and interrupt markers all share `type: "user"`.
+this module separates what a human actually typed from harness noise — and
+mines the rest of the record stream (titles, pr links, models, usage, tics)
+in the same single pass.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import re
+from collections import Counter
+from dataclasses import dataclass, field
+from datetime import UTC, datetime, timedelta
+from pathlib import Path
+from typing import Any
+
+
+def default_claude_dir() -> Path:
+    """where claude code keeps its data: $CLAUDE_CONFIG_DIR, else ~/.claude."""
+    return Path(os.environ.get("CLAUDE_CONFIG_DIR") or Path.home() / ".claude")
+
+
+DEFAULT_CLAUDE_DIR = default_claude_dir()
+
+# substrings that mark a user-role record as harness traffic, not a typed prompt
+NOISE_MARKERS = (
+    "<command-name>",
+    "<command-message>",
+    "<bash-input>",
+    "<bash-stdout>",
+    "<local-command-stdout>",
+    "<task-notification>",
+    "<system-reminder>",
+    "[Request interrupted",
+    "Caveat: the messages below",
+)
+
+# things claude says
+ISM_PATTERNS = {
+    "you're absolutely right": re.compile(r"you'?re absolutely right", re.I),
+    "let me …": re.compile(r"^let me ", re.I | re.M),
+    "now i see": re.compile(r"\bnow i see\b", re.I),
+    "the issue is": re.compile(r"\bthe (?:real )?issue is\b", re.I),
+    "should now work": re.compile(r"\bshould (?:now )?work\b", re.I),
+    "great question": re.compile(r"\bgreat question\b", re.I),
+    "perfect!": re.compile(r"\bperfect!", re.I),
+}
+
+# things you say
+VIBE_PATTERNS = {
+    "please": re.compile(r"\bplease\b|\bpls\b", re.I),
+    "thanks": re.compile(r"\bthanks?\b|\bty\b", re.I),
+    "dude": re.compile(r"\bdude\b", re.I),
+    "bro": re.compile(r"\bbro\b", re.I),
+    "lol": re.compile(r"\blo+l\b|\blmao\b", re.I),
+    "profanity": re.compile(r"\b(?:fuck\w*|shit\w*|damn|wtf)\b", re.I),
+}
+
+IMAGE_RE = re.compile(r"\[Image #\d+\]")
+SLASH_RE = re.compile(r"<command-name>(\S+?)</command-name>")
+
+# gaps longer than this don't count toward active time (you walked away)
+IDLE_CAP_SECONDS = 300
+
+
+@dataclass(slots=True)
+class Prompt:
+    text: str
+    project: str
+    session_id: str
+    timestamp: datetime | None
+
+
+@dataclass(slots=True)
+class Session:
+    path: Path
+    session_id: str
+    project: str
+    title: str = ""
+    prompts: list[Prompt] = field(default_factory=list)
+    interrupts: int = 0
+    tool_calls: Counter[str] = field(default_factory=Counter)
+    output_tokens: int = 0
+    input_tokens: int = 0
+    cache_read_tokens: int = 0
+    models: Counter[str] = field(default_factory=Counter)
+    isms: Counter[str] = field(default_factory=Counter)
+    vibe: Counter[str] = field(default_factory=Counter)
+    slash_commands: Counter[str] = field(default_factory=Counter)
+    pr_urls: set[str] = field(default_factory=set)
+    images: int = 0
+    first_ts: datetime | None = None
+    last_ts: datetime | None = None
+    active_seconds: float = 0.0
+
+
+def _parse_timestamp(raw: str | None) -> datetime | None:
+    if not raw:
+        return None
+    try:
+        return datetime.fromisoformat(raw.replace("Z", "+00:00"))
+    except ValueError:
+        return None
+
+
+def _flatten_text(content: Any) -> str | None:
+    """collapse message content to text, or None if there is none (e.g. pure tool_result)."""
+    if isinstance(content, str):
+        return content
+    if isinstance(content, list):
+        texts = [
+            block.get("text", "")
+            for block in content
+            if isinstance(block, dict) and block.get("type") == "text"
+        ]
+        if texts:
+            return "\n".join(texts)
+    return None
+
+
+def _shorten_home(cwd: str) -> str:
+    home = str(Path.home())
+    if cwd == home:
+        return "~"
+    return cwd.removeprefix(home + "/")
+
+
+def session_files(claude_dir: Path) -> list[Path]:
+    """top-level session transcripts. subdirectories hold subagent sidechains."""
+    return sorted(claude_dir.glob("projects/*/*.jsonl"))
+
+
+def parse_session(path: Path, since: datetime | None = None) -> Session:
+    session = Session(path=path, session_id=path.stem, project="?")
+
+    with path.open() as f:
+        for line in f:
+            try:
+                record = json.loads(line)
+            except json.JSONDecodeError:
+                continue
+            if record.get("isSidechain"):
+                continue
+
+            kind = record.get("type")
+            if kind == "ai-title":
+                session.title = record.get("aiTitle") or session.title
+                continue
+            if kind == "pr-link":
+                if url := record.get("prUrl"):
+                    session.pr_urls.add(url)
+                continue
+
+            timestamp = _parse_timestamp(record.get("timestamp"))
+            if since and timestamp and timestamp < since:
+                continue
+            if timestamp:
+                if session.first_ts is None:
+                    session.first_ts = timestamp
+                elif session.last_ts is not None:
+                    gap = (timestamp - session.last_ts).total_seconds()
+                    if 0 < gap <= IDLE_CAP_SECONDS:
+                        session.active_seconds += gap
+                session.last_ts = timestamp
+            if session.project == "?" and record.get("cwd"):
+                session.project = _shorten_home(record["cwd"])
+
+            message = record.get("message") or {}
+            if kind == "assistant":
+                if model := message.get("model"):
+                    if not model.startswith("<"):  # `<synthetic>` placeholder rows
+                        session.models[model] += 1
+                for block in message.get("content") or []:
+                    if not isinstance(block, dict):
+                        continue
+                    if block.get("type") == "tool_use":
+                        session.tool_calls[block.get("name", "?")] += 1
+                    elif block.get("type") == "text":
+                        for name, pattern in ISM_PATTERNS.items():
+                            session.isms[name] += len(pattern.findall(block["text"]))
+                usage = message.get("usage") or {}
+                session.output_tokens += usage.get("output_tokens", 0)
+                session.input_tokens += usage.get("input_tokens", 0)
+                session.cache_read_tokens += usage.get("cache_read_input_tokens", 0)
+            elif kind == "user":
+                text = _flatten_text(message.get("content"))
+                if text is None:
+                    continue
+                if "[Request interrupted" in text:
+                    session.interrupts += 1
+                    continue
+                if match := SLASH_RE.search(text):
+                    session.slash_commands[match.group(1)] += 1
+                    continue
+                if record.get("isMeta") or any(m in text for m in NOISE_MARKERS):
+                    continue
+                text = text.strip()
+                if text:
+                    session.images += len(IMAGE_RE.findall(text))
+                    for name, pattern in VIBE_PATTERNS.items():
+                        session.vibe[name] += len(pattern.findall(text))
+                    session.prompts.append(
+                        Prompt(
+                            text=text,
+                            project=session.project,
+                            session_id=record.get("sessionId", session.session_id),
+                            timestamp=timestamp,
+                        )
+                    )
+
+    return session
+
+
+def load_sessions(
+    claude_dir: Path = DEFAULT_CLAUDE_DIR, days: int | None = None
+) -> list[Session]:
+    since = datetime.now(UTC) - timedelta(days=days) if days is not None else None
+    sessions = [parse_session(path, since=since) for path in session_files(claude_dir)]
+    return [s for s in sessions if s.prompts or s.tool_calls or s.interrupts]