claude-code-statusline 0.7.1__py3-none-any.whl

claude_code_statusline/__init__.py

@@ -0,0 +1,6 @@
+"""Claude Code Statusline - Context usage tracking for Claude Code."""
+
+from importlib.metadata import version
+
+__version__ = version("claude-code-statusline")
+__all__ = ["__version__"]

claude_code_statusline/config/defaults.py

@@ -0,0 +1,29 @@
+"""Default configuration for Claude Code Status Line."""
+
+from .schema import StatusLineConfig, WidgetConfigModel
+
+
+def get_default_config() -> StatusLineConfig:
+    """Generate the default status line configuration."""
+    return StatusLineConfig(
+        version=1,
+        lines=[
+            [
+                WidgetConfigModel(type="model", color="cyan"),
+                WidgetConfigModel(type="separator"),
+                WidgetConfigModel(type="directory", color="blue"),
+                WidgetConfigModel(type="separator"),
+                WidgetConfigModel(type="git-branch", color="magenta"),
+                WidgetConfigModel(type="separator"),
+                WidgetConfigModel(type="context-percentage"),
+                WidgetConfigModel(type="separator"),
+                WidgetConfigModel(type="cost"),
+                WidgetConfigModel(type="separator"),
+                WidgetConfigModel(type="lines-changed"),
+                WidgetConfigModel(type="separator"),
+                WidgetConfigModel(type="session-id"),
+                WidgetConfigModel(type="separator"),
+                WidgetConfigModel(type="session-clock"),
+            ]
+        ],
+    )

claude_code_statusline/config/loader.py

@@ -0,0 +1,123 @@
+"""Configuration file loading and saving."""
+
+import os
+
+from pathlib import Path
+from typing import Optional
+
+import yaml
+
+from pydantic import ValidationError
+
+from .defaults import get_default_config
+from .schema import StatusLineConfig
+
+# Module-level cache for config
+_cached_config: Optional[StatusLineConfig] = None
+_cached_mtime: float = 0.0
+
+
+def get_config_dir() -> Path:
+    """Get the configuration directory path."""
+    config_home = os.getenv("XDG_CONFIG_HOME", os.path.expanduser("~/.config"))
+    return Path(config_home) / "claude-statusline"
+
+
+def get_config_path() -> Path:
+    """Get the full configuration file path."""
+    return get_config_dir() / "config.yaml"
+
+
+def get_missing_widgets(config: StatusLineConfig) -> list[str]:
+    """Return widget types in defaults but missing from user config."""
+    default_config = get_default_config()
+
+    default_types = {
+        w.type for line in default_config.lines for w in line if w.type != "separator"
+    }
+
+    user_types = {
+        w.type for line in config.lines for w in line if w.type != "separator"
+    }
+
+    return sorted(default_types - user_types)
+
+
+def load_config() -> StatusLineConfig:
+    """
+    Load configuration from YAML file with mtime-based caching.
+
+    If config file doesn't exist, creates it with defaults.
+    If config is invalid, falls back to defaults and logs error.
+    """
+    global _cached_config, _cached_mtime
+
+    config_path = get_config_path()
+
+    if _cached_config is not None:
+        try:
+            current_mtime = config_path.stat().st_mtime
+            if current_mtime == _cached_mtime:
+                return _cached_config
+        except OSError:
+            pass
+
+    if not config_path.exists():
+        config = get_default_config()
+        save_config(config)
+        _cached_config = config
+        try:
+            _cached_mtime = config_path.stat().st_mtime
+        except OSError:
+            _cached_mtime = 0.0
+        return config
+
+    try:
+        with open(config_path, encoding="utf-8") as f:
+            config_data = yaml.safe_load(f)
+
+        if config_data is None:
+            config_data = {}
+
+        config = StatusLineConfig(**config_data)
+
+        missing = get_missing_widgets(config)
+        if missing:
+            import sys
+
+            print(
+                f"Warning: Config is missing widgets from defaults: {', '.join(missing)}. "
+                f"Delete {config_path} to regenerate with new defaults.",
+                file=sys.stderr,
+            )
+
+        _cached_config = config
+        try:
+            _cached_mtime = config_path.stat().st_mtime
+        except OSError:
+            _cached_mtime = 0.0
+
+        return config
+
+    except (yaml.YAMLError, ValidationError, OSError) as e:
+        import sys
+
+        print(
+            f"Warning: Failed to load config from {config_path}: {e}",
+            file=sys.stderr,
+        )
+        print("Using default configuration.", file=sys.stderr)
+        return get_default_config()
+
+
+def save_config(config: StatusLineConfig) -> None:
+    """Save configuration to YAML file."""
+    config_path = get_config_path()
+    config_dir = config_path.parent
+
+    config_dir.mkdir(parents=True, exist_ok=True)
+
+    config_dict = config.model_dump(mode="python")
+
+    with open(config_path, "w", encoding="utf-8") as f:
+        yaml.dump(config_dict, f, default_flow_style=False, sort_keys=False)

claude_code_statusline/config/schema.py

@@ -0,0 +1,25 @@
+"""Configuration schema using Pydantic for validation."""
+
+from typing import Optional
+from uuid import uuid4
+
+from pydantic import BaseModel, Field
+
+
+class WidgetConfigModel(BaseModel):
+    """Configuration for a single widget instance."""
+
+    type: str
+    id: str = Field(default_factory=lambda: str(uuid4()))
+    color: Optional[str] = None
+    bold: bool = False
+    metadata: dict[str, str] = Field(default_factory=dict)
+
+
+class StatusLineConfig(BaseModel):
+    """Complete status line configuration."""
+
+    version: int = 1
+    lines: list[list[WidgetConfigModel]] = Field(default_factory=list)
+
+    model_config = {"extra": "forbid"}

claude_code_statusline/parsers/jsonl.py

@@ -0,0 +1,330 @@
+"""JSONL transcript parsing utilities."""
+
+import json
+import os
+
+from dataclasses import dataclass, field
+
+from ..utils.debug import debug_log
+
+
+@dataclass
+class ParsedTranscript:
+    """Results from parsing a transcript file."""
+
+    session_id: str = ""
+    context_chars: int = 0
+    total_file_chars: int = 0
+    boundaries_found: int = 0
+    is_jsonl: bool = False
+
+
+@dataclass
+class ExclusionRules:
+    """Configuration for which lines to exclude from token counting.
+
+    These fields are stored in Claude Code's JSONL files for debugging and
+    UI purposes but are not included in the actual context sent to Claude.
+    """
+
+    metadata_fields: list[str] = field(
+        default_factory=lambda: [
+            "snapshot",
+            "leafUuid",
+        ]
+    )
+    excluded_types: list[str] = field(default_factory=lambda: ["summary", "system"])
+    excluded_flags: list[str] = field(default_factory=lambda: [])
+
+
+EXCLUSION_RULES = ExclusionRules()
+CHARS_PER_TOKEN = 3.31  # Fallback estimation for transcripts without message.usage
+DEFAULT_SYSTEM_OVERHEAD_TOKENS = 21400  # For character-based fallback
+
+
+def get_system_overhead_tokens() -> int:
+    """Get system overhead tokens from environment or use default."""
+    try:
+        return int(
+            os.getenv("CLAUDE_CODE_SYSTEM_OVERHEAD", DEFAULT_SYSTEM_OVERHEAD_TOKENS)
+        )
+    except (ValueError, TypeError):
+        return DEFAULT_SYSTEM_OVERHEAD_TOKENS
+
+
+def calculate_total_tokens(transcript: ParsedTranscript) -> int:
+    """Calculate total tokens from a transcript including conversation and system overhead.
+
+    This uses character-based estimation and is kept for backwards compatibility.
+    For real token counts, use parsers.tokens.get_token_metrics() instead.
+
+    Args:
+        transcript: Parsed transcript with character counts
+
+    Returns:
+        Estimated total tokens
+    """
+    conversation_tokens = int(transcript.context_chars // CHARS_PER_TOKEN)
+    system_overhead_tokens = get_system_overhead_tokens()
+    return conversation_tokens + system_overhead_tokens
+
+
+def safe_get_file_size(file_path: str) -> int:
+    """Safely get file size, returning 0 on error."""
+    try:
+        return os.path.getsize(file_path)
+    except OSError:
+        return 0
+
+
+def is_real_compact_boundary(data: dict) -> bool:
+    """Check if this is a real compact boundary set by Claude Code.
+
+    Args:
+        data: Parsed JSON line from transcript
+
+    Returns:
+        True if this line is a valid compact boundary marker
+    """
+    return (
+        data.get("type") == "system"
+        and data.get("subtype") == "compact_boundary"
+        and "compactMetadata" in data
+        and isinstance(data["compactMetadata"], dict)
+        and "trigger" in data["compactMetadata"]
+    )
+
+
+def should_exclude_line(
+    data: dict, rules: ExclusionRules = EXCLUSION_RULES
+) -> tuple[bool, str]:
+    """Check if a line should be excluded from token counting.
+
+    Args:
+        data: Parsed JSON line from transcript
+        rules: Exclusion rules configuration (defaults to global rules)
+
+    Returns:
+        Tuple of (should_exclude, reason) where reason is empty if not excluded
+    """
+    for metadata_field in rules.metadata_fields:
+        if metadata_field in data:
+            return True, f"has {metadata_field}"
+
+    line_type = data.get("type")
+    if line_type in rules.excluded_types:
+        return True, f"type={line_type}"
+
+    for flag_name in rules.excluded_flags:
+        if data.get(flag_name):
+            return True, f"{flag_name}=true"
+
+    return False, ""
+
+
+def extract_message_content_chars(
+    data: dict, session_id: str = "", detailed_debug: bool = False
+) -> int:
+    """Extract content that contributes to context.
+
+    Only counts role and content fields, as these are what actually gets sent to Claude.
+    Response metadata fields (model, type, stop_reason, etc.) are not counted.
+
+    Args:
+        data: Parsed JSON line from transcript
+        session_id: Session identifier for debug logging
+        detailed_debug: Whether to log detailed debug information
+
+    Returns:
+        Number of characters that contribute to context
+    """
+    message = data.get("message", {})
+    if not message:
+        return 0
+
+    filtered_message = {}
+    field_contributions = {}
+
+    if "role" in message:
+        field_value = json.dumps(message["role"])
+        filtered_message["role"] = message["role"]
+        field_contributions["role"] = len(field_value)
+
+    if "content" in message:
+        content = message["content"]
+        filtered_content = content
+        images_skipped = 0
+
+        if isinstance(content, list):
+            filtered_content = []
+            for item in content:
+                if isinstance(item, dict) and item.get("type") == "image":
+                    images_skipped += 1
+                    debug_log(
+                        "Skipping base64-encoded image in message (not counted as text tokens)",
+                        session_id,
+                    )
+                else:
+                    filtered_content.append(item)
+
+        field_value = json.dumps(filtered_content)
+        filtered_message["content"] = filtered_content
+        field_contributions["content"] = len(field_value)
+
+        if images_skipped > 0:
+            debug_log(
+                f"Excluded {images_skipped} base64-encoded image(s) from character count",
+                session_id,
+            )
+
+    total_chars = len(json.dumps(filtered_message))
+
+    if detailed_debug and field_contributions:
+        role = message.get("role", "unknown")
+        debug_log(
+            f"Message field breakdown ({role}): {field_contributions}", session_id
+        )
+
+    return total_chars
+
+
+def parse_transcript(file_path: str) -> ParsedTranscript:
+    """Parse transcript file in a single pass.
+
+    Args:
+        file_path: Path to the JSONL transcript file
+
+    Returns:
+        ParsedTranscript with character counts and session metadata
+    """
+    if not file_path or not os.path.isfile(file_path):
+        debug_log("No valid transcript file", transcript_path=file_path)
+        return ParsedTranscript()
+
+    total_file_chars = safe_get_file_size(file_path)
+    debug_log(
+        f"Parsing transcript: {file_path} ({total_file_chars} chars)",
+        transcript_path=file_path,
+    )
+
+    try:
+        with open(file_path, encoding="utf-8") as f:
+            lines = f.readlines()
+    except OSError as e:
+        debug_log(f"Failed to read file: {e}", transcript_path=file_path)
+        return ParsedTranscript(total_file_chars=total_file_chars)
+
+    # Single-pass parsing: track all state simultaneously
+    session_id = ""
+    boundary_count = 0
+    is_jsonl = False
+    detailed_debug = os.getenv("CLAUDE_CODE_STATUSLINE_DEBUG")
+
+    chars_before_latest_boundary = 0
+    chars_after_latest_boundary = 0
+
+    message_type_counts = {}
+    message_type_chars = {}
+    excluded_line_counts = {}
+    total_excluded_lines = 0
+
+    for _line_num, line in enumerate(lines):
+        stripped = line.strip()
+        if not stripped:
+            continue
+
+        try:
+            data = json.loads(stripped)
+            is_jsonl = True  # At least one valid JSON line
+
+            if not session_id and data.get("sessionId"):
+                session_id = data["sessionId"]
+
+            if is_real_compact_boundary(data):
+                boundary_count += 1
+                chars_before_latest_boundary += chars_after_latest_boundary
+                chars_after_latest_boundary = 0
+                continue
+
+            should_exclude, exclusion_reason = should_exclude_line(data)
+            if should_exclude:
+                total_excluded_lines += 1
+                excluded_line_counts[exclusion_reason] = (
+                    excluded_line_counts.get(exclusion_reason, 0) + 1
+                )
+                continue
+
+            chars = extract_message_content_chars(
+                data, session_id, bool(detailed_debug)
+            )
+            chars_after_latest_boundary += chars
+
+            if detailed_debug and chars > 0:
+                msg_type = data.get("type", "unknown")
+                role = data.get("message", {}).get("role", "")
+                type_key = f"{msg_type}:{role}" if role else msg_type
+
+                message_type_counts[type_key] = message_type_counts.get(type_key, 0) + 1
+                message_type_chars[type_key] = (
+                    message_type_chars.get(type_key, 0) + chars
+                )
+
+        except json.JSONDecodeError:
+            continue
+
+    if not is_jsonl:
+        debug_log("File is not JSONL format, using fallback", transcript_path=file_path)
+        return ParsedTranscript(
+            session_id="",
+            total_file_chars=total_file_chars,
+            context_chars=total_file_chars,
+            is_jsonl=False,
+        )
+
+    message_content_chars = (
+        chars_after_latest_boundary
+        if boundary_count > 0
+        else (chars_before_latest_boundary + chars_after_latest_boundary)
+    )
+
+    debug_log(f"Session: {session_id}, boundaries: {boundary_count}", session_id)
+    debug_log(
+        f"Message content chars: {message_content_chars}/{total_file_chars}", session_id
+    )
+
+    if detailed_debug:
+        if total_excluded_lines > 0:
+            debug_log(
+                f"=== Excluded {total_excluded_lines} lines from token counting ===",
+                session_id,
+            )
+            for reason, count in sorted(
+                excluded_line_counts.items(), key=lambda x: x[1], reverse=True
+            ):
+                debug_log(f"  {reason}: {count} lines", session_id)
+            debug_log("=" * 40, session_id)
+
+        if message_type_chars:
+            debug_log("=== Token Breakdown by Message Type ===", session_id)
+            sorted_types = sorted(
+                message_type_chars.items(), key=lambda x: x[1], reverse=True
+            )
+            total_tracked = sum(message_type_chars.values())
+
+            for msg_type, chars in sorted_types:
+                count = message_type_counts.get(msg_type, 0)
+                tokens = int(chars // CHARS_PER_TOKEN)
+                percentage = (chars * 100) // total_tracked if total_tracked > 0 else 0
+                debug_log(
+                    f"  {msg_type}: {count} messages, {chars} chars, {tokens} tokens ({percentage}%)",
+                    session_id,
+                )
+            debug_log("=" * 40, session_id)
+
+    return ParsedTranscript(
+        session_id=session_id,
+        context_chars=message_content_chars,
+        total_file_chars=total_file_chars,
+        boundaries_found=boundary_count,
+        is_jsonl=True,
+    )

claude_code_statusline/parsers/tokens.py

@@ -0,0 +1,159 @@
+"""Real token extraction from JSONL message.usage fields."""
+
+import json
+import os
+
+from datetime import datetime
+from typing import Optional
+
+from ..types import SessionMetrics, TokenMetrics
+
+
+def parse_transcript(
+    transcript_path: str,
+) -> tuple[TokenMetrics, Optional[SessionMetrics]]:
+    """Extract token metrics and session duration in single file read.
+
+    Combines the logic of get_token_metrics() and get_session_duration()
+    to avoid reading the transcript file twice.
+
+    Args:
+        transcript_path: Path to the JSONL transcript file
+
+    Returns:
+        Tuple of (TokenMetrics, SessionMetrics) from single file pass
+    """
+    if not transcript_path or not os.path.isfile(transcript_path):
+        return TokenMetrics(transcript_exists=False), None
+
+    input_tokens = 0
+    output_tokens = 0
+    cached_tokens = 0
+    context_length = 0
+
+    most_recent_time: Optional[datetime] = None
+    most_recent_usage: Optional[dict] = None
+
+    first_timestamp: Optional[datetime] = None
+    last_timestamp: Optional[datetime] = None
+
+    try:
+        with open(transcript_path, encoding="utf-8") as f:
+            for line in f:
+                line = line.strip()
+                if not line:
+                    continue
+
+                try:
+                    data = json.loads(line)
+
+                    # Extract timestamp for session duration
+                    timestamp_str = data.get("timestamp")
+                    if timestamp_str:
+                        try:
+                            timestamp = datetime.fromisoformat(
+                                timestamp_str.replace("Z", "+00:00")
+                            )
+                            if first_timestamp is None:
+                                first_timestamp = timestamp
+                            last_timestamp = timestamp
+                        except ValueError:
+                            pass
+
+                    # Extract token usage
+                    usage = data.get("message", {}).get("usage")
+                    if not usage:
+                        continue
+
+                    # Sum totals across all messages
+                    input_tokens += usage.get("input_tokens", 0)
+                    output_tokens += usage.get("output_tokens", 0)
+                    cached_tokens += usage.get("cache_read_input_tokens", 0)
+                    cached_tokens += usage.get("cache_creation_input_tokens", 0)
+
+                    # Track most recent main chain entry for context_length
+                    is_sidechain = data.get("isSidechain", False)
+                    is_api_error = data.get("isApiErrorMessage", False)
+                    stop_reason = data.get("message", {}).get("stop_reason")
+
+                    # Only use completed messages (skip streaming partials with stop_reason: null)
+                    if (
+                        not is_sidechain
+                        and not is_api_error
+                        and timestamp_str
+                        and stop_reason is not None
+                    ):
+                        try:
+                            entry_time = datetime.fromisoformat(
+                                timestamp_str.replace("Z", "+00:00")
+                            )
+                            if (
+                                most_recent_time is None
+                                or entry_time > most_recent_time
+                            ):
+                                most_recent_time = entry_time
+                                most_recent_usage = usage
+                        except ValueError:
+                            # Skip invalid timestamps
+                            continue
+
+                except (json.JSONDecodeError, ValueError):
+                    continue
+
+    except OSError:
+        return TokenMetrics(transcript_exists=False), None
+
+    # Calculate context_length from most recent main chain message
+    if most_recent_usage:
+        context_length = (
+            most_recent_usage.get("input_tokens", 0)
+            + most_recent_usage.get("cache_read_input_tokens", 0)
+            + most_recent_usage.get("cache_creation_input_tokens", 0)
+        )
+
+    total_tokens = input_tokens + output_tokens + cached_tokens
+
+    token_metrics = TokenMetrics(
+        input_tokens=input_tokens,
+        output_tokens=output_tokens,
+        cached_tokens=cached_tokens,
+        total_tokens=total_tokens,
+        context_length=context_length,
+        transcript_exists=True,
+    )
+
+    # Build session metrics
+    session_metrics = None
+    if first_timestamp and last_timestamp:
+        duration_seconds = int((last_timestamp - first_timestamp).total_seconds())
+        session_metrics = SessionMetrics(
+            start_time=first_timestamp,
+            last_activity=last_timestamp,
+            duration_seconds=duration_seconds,
+        )
+
+    return token_metrics, session_metrics
+
+
+def format_duration(duration_seconds: int) -> str:
+    """Format duration in seconds to human-readable string.
+
+    Args:
+        duration_seconds: Duration in seconds
+
+    Returns:
+        Formatted string like "2hr 15m" or "45m" or "<1m"
+    """
+    if duration_seconds < 60:
+        return "<1m"
+
+    total_minutes = duration_seconds // 60
+    hours = total_minutes // 60
+    minutes = total_minutes % 60
+
+    if hours == 0:
+        return f"{minutes}m"
+    elif minutes == 0:
+        return f"{hours}hr"
+    else:
+        return f"{hours}hr {minutes}m"