claude-statuskit 0.3.0__py3-none-any.whl

claude_statuskit-0.3.0.dist-info/METADATA

@@ -0,0 +1,205 @@
+Metadata-Version: 2.4
+Name: claude-statuskit
+Version: 0.3.0
+Summary: Modular statusline for Claude Code
+Project-URL: Homepage, https://github.com/NoNameItem/claude-tools/tree/master/packages/statuskit
+Project-URL: Repository, https://github.com/NoNameItem/claude-tools
+Author-email: Artem Vasin <nonameitem@me.com>
+License: MIT
+Keywords: claude,claude-code,cli,statusline
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Python: >=3.11
+Requires-Dist: termcolor
+Description-Content-Type: text/markdown
+
+# statuskit
+
+[![PyPI version](https://img.shields.io/pypi/v/claude-statuskit)](https://pypi.org/project/claude-statuskit/)
+[![Python versions](https://img.shields.io/pypi/pyversions/claude-statuskit)](https://pypi.org/project/claude-statuskit/)
+[![License](https://img.shields.io/pypi/l/claude-statuskit)](https://github.com/NoNameItem/claude-tools/blob/master/LICENSE)
+
+Modular statusline for [Claude Code](https://docs.anthropic.com/en/docs/claude-code).
+
+Statuskit displays contextual information below Claude's responses: current model, git status, API usage limits, and more. It reads JSON from Claude Code's statusline hook and renders formatted, colored output.
+
+## Features
+
+- **Modular architecture** — enable only the modules you need
+- **Configurable** — customize each module's behavior via TOML config
+- **Built-in modules:**
+  - `model` — current Claude model name
+  - `git` — branch, remote status, changes, last commit, project/worktree location
+  - `usage_limits` — API quota tracking (5h session, 7d weekly) with color-coded warnings
+- **Coming soon:**
+  - `beads` — display active beads tasks
+  - External modules support — load custom modules from separate packages
+
+## Installation
+
+```bash
+# Using uv (recommended)
+uv tool install claude-statuskit
+
+# Using pipx
+pipx install claude-statuskit
+
+# Using pip
+pip install claude-statuskit
+```
+
+## Quick Start
+
+Run the setup command to configure Claude Code:
+
+```bash
+# User-level setup (recommended for personal use)
+statuskit setup
+
+# Project-level setup (shared config for team)
+statuskit setup --scope project
+
+# Local setup (personal overrides, gitignored)
+statuskit setup --scope local
+```
+
+Setup will:
+1. Add the statusline hook to Claude Code settings
+2. Create configuration file at the appropriate level
+3. Update gitignore for local configs (if applicable)
+
+After setup, restart Claude Code to see the statusline.
+
+## Example Output
+
+```
+Opus 4.5 · 47m · 120k free (60%)
+claude-tools master ↑1 +2 ~1 ?3 · a1b2c3d 2h
+Session: 45% (2h 30m) · Weekly: 12%
+```
+
+This shows:
+- **Line 1 (model):** Model name, session duration, context window
+- **Line 2 (git):** Project, branch, remote status, changes, last commit
+- **Line 3 (usage_limits):** API quota for session and weekly limits
+
+## Configuration
+
+Configuration files are loaded in priority order (first found wins):
+
+| Level | Path | Use case |
+|-------|------|----------|
+| Local | `.claude/statuskit.local.toml` | Personal overrides, gitignored |
+| Project | `.claude/statuskit.toml` | Shared team configuration |
+| User | `~/.claude/statuskit.toml` | Global personal defaults |
+
+### Basic Configuration
+
+```toml
+# Modules to display (in order)
+modules = ["model", "git", "usage_limits"]
+
+# Enable debug output
+debug = false
+```
+
+### Module Configuration
+
+Each module can be configured in its own section:
+
+```toml
+[git]
+show_branch = true
+commit_age_format = "compact"
+
+[usage_limits]
+show_session = true
+show_weekly = true
+multiline = false
+```
+
+## Module Reference
+
+### `model` Module
+
+Displays model name, session duration, and context window usage.
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `show_duration` | bool | `true` | Show session duration |
+| `show_context` | bool | `true` | Show context window usage |
+| `context_format` | string | `"free"` | Context display format (see below) |
+| `context_compact` | bool | `false` | Use compact numbers (e.g., `150k` instead of `150,000`) |
+| `context_threshold_green` | int | `50` | Percentage of free context to show green |
+| `context_threshold_yellow` | int | `25` | Percentage of free context to show yellow (below = red) |
+
+**`context_format` values:**
+
+| Value | Output example |
+|-------|----------------|
+| `"free"` | `150,000 free (75.0%)` |
+| `"used"` | `50,000 used (25.0%)` |
+| `"ratio"` | `50,000/200,000 (25.0%)` |
+| `"bar"` | `[███████░░░] 70%` |
+
+### `git` Module
+
+Displays git branch, remote status, changes, last commit, and project/worktree location.
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `show_project` | bool | `true` | Show project (repository) name |
+| `show_worktree` | bool | `true` | Show worktree name with 🌲 indicator |
+| `show_folder` | bool | `true` | Show current subfolder relative to repo root |
+| `show_branch` | bool | `true` | Show current branch name |
+| `show_remote_status` | bool | `true` | Show ahead/behind/diverged status |
+| `show_changes` | bool | `true` | Show staged/modified/untracked counts |
+| `show_commit` | bool | `true` | Show last commit hash and age |
+| `commit_age_format` | string | `"relative"` | Commit age format (see below) |
+
+**`commit_age_format` values:**
+
+| Value | Output example |
+|-------|----------------|
+| `"relative"` | `2 hours ago` |
+| `"compact"` | `2h` |
+
+### `usage_limits` Module
+
+Displays API usage limits with color-coded warnings based on consumption rate.
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `show_session` | bool | `true` | Show 5-hour session limit |
+| `show_weekly` | bool | `true` | Show 7-day weekly limit |
+| `show_sonnet` | bool | `false` | Show Sonnet-only weekly limit |
+| `show_reset_time` | bool | `true` | Show time until reset |
+| `multiline` | bool | `true` | Display each limit on separate line |
+| `show_progress_bar` | bool | `false` | Show visual progress bar |
+| `bar_width` | int | `10` | Progress bar width in characters |
+| `session_time_format` | string | `"remaining"` | Time format for session limit |
+| `weekly_time_format` | string | `"reset_at"` | Time format for weekly limit |
+| `sonnet_time_format` | string | `"reset_at"` | Time format for Sonnet limit |
+| `cache_ttl` | int | `60` | Cache lifetime in seconds |
+
+**Time format values:**
+
+| Value | Output example |
+|-------|----------------|
+| `"remaining"` | `2h 30m` |
+| `"reset_at"` | `Thu 17:00` |
+
+**Color coding:** Usage is colored based on consumption rate vs elapsed time:
+- 🟢 Green — on track or under
+- 🟡 Yellow — approaching the limit trajectory
+- 🔴 Red — ahead of pace, may hit limit
+
+## License
+
+MIT — see [LICENSE](https://github.com/NoNameItem/claude-tools/blob/master/LICENSE) for details.

claude_statuskit-0.3.0.dist-info/RECORD

@@ -0,0 +1,22 @@
+statuskit/__init__.py,sha256=5YT6UVacwSqav_yy0eTZykROhp3LjbdK8m-Wkia32VY,3642
+statuskit/cli.py,sha256=IRXKUCIiQX-HGjNBeo_ZiA_55L6lUQa1_zsznp2i64Q,1833
+statuskit/core/__init__.py,sha256=ws2smu4R-UF5LWFM35yuGBUuKGuOiy6U68RKmEq3Aqk,37
+statuskit/core/config.py,sha256=HqYhYWv-1VDMDV48R43dSYcJ9qf_ZKdjmvPk3rfjLOQ,2439
+statuskit/core/loader.py,sha256=ehmwwITKZRLgc6yxyOPVqQchHQQFtVSoGn33_Sy_LK0,992
+statuskit/core/models.py,sha256=-9SFMFNCUpYOERLCmta2jdoa-eKl_xGDoYWw4iIuZ0Y,3837
+statuskit/modules/__init__.py,sha256=8Nq_CdDeUtNUtikAqrZnPYmPezDPU_AmHfRTmwfNf7M,163
+statuskit/modules/base.py,sha256=kOuZKZgU3S8oxTENaGuHNuhiYMxkt_MVUlw1C22Hs0M,952
+statuskit/modules/git.py,sha256=ipg_ibj4HKiN26tt_J9Z0IGS7D413nkLIymb6rqxFwQ,12439
+statuskit/modules/model.py,sha256=iJAiFWsjSmTDaMVubabatBLVLOeQbj4TVxHc417hb78,4369
+statuskit/modules/usage_limits.py,sha256=83UhiceuZf0XkxOewdQq49exaVYlibTAkyO154ONfYw,15361
+statuskit/setup/__init__.py,sha256=TlrT2k5z4QUG9Op3w7Ho0lHQCu86NnJCVrJteqnC6NE,35
+statuskit/setup/commands.py,sha256=7ZpsKrscQJj5TPeibY8T-zeiz64jvCGjYD7_htK8kFo,6835
+statuskit/setup/config.py,sha256=IdRHxpknOM2Ho-QwTV98-PXqw1tY_lD72gk6_0xFdm8,645
+statuskit/setup/gitignore.py,sha256=euRZ2lFG3KAM13jMGUt6oiIsjQMifE1zrJuiH3eNe20,1566
+statuskit/setup/hooks.py,sha256=L2owfXpKZle1VAde9c8pPqaR8uXht4cC-44MkWsJMTw,1471
+statuskit/setup/paths.py,sha256=Z_eogXqmsITnlEh9ifWqDMs7YZvrbtWShLT89ZLsi6I,877
+statuskit/setup/ui.py,sha256=Lz9CX02tqqn3GF2EqHsvo2olDd_D7rbN6_u-T5nZ6q4,956
+claude_statuskit-0.3.0.dist-info/METADATA,sha256=ylVqwDjyaR-Dm1uFgobvGK4EheWIe9624JWZ0cEzL2A,7115
+claude_statuskit-0.3.0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+claude_statuskit-0.3.0.dist-info/entry_points.txt,sha256=6C0Zr7X1ues0_IA2XtSqH7I64SL7qhBxXd612xEGbMo,45
+claude_statuskit-0.3.0.dist-info/RECORD,,

claude_statuskit-0.3.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.28.0
+Root-Is-Purelib: true
+Tag: py3-none-any

claude_statuskit-0.3.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+statuskit = statuskit:main

statuskit/__init__.py

@@ -0,0 +1,120 @@
+"""Modular statusline kit for Claude Code."""
+
+import json
+import sys
+from argparse import Namespace
+
+from termcolor import colored
+
+from .cli import create_parser
+from .core.config import load_config
+from .core.loader import load_modules
+from .core.models import RenderContext, StatusInput
+
+
+def _handle_setup(args: Namespace) -> None:
+    """Handle setup command."""
+    from .setup.commands import check_installation
+    from .setup.paths import Scope
+    from .setup.ui import ConsoleUI
+
+    if args.check:
+        print(check_installation())
+        return
+
+    scope = Scope(args.scope)
+    ui = None if args.force else ConsoleUI()
+
+    if args.remove:
+        _handle_remove(scope, args.force, ui)
+    else:
+        _handle_install(scope, args.force, ui)
+
+
+def _handle_remove(scope, force: bool, ui) -> None:
+    """Handle setup --remove command."""
+    from .setup.commands import remove_hook
+
+    result = remove_hook(scope, force=force, ui=ui)
+    if result.not_installed:
+        print(f"statuskit is not installed at {scope.value} scope.")
+    elif result.success:
+        print(f"\u2713 Removed statusline hook from {scope.value} scope.")
+    else:
+        print(f"Error: {result.message}")
+        sys.exit(1)
+
+
+def _handle_install(scope, force: bool, ui) -> None:
+    """Handle setup install command."""
+    from .setup.commands import install_hook
+
+    result = install_hook(scope, force=force, ui=ui)
+    if result.higher_scope_installed and result.higher_scope:
+        print(f"statuskit is already installed at {result.higher_scope.value} scope.")
+        print("The hook will work for this project too.")
+        if result.config_created:
+            print(f"\u2713 Created config file at {scope.value} scope.")
+    elif result.already_installed:
+        print(f"statuskit is already installed at {scope.value} scope.")
+        if result.config_created:
+            print("\u2713 Created config file.")
+    elif result.success:
+        print(f"\u2713 Added statusline hook to {scope.value} scope.")
+        if result.backup_created:
+            print("\u2713 Created backup of previous settings.")
+        if result.config_created:
+            print("\u2713 Created config file.")
+        if result.gitignore_updated:
+            print("\u2713 Added .claude/*.local.* to .gitignore")
+        print("\nRun `claude` to see your new statusline!")
+    else:
+        print(f"Error: {result.message}")
+        sys.exit(1)
+
+
+def _render_statusline() -> None:
+    """Read from stdin and render statusline."""
+    config = load_config()
+
+    try:
+        raw_data = json.load(sys.stdin)
+        data = StatusInput.from_dict(raw_data)
+    except Exception as e:
+        if config.debug:
+            print(colored(f"[!] Failed to parse input: {e}", "red"))
+        return
+
+    ctx = RenderContext(debug=config.debug, data=data, cache_dir=config.cache_dir)
+    modules = load_modules(config, ctx)
+
+    for mod in modules:
+        try:
+            output = mod.render()
+            if output:
+                print(output)
+        except Exception as e:
+            if config.debug:
+                print(colored(f"[!] {mod.name}: {e}", "red"))
+
+
+def main() -> None:
+    """Entry point for statuskit command."""
+    parser = create_parser()
+    args = parser.parse_args()
+
+    if args.command == "setup":
+        _handle_setup(args)
+        return
+
+    if sys.stdin.isatty():
+        print("statuskit: reads JSON from stdin")
+        print("Usage: echo '{...}' | statuskit")
+        print("\nRun 'statuskit setup' to configure Claude Code integration.")
+        return
+
+    _render_statusline()
+
+
+if __name__ == "__main__":
+    main()

statuskit/cli.py

@@ -0,0 +1,68 @@
+"""CLI argument parsing for statuskit."""
+
+import argparse
+from importlib.metadata import version
+
+MODULES_HELP = """
+Built-in modules:
+  model                  Display current Claude model name
+  git                    Show git branch and status
+  beads                  Display active beads tasks
+  quota                  Track token usage
+"""
+
+
+def get_version() -> str:
+    """Get statuskit version from package metadata."""
+    try:
+        return version("statuskit")
+    except Exception:
+        return "0.1.0"  # fallback for development
+
+
+def create_parser() -> argparse.ArgumentParser:
+    """Create argument parser for statuskit CLI."""
+    parser = argparse.ArgumentParser(
+        prog="statuskit",
+        description="Modular statusline for Claude Code",
+        epilog=MODULES_HELP,
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+    parser.add_argument(
+        "-V",
+        "--version",
+        action="version",
+        version=f"statuskit {get_version()}",
+    )
+
+    subparsers = parser.add_subparsers(dest="command")
+
+    # setup subcommand
+    setup_parser = subparsers.add_parser(
+        "setup",
+        help="Configure Claude Code integration",
+    )
+    setup_parser.add_argument(
+        "-s",
+        "--scope",
+        choices=["user", "project", "local"],
+        default="user",
+        help="Installation scope (default: user)",
+    )
+    setup_parser.add_argument(
+        "--check",
+        action="store_true",
+        help="Check installation status (all scopes)",
+    )
+    setup_parser.add_argument(
+        "--remove",
+        action="store_true",
+        help="Remove integration (requires --scope)",
+    )
+    setup_parser.add_argument(
+        "--force",
+        action="store_true",
+        help="Skip confirmations, backup and overwrite",
+    )
+
+    return parser

statuskit/core/__init__.py

@@ -0,0 +1 @@
+"""Core statuskit infrastructure."""

statuskit/core/config.py

@@ -0,0 +1,73 @@
+"""Configuration loading for statuskit."""
+
+import tomllib
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from termcolor import colored
+
+# Kept for backward compatibility in tests
+CONFIG_PATH = Path.home() / ".claude" / "statuskit.toml"
+DEFAULT_CACHE_DIR = Path.home() / ".cache" / "statuskit"
+
+
+def _get_config_paths() -> list[Path]:
+    """Get config paths in priority order (highest first)."""
+    return [
+        Path(".claude") / "statuskit.local.toml",  # Local (highest)
+        Path(".claude") / "statuskit.toml",  # Project
+        Path.home() / ".claude" / "statuskit.toml",  # User (lowest)
+    ]
+
+
+@dataclass
+class Config:
+    """Statuskit configuration."""
+
+    debug: bool = False
+    modules: list[str] = field(default_factory=lambda: ["model", "git", "beads", "quota"])
+    module_configs: dict[str, dict] = field(default_factory=dict)
+    cache_dir: Path = field(default_factory=lambda: DEFAULT_CACHE_DIR)
+
+    def get_module_config(self, name: str) -> dict:
+        """Get configuration for a specific module."""
+        return self.module_configs.get(name, {})
+
+
+def load_config() -> Config:
+    """Load configuration from TOML files.
+
+    Searches in priority order:
+    1. .claude/statuskit.local.toml (Local)
+    2. .claude/statuskit.toml (Project)
+    3. ~/.claude/statuskit.toml (User)
+
+    Returns defaults if no config file exists.
+    Shows error and returns defaults if file is invalid.
+    """
+    for config_path in _get_config_paths():
+        if config_path.exists():
+            try:
+                with config_path.open("rb") as f:
+                    data = tomllib.load(f)
+            except (tomllib.TOMLDecodeError, OSError) as e:
+                print(colored(f"[!] Config error in {config_path}: {e}", "red"))
+                return Config()
+
+            # Extract module configs
+            module_configs = {
+                k: v for k, v in data.items() if isinstance(v, dict) and k not in ("debug", "modules", "cache_dir")
+            }
+
+            # Parse cache_dir
+            cache_dir_str = data.get("cache_dir")
+            cache_dir = Path(cache_dir_str).expanduser() if cache_dir_str else DEFAULT_CACHE_DIR
+
+            return Config(
+                debug=data.get("debug", False),
+                modules=data.get("modules", Config().modules),
+                module_configs=module_configs,
+                cache_dir=cache_dir,
+            )
+
+    return Config()

statuskit/core/loader.py

@@ -0,0 +1,33 @@
+"""Module loader for statuskit."""
+
+from statuskit.core.config import Config
+from statuskit.core.models import RenderContext
+from statuskit.modules import git, model, usage_limits
+from statuskit.modules.base import BaseModule
+
+BUILTIN_MODULES: dict[str, type[BaseModule]] = {
+    "model": model.ModelModule,
+    "usage_limits": usage_limits.UsageLimitsModule,
+    "git": git.GitModule,
+    # "beads": ...,  # v0.3
+}
+
+
+def load_modules(config: Config, ctx: RenderContext) -> list[BaseModule]:
+    """Load modules based on configuration.
+
+    Args:
+        config: Statuskit configuration
+        ctx: Render context for modules
+
+    Returns:
+        List of instantiated modules
+    """
+    modules = []
+    for name in config.modules:
+        if name in BUILTIN_MODULES:
+            module_config = config.get_module_config(name)
+            modules.append(BUILTIN_MODULES[name](ctx, module_config))
+        elif ctx.debug:
+            print(f"[!] Unknown module: {name}")
+    return modules

statuskit/core/models.py

@@ -0,0 +1,142 @@
+"""Data types for statuskit."""
+
+from dataclasses import dataclass
+from pathlib import Path
+
+
+@dataclass
+class Model:
+    """Model information from Claude Code."""
+
+    id: str | None
+    display_name: str
+
+
+@dataclass
+class Workspace:
+    """Workspace paths from Claude Code."""
+
+    current_dir: str
+    project_dir: str
+
+
+@dataclass
+class Cost:
+    """Cost and timing information from Claude Code."""
+
+    total_cost_usd: float | None
+    total_duration_ms: int | None
+    total_api_duration_ms: int | None
+    total_lines_added: int | None
+    total_lines_removed: int | None
+
+
+@dataclass
+class CurrentUsage:
+    """Current context window usage."""
+
+    input_tokens: int
+    output_tokens: int
+    cache_creation_input_tokens: int
+    cache_read_input_tokens: int
+
+
+@dataclass
+class ContextWindow:
+    """Context window information from Claude Code."""
+
+    context_window_size: int | None
+    total_input_tokens: int | None
+    total_output_tokens: int | None
+    current_usage: CurrentUsage | None
+
+
+@dataclass
+class StatusInput:
+    """Parsed input from Claude Code status hook."""
+
+    session_id: str | None
+    cwd: str | None
+    model: Model | None
+    workspace: Workspace | None
+    cost: Cost | None
+    context_window: ContextWindow | None
+
+    @classmethod
+    def from_dict(cls, data: dict) -> "StatusInput":
+        """Parse JSON dict into StatusInput dataclass.
+
+        Missing fields become None.
+        """
+        model_data = data.get("model")
+        model = (
+            Model(
+                id=model_data.get("id"),
+                display_name=model_data.get("display_name", "Unknown"),
+            )
+            if model_data
+            else None
+        )
+
+        workspace_data = data.get("workspace")
+        workspace = (
+            Workspace(
+                current_dir=workspace_data.get("current_dir", ""),
+                project_dir=workspace_data.get("project_dir", ""),
+            )
+            if workspace_data
+            else None
+        )
+
+        cost_data = data.get("cost")
+        cost = (
+            Cost(
+                total_cost_usd=cost_data.get("total_cost_usd"),
+                total_duration_ms=cost_data.get("total_duration_ms"),
+                total_api_duration_ms=cost_data.get("total_api_duration_ms"),
+                total_lines_added=cost_data.get("total_lines_added"),
+                total_lines_removed=cost_data.get("total_lines_removed"),
+            )
+            if cost_data
+            else None
+        )
+
+        ctx_data = data.get("context_window")
+        context_window = None
+        if ctx_data:
+            usage_data = ctx_data.get("current_usage")
+            current_usage = (
+                CurrentUsage(
+                    input_tokens=usage_data.get("input_tokens", 0),
+                    output_tokens=usage_data.get("output_tokens", 0),
+                    cache_creation_input_tokens=usage_data.get("cache_creation_input_tokens", 0),
+                    cache_read_input_tokens=usage_data.get("cache_read_input_tokens", 0),
+                )
+                if usage_data
+                else None
+            )
+
+            context_window = ContextWindow(
+                context_window_size=ctx_data.get("context_window_size"),
+                total_input_tokens=ctx_data.get("total_input_tokens"),
+                total_output_tokens=ctx_data.get("total_output_tokens"),
+                current_usage=current_usage,
+            )
+
+        return cls(
+            session_id=data.get("session_id"),
+            cwd=data.get("cwd"),
+            model=model,
+            workspace=workspace,
+            cost=cost,
+            context_window=context_window,
+        )
+
+
+@dataclass
+class RenderContext:
+    """Context passed to modules for rendering."""
+
+    debug: bool
+    data: StatusInput
+    cache_dir: Path | None = None

statuskit/modules/__init__.py

@@ -0,0 +1,6 @@
+"""Statuskit modules."""
+
+from statuskit.core.models import RenderContext
+from statuskit.modules.base import BaseModule
+
+__all__ = ["BaseModule", "RenderContext"]