claude-lean 0.1.0__py3-none-any.whl

claude_lean/__init__.py

@@ -0,0 +1,9 @@
+"""claude-lean — get 5x more from your Claude Code token budget."""
+
+__version__ = "0.1.0"
+__author__ = "vipin"
+
+from claude_lean.common.tokenizer import count_tokens
+from claude_lean.common.claude_paths import ClaudePaths
+
+__all__ = ["__version__", "count_tokens", "ClaudePaths"]

claude_lean/__main__.py

@@ -0,0 +1,6 @@
+"""Entry point for `python -m claude_lean`."""
+
+from claude_lean.cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

claude_lean/apply/__init__.py

@@ -0,0 +1 @@
+"""Apply subsystem: write recommended changes with backup + dry-run safety."""

claude_lean/apply/generator.py

@@ -0,0 +1,180 @@
+"""Generate optimized settings.json + CLAUDE.md based on wizard input."""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+from claude_lean.apply.wizard import WizardResult
+from claude_lean.audit.rules.unused_plugins import LIKELY_UNUSED_FOR_ENGINEERING
+from claude_lean.common.claude_paths import ClaudePaths
+
+
+# Plugin packs to always keep enabled for engineering work
+_CORE_ENG_PLUGINS = {
+    "engineering-skills",
+    "engineering-advanced-skills",
+    "superpowers",
+    "context7",
+    "github",
+    "code-review",
+    "feature-dev",
+    "code-simplifier",
+    "self-improving-agent",
+}
+
+# Plugin packs that depend on a specific stack
+_STACK_TO_PLUGINS = {
+    "frontend": {"frontend-design", "playwright"},
+    "javascript/typescript": {"frontend-design", "playwright"},
+}
+
+# Non-engineering work areas that need their corresponding plugins
+_WORK_TO_PLUGINS = {
+    "marketing": {"marketing-skills", "content-creator"},
+    "sales": {"business-growth-skills"},
+    "finance": {"finance-skills"},
+    "product": {"product-skills"},
+    "regulatory": {"ra-qm-skills"},
+}
+
+
+@dataclass
+class GeneratorPlan:
+    """The proposed changes; render to diff before applying."""
+
+    new_settings: dict[str, Any]
+    old_settings: dict[str, Any]
+    new_claude_md: str
+    old_claude_md: str
+    plugin_disables: list[str]
+    plugin_keeps: list[str]
+    settings_path: Path
+    claude_md_path: Path
+
+    @property
+    def has_changes(self) -> bool:
+        return self.new_settings != self.old_settings or self.new_claude_md != self.old_claude_md
+
+
+def build_plan(paths: ClaudePaths, wizard: WizardResult) -> GeneratorPlan:
+    """Build a GeneratorPlan from current state + wizard input."""
+    old_settings = _load_json(paths.settings_json)
+    new_settings = _optimize_settings(old_settings, wizard)
+
+    old_claude_md = paths.global_claude_md.read_text(encoding="utf-8") if paths.global_claude_md.is_file() else ""
+    new_claude_md = _optimize_claude_md(old_claude_md, wizard)
+
+    # Diff plugin states for the human summary
+    old_enabled = set(_enabled_keys(old_settings))
+    new_enabled = set(_enabled_keys(new_settings))
+    disables = sorted(old_enabled - new_enabled)
+    keeps = sorted(new_enabled)
+
+    return GeneratorPlan(
+        new_settings=new_settings,
+        old_settings=old_settings,
+        new_claude_md=new_claude_md,
+        old_claude_md=old_claude_md,
+        plugin_disables=disables,
+        plugin_keeps=keeps,
+        settings_path=paths.settings_json,
+        claude_md_path=paths.global_claude_md,
+    )
+
+
+def write_plan(plan: GeneratorPlan) -> None:
+    """Write the plan to disk. Caller is responsible for creating backups first."""
+    plan.settings_path.parent.mkdir(parents=True, exist_ok=True)
+    plan.settings_path.write_text(json.dumps(plan.new_settings, indent=2) + "\n", encoding="utf-8")
+    plan.claude_md_path.parent.mkdir(parents=True, exist_ok=True)
+    plan.claude_md_path.write_text(plan.new_claude_md, encoding="utf-8")
+
+
+# ---- internals ----
+
+
+def _load_json(path: Path) -> dict[str, Any]:
+    if not path.is_file():
+        return {}
+    try:
+        return json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError):
+        return {}
+
+
+def _enabled_keys(settings: dict[str, Any]) -> list[str]:
+    raw = settings.get("enabledPlugins", {})
+    if not isinstance(raw, dict):
+        return []
+    return [k for k, v in raw.items() if v]
+
+
+def _optimize_settings(old: dict[str, Any], wizard: WizardResult) -> dict[str, Any]:
+    """Produce a new settings.json keeping the structure but trimming plugins."""
+    out = dict(old)  # shallow copy
+    plugins = dict(out.get("enabledPlugins", {}))
+
+    # Decide which plugin keys to keep
+    needed_plugin_names = set(_CORE_ENG_PLUGINS)
+    for stack in wizard.primary_stacks:
+        needed_plugin_names.update(_STACK_TO_PLUGINS.get(stack, set()))
+    for work in wizard.non_eng_work:
+        needed_plugin_names.update(_WORK_TO_PLUGINS.get(work, set()))
+
+    aggressive = wizard.aggressiveness == "aggressive"
+    conservative = wizard.aggressiveness == "conservative"
+
+    for key in list(plugins.keys()):
+        plugin_name = key.split("@", 1)[0]
+        if plugin_name in needed_plugin_names:
+            plugins[key] = True
+            continue
+        if plugin_name in LIKELY_UNUSED_FOR_ENGINEERING and not conservative:
+            plugins[key] = False
+            continue
+        if aggressive and plugin_name not in _CORE_ENG_PLUGINS:
+            plugins[key] = False
+            continue
+        # Otherwise leave as-is
+
+    out["enabledPlugins"] = plugins
+    return out
+
+
+def _optimize_claude_md(old: str, wizard: WizardResult) -> str:
+    """Rewrite CLAUDE.md to remove forcing rules and add stack hints."""
+    lines = old.splitlines()
+    cleaned: list[str] = []
+
+    for line in lines:
+        stripped = line.strip().lower()
+        # Drop "always use all agents" and similar forcing rules
+        if "always use" in stripped and "agent" in stripped:
+            cleaned.append(
+                "- Use agents when work is specialized or parallelizable, "
+                "not for simple edits"
+            )
+            continue
+        if "always use all" in stripped:
+            continue  # filtered out
+        cleaned.append(line)
+
+    # Add a stack-aware hint if not already present
+    stack_hint = _stack_hint(wizard.primary_stacks)
+    if stack_hint and stack_hint not in "\n".join(cleaned):
+        cleaned.append(stack_hint)
+
+    # Trailing newline discipline
+    text = "\n".join(cleaned).rstrip() + "\n"
+    return text
+
+
+def _stack_hint(stacks: list[str]) -> str | None:
+    if "python" in stacks and "ml/ai" in stacks:
+        return "- Prefer MLX over PyTorch for local ML on Apple Silicon when possible"
+    if "rust" in stacks:
+        return "- Default to safe Rust; only reach for unsafe when measurably necessary"
+    return None

claude_lean/apply/memory_cleaner.py

@@ -0,0 +1,77 @@
+"""Remove stale snapshot sections from memory files, keeping policy/why intact."""
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+
+
+# Heading patterns that mark a snapshot section (case-insensitive)
+_SNAPSHOT_HEADING = re.compile(
+    r"^(\*\*)?(setup\s+state|state\s+\(as\s+of|snapshot|installed\s+as\s+of|current\s+state)",
+    re.IGNORECASE,
+)
+
+
+def clean_memory_body(text: str) -> tuple[str, bool]:
+    """Remove snapshot sections from a memory file's body.
+
+    Returns ``(new_text, changed)``. The frontmatter is preserved untouched.
+    """
+    if not text.startswith("---\n"):
+        return text, False
+
+    end = text.find("\n---\n", 4)
+    if end == -1:
+        return text, False
+
+    frontmatter = text[: end + 5]
+    body = text[end + 5 :]
+
+    new_body, changed = _strip_snapshot_blocks(body)
+    if not changed:
+        return text, False
+    return frontmatter + new_body, True
+
+
+def clean_memory_file(path: Path) -> bool:
+    """In-place clean a memory file. Returns True if anything changed."""
+    try:
+        text = path.read_text(encoding="utf-8")
+    except OSError:
+        return False
+    new_text, changed = clean_memory_body(text)
+    if not changed:
+        return False
+    path.write_text(new_text, encoding="utf-8")
+    return True
+
+
+def _strip_snapshot_blocks(body: str) -> tuple[str, bool]:
+    """Drop sections that look like dated snapshots."""
+    lines = body.splitlines(keepends=True)
+    out: list[str] = []
+    skipping = False
+    changed = False
+
+    for line in lines:
+        if skipping:
+            # Stop skipping at the next blank-line-then-heading or end of paragraph
+            if line.strip() == "":
+                # Lookahead would help, but stay simple: treat blank as end of block
+                skipping = False
+                # Don't emit the blank line (we already consumed the section)
+                continue
+            # Still in snapshot block; drop
+            continue
+
+        # Detect start of snapshot section
+        stripped = line.strip()
+        if _SNAPSHOT_HEADING.search(stripped):
+            skipping = True
+            changed = True
+            continue
+
+        out.append(line)
+
+    return "".join(out), changed

claude_lean/apply/wizard.py

@@ -0,0 +1,107 @@
+"""Interactive wizard that asks the user about their stack and returns a plan."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+from rich.console import Console
+from rich.prompt import Prompt, Confirm
+
+
+_ENGINEERING_STACKS = ["python", "javascript/typescript", "rust", "go", "ml/ai", "devops", "frontend", "mobile", "other"]
+_NON_ENG_WORK = ["marketing", "sales", "finance", "product", "regulatory", "none"]
+
+
+@dataclass
+class WizardResult:
+    """User's choices, ready to feed into the generator."""
+
+    primary_stacks: list[str] = field(default_factory=list)
+    non_eng_work: list[str] = field(default_factory=list)
+    aggressiveness: str = "balanced"  # conservative | balanced | aggressive
+    confirm_apply: bool = False
+
+
+def run_wizard(*, console: Console | None = None) -> WizardResult:
+    """Run the interactive wizard. Returns the user's choices."""
+    console = console or Console()
+    console.print()
+    console.rule("[bold]claude-lean apply[/bold]")
+    console.print()
+    console.print("A few questions to tailor recommendations to your work.")
+    console.print()
+
+    primary = _multi_select(console, "What's your primary stack?", _ENGINEERING_STACKS)
+    non_eng = _multi_select(
+        console,
+        "Any non-engineering work types? ('none' is fine)",
+        _NON_ENG_WORK,
+        default_index=len(_NON_ENG_WORK) - 1,
+    )
+    aggressiveness = _single_select(
+        console,
+        "How aggressive should optimizations be?",
+        ["conservative", "balanced", "aggressive"],
+        default="balanced",
+    )
+    confirm = Confirm.ask(
+        "Apply changes now? (Will show diff first; nothing is destructive)",
+        default=False,
+        console=console,
+    )
+
+    return WizardResult(
+        primary_stacks=primary,
+        non_eng_work=non_eng,
+        aggressiveness=aggressiveness,
+        confirm_apply=confirm,
+    )
+
+
+def _multi_select(
+    console: Console,
+    prompt: str,
+    choices: list[str],
+    *,
+    default_index: int | None = None,
+) -> list[str]:
+    """Naive stdlib-friendly multi-select: comma-separated indices."""
+    console.print(f"[bold]{prompt}[/bold]")
+    for i, c in enumerate(choices, start=1):
+        marker = " (default)" if default_index == i - 1 else ""
+        console.print(f"  [cyan]{i}[/cyan]. {c}{marker}")
+    default_str = str(default_index + 1) if default_index is not None else ""
+    raw = Prompt.ask(
+        "Enter numbers separated by commas",
+        default=default_str,
+        console=console,
+        show_default=bool(default_str),
+    )
+    selected: list[str] = []
+    for chunk in raw.split(","):
+        chunk = chunk.strip()
+        if not chunk:
+            continue
+        try:
+            idx = int(chunk)
+            if 1 <= idx <= len(choices):
+                selected.append(choices[idx - 1])
+        except ValueError:
+            pass
+    console.print()
+    return selected
+
+
+def _single_select(
+    console: Console,
+    prompt: str,
+    choices: list[str],
+    *,
+    default: str,
+) -> str:
+    return Prompt.ask(
+        prompt,
+        choices=choices,
+        default=default,
+        console=console,
+    )

claude_lean/audit/__init__.py

@@ -0,0 +1,7 @@
+"""Audit subsystem: read-only inspection of ~/.claude/."""
+
+from claude_lean.audit.scanner import scan
+from claude_lean.audit.analyzer import analyze
+from claude_lean.audit.report import render_terminal, render_json
+
+__all__ = ["scan", "analyze", "render_terminal", "render_json"]

claude_lean/audit/analyzer.py

@@ -0,0 +1,51 @@
+"""Run all registered rules over an inventory and produce a finding list."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+from claude_lean.audit.rules import all_rules
+from claude_lean.audit.rules._base import Finding, Severity
+from claude_lean.audit.scanner import Inventory
+
+
+@dataclass
+class AuditResult:
+    """The full audit output."""
+
+    inventory: Inventory
+    findings: list[Finding] = field(default_factory=list)
+
+    @property
+    def total_estimated_savings(self) -> int:
+        return sum(f.estimated_savings_tokens for f in self.findings)
+
+    @property
+    def critical_count(self) -> int:
+        return sum(1 for f in self.findings if f.severity == Severity.CRITICAL)
+
+    @property
+    def warn_count(self) -> int:
+        return sum(1 for f in self.findings if f.severity == Severity.WARN)
+
+    @property
+    def info_count(self) -> int:
+        return sum(1 for f in self.findings if f.severity == Severity.INFO)
+
+    @property
+    def multiplier_gain(self) -> float:
+        """Estimated tokens-per-conversation multiplier after applying recommendations."""
+        baseline = self.inventory.estimated_system_prompt_tokens
+        if baseline <= 0:
+            return 1.0
+        saved = self.total_estimated_savings
+        remaining = max(baseline - saved, 1)
+        return round(baseline / remaining, 2)
+
+
+def analyze(inventory: Inventory) -> AuditResult:
+    """Run every registered rule and collect findings."""
+    findings: list[Finding] = []
+    for rule in all_rules():
+        findings.extend(rule.evaluate(inventory))
+    return AuditResult(inventory=inventory, findings=findings)

claude_lean/audit/report.py

@@ -0,0 +1,163 @@
+"""Render audit results to terminal (rich) or JSON."""
+
+from __future__ import annotations
+
+import json
+from datetime import datetime, timezone
+
+from rich.console import Console
+from rich.table import Table
+from rich import box
+
+from claude_lean.audit.analyzer import AuditResult
+from claude_lean.audit.rules._base import Severity
+from claude_lean.common.tokenizer import accuracy_label
+
+
+_SEVERITY_GLYPH = {
+    Severity.INFO: "[cyan]ℹ[/cyan]",
+    Severity.WARN: "[yellow]⚠[/yellow]",
+    Severity.CRITICAL: "[red]✖[/red]",
+}
+
+
+def render_terminal(result: AuditResult, console: Console | None = None) -> None:
+    """Render the audit to the terminal using rich."""
+    console = console or Console()
+    inv = result.inventory
+
+    # Header
+    console.print()
+    console.rule(f"[bold]claude-lean audit[/bold] · {inv.claude_home}")
+    console.print(f"[dim]Token measurement: {accuracy_label()}[/dim]")
+    console.print()
+
+    # Headline stats
+    console.print(
+        f"  Plugins enabled: [bold]{sum(1 for p in inv.plugins if p.enabled)}[/bold]  "
+        f"·  Skills: [bold]{sum(len(p.skills) for p in inv.plugins if p.enabled)}[/bold]  "
+        f"·  Agents: [bold]{sum(len(p.agents) for p in inv.plugins if p.enabled)}[/bold]"
+    )
+    console.print(
+        f"  Estimated system-prompt overhead per turn: "
+        f"[bold yellow]{inv.estimated_system_prompt_tokens:,}[/bold yellow] tokens"
+    )
+    console.print()
+
+    # Per-plugin table (top 10 by cost)
+    enabled_plugins = sorted(
+        (p for p in inv.plugins if p.enabled),
+        key=lambda p: p.tokens_total,
+        reverse=True,
+    )
+    top = enabled_plugins[:10]
+    if top:
+        table = Table(
+            title="Top 10 enabled plugins by token cost",
+            box=box.SIMPLE_HEAVY,
+            show_lines=False,
+        )
+        table.add_column("Plugin", style="cyan")
+        table.add_column("Skills", justify="right")
+        table.add_column("Agents", justify="right")
+        table.add_column("Total tokens", justify="right", style="bold")
+        for p in top:
+            table.add_row(
+                p.name,
+                f"{p.tokens_skills:,}",
+                f"{p.tokens_agents:,}",
+                f"{p.tokens_total:,}",
+            )
+        console.print(table)
+        console.print()
+
+    # Findings
+    if result.findings:
+        console.print(
+            f"[bold]Findings:[/bold] "
+            f"[red]{result.critical_count} critical[/red] · "
+            f"[yellow]{result.warn_count} warn[/yellow] · "
+            f"[cyan]{result.info_count} info[/cyan]"
+        )
+        console.print()
+        # Group findings by rule_id
+        by_rule: dict[str, list] = {}
+        for f in result.findings:
+            by_rule.setdefault(f.rule_id, []).append(f)
+        for rule_id, group in by_rule.items():
+            first = group[0]
+            glyph = _SEVERITY_GLYPH.get(first.severity, "·")
+            console.print(f"{glyph} [bold]{rule_id}[/bold] ({len(group)})")
+            for f in group:
+                console.print(f"    {f.title}")
+                if f.estimated_savings_tokens:
+                    console.print(
+                        f"    [dim]→ est. savings: {f.estimated_savings_tokens:,} tokens/turn[/dim]"
+                    )
+            console.print()
+    else:
+        console.print("[green]✓[/green] No anti-patterns detected. Your setup looks clean.")
+        console.print()
+
+    # Bottom line
+    savings = result.total_estimated_savings
+    if savings > 0:
+        console.print(
+            f"  [bold]Estimated tokens saved per turn if applied:[/bold] "
+            f"[green]{savings:,}[/green] tokens  "
+            f"(≈ [bold green]{result.multiplier_gain}×[/bold green] more headroom)"
+        )
+        console.print()
+        console.print(
+            "  Next: run [bold cyan]claude-lean apply[/bold cyan] to act on these recommendations."
+        )
+    console.print()
+
+
+def render_json(result: AuditResult) -> str:
+    """Render the audit as a stable JSON document."""
+    inv = result.inventory
+    doc = {
+        "schema_version": 1,
+        "generated_at": datetime.now(timezone.utc).isoformat(),
+        "claude_home": str(inv.claude_home),
+        "tokenizer_accuracy": accuracy_label(),
+        "totals": {
+            "plugins_enabled": sum(1 for p in inv.plugins if p.enabled),
+            "plugins_installed": len(inv.plugins),
+            "skills_loaded": sum(len(p.skills) for p in inv.plugins if p.enabled),
+            "agents_loaded": sum(len(p.agents) for p in inv.plugins if p.enabled),
+            "estimated_system_prompt_tokens": inv.estimated_system_prompt_tokens,
+            "claude_md_tokens": inv.claude_md_tokens,
+        },
+        "by_plugin": [
+            {
+                "name": p.name,
+                "marketplace": p.marketplace,
+                "enabled": p.enabled,
+                "tokens_skills": p.tokens_skills,
+                "tokens_agents": p.tokens_agents,
+                "tokens_mcp": p.tokens_mcp,
+                "tokens_total": p.tokens_total,
+            }
+            for p in sorted(inv.plugins, key=lambda x: x.tokens_total, reverse=True)
+        ],
+        "findings": [
+            {
+                "rule_id": f.rule_id,
+                "severity": f.severity.value,
+                "title": f.title,
+                "evidence": f.evidence,
+                "suggested_action": f.suggested_action,
+                "estimated_savings_tokens": f.estimated_savings_tokens,
+                "target": f.target,
+                "metadata": f.metadata,
+            }
+            for f in result.findings
+        ],
+        "recommendations_summary": {
+            "estimated_tokens_saved_per_turn": result.total_estimated_savings,
+            "estimated_multiplier_gain": result.multiplier_gain,
+        },
+    }
+    return json.dumps(doc, indent=2, default=str)

claude_lean/audit/rules/__init__.py

@@ -0,0 +1,22 @@
+"""Rule modules — one anti-pattern detector per file."""
+
+from claude_lean.audit.rules._base import Rule, Finding, Severity
+from claude_lean.audit.rules.unused_plugins import UnusedPluginsRule
+from claude_lean.audit.rules.forcing_rules import ForcingRulesRule
+from claude_lean.audit.rules.stale_memory import StaleMemoryRule
+from claude_lean.audit.rules.vague_descriptions import VagueDescriptionsRule
+from claude_lean.audit.rules.memory_near_cap import MemoryNearCapRule
+
+
+def all_rules() -> list[Rule]:
+    """Return all built-in rules, in fire order."""
+    return [
+        UnusedPluginsRule(),
+        ForcingRulesRule(),
+        StaleMemoryRule(),
+        VagueDescriptionsRule(),
+        MemoryNearCapRule(),
+    ]
+
+
+__all__ = ["Rule", "Finding", "Severity", "all_rules"]

claude_lean/audit/rules/_base.py

@@ -0,0 +1,41 @@
+"""Base types for audit rules. A rule looks at the inventory and emits findings."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Protocol, TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from claude_lean.audit.scanner import Inventory
+
+
+class Severity(str, Enum):
+    INFO = "info"
+    WARN = "warn"
+    CRITICAL = "critical"
+
+
+@dataclass
+class Finding:
+    """A single anti-pattern instance discovered by a rule."""
+
+    rule_id: str
+    severity: Severity
+    title: str
+    evidence: str
+    suggested_action: str
+    estimated_savings_tokens: int = 0
+    target: str | None = None  # plugin name / file path / etc.
+    metadata: dict = field(default_factory=dict)
+
+
+class Rule(Protocol):
+    """Audit rule contract."""
+
+    rule_id: str
+    severity: Severity
+    title: str
+
+    def evaluate(self, inventory: "Inventory") -> list[Finding]:
+        ...