ai-agent-rules 0.11.0__py3-none-any.whl → 0.15.8__py3-none-any.whl

{ai_agent_rules-0.11.0.dist-info → ai_agent_rules-0.15.8.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ai-agent-rules
-Version: 0.11.0
+Version: 0.15.8
 Summary: Manage user-level AI agent configurations
 Author-email: Will Pfleger <pfleger.will@gmail.com>
 License-Expression: MIT
@@ -47,14 +47,14 @@ Manage AI agent configurations through symlinks. Keep all your configs in one gi
 
 ## Overview
 
-Consolidates config files for AI coding agents (Claude Code, Goose) into a single source of truth via symlinks:
+Consolidates config files for AI coding agents (Claude Code, Cursor, Goose) into a single source of truth via symlinks:
 
 - Git-tracked configs synced across machines
 - Edit once, apply everywhere
 - Exclude specific files (e.g., company-managed)
 - Per-agent customizations
 
-**Supported:** Claude Code (settings, agents, commands), Goose (hints, config), Shared (AGENTS.md)
+**Supported:** Claude Code (settings, agents, commands), Cursor (settings, keybindings), Goose (hints, config), Shared (AGENTS.md)
 
 ## Installation
 
@@ -75,6 +75,16 @@ This will:
 
 After setup, you can run `ai-rules` from any directory.
 
+### From GitHub (Development)
+
+Install from GitHub to get the latest development code:
+
+```bash
+uvx --from ai-agent-rules ai-rules setup --github
+```
+
+This installs from the main branch and auto-detects the GitHub source for future updates.
+
 ### Local Development
 
 For contributing or local development:
@@ -82,10 +92,11 @@ For contributing or local development:
 ```bash
 git clone https://github.com/wpfleger96/ai-rules.git
 cd ai-rules
-uv tool install -e .
-ai-rules install
+uv run ai-rules install
 ```
 
+Use `uv run ai-rules <command>` to test local changes. The global `ai-rules` command continues to run your installed version (PyPI/GitHub).
+
 ### Updating
 
 Check for and install updates:
@@ -109,6 +120,8 @@ notify_only: false
 
 ```bash
 ai-rules setup                      # One-time setup: install symlinks + make available system-wide
+ai-rules setup --github             # Install from GitHub (pre-release)
+ai-rules setup --profile work       # Setup with a specific profile
 ai-rules upgrade                    # Upgrade to latest version
 ai-rules upgrade --check            # Check for updates without installing
 
@@ -118,7 +131,7 @@ ai-rules install --dry-run          # Preview changes
 ai-rules install --force            # Skip confirmations
 ai-rules install --rebuild-cache    # Rebuild merged settings cache
 
-ai-rules status                     # Check symlink status + optional tools (✓✗⚠○)
+ai-rules status                     # Check symlink status + optional tools + active profile (✓✗⚠○)
 ai-rules diff                       # Show config differences
 ai-rules validate                   # Verify source files exist
 ai-rules update                     # Re-sync after adding files
@@ -145,6 +158,7 @@ ai-rules exclude list                        # List all exclusions
 
 # Manage settings overrides (for machine-specific settings)
 ai-rules override set claude.model "claude-sonnet-4-5-20250929"  # Set simple override
+ai-rules override set cursor.editor.fontSize 14  # Override Cursor font size
 ai-rules override set claude.hooks.SubagentStop[0].hooks[0].command "script.py"  # Array notation
 ai-rules override unset claude.model         # Remove override
 ai-rules override list                       # List all overrides
@@ -185,12 +199,17 @@ settings_overrides:
   claude:
     model: "claude-sonnet-4-5-20250929"  # Override model on personal laptop
     # Other settings inherited from base config/claude/settings.json
+  cursor:
+    editor.fontSize: 14  # Override font size on this machine
   goose:
     provider: "anthropic"
 ```
 
 **Config File Location:**
 - `~/.ai-rules-config.yaml` - User-specific config (exclusions and overrides)
+- `~/.ai-rules/state.yaml` - Active profile and last install timestamp (auto-managed)
+- `~/.ai-rules/cache/` - Merged settings cache (auto-generated)
+- `~/.ai-rules/update_config.yaml` - Update check configuration
 
 ### Settings Overrides - Syncing Configs Across Machines
 
@@ -241,6 +260,64 @@ ai-rules override set claude.modle "sonnet"
 
 Path validation ensures you only set valid overrides that exist in the base settings, preventing typos and configuration errors.
 
+### Cursor Settings
+
+Cursor settings support the same override mechanism as other agents:
+
+```yaml
+# ~/.ai-rules-config.yaml
+settings_overrides:
+  cursor:
+    editor.fontSize: 14
+    terminal.integrated.defaultLocation: "editor"
+```
+
+> **Note:** `keybindings.json` uses direct symlinks without override merging (array structure).
+
+### Profiles - Machine-Specific Configuration
+
+Profiles let you group configuration overrides into named presets. Instead of manually maintaining different `~/.ai-rules-config.yaml` files across machines, define profiles once and select them at install time.
+
+```bash
+# List available profiles
+ai-rules profile list
+
+# View profile details
+ai-rules profile show work
+ai-rules profile show work --resolved  # Show with inheritance
+
+# Check which profile is active
+ai-rules profile current
+
+# Switch to a different profile
+ai-rules profile switch work
+
+# Install with a specific profile
+ai-rules install --profile work
+```
+
+Profiles are stored in `src/ai_rules/config/profiles/` and support inheritance:
+
+```yaml
+# profiles/work.yaml
+name: work
+description: Work laptop with extended context model
+extends: null
+settings_overrides:
+  claude:
+    env:
+      ANTHROPIC_DEFAULT_SONNET_MODEL: "claude-sonnet-4-5-20250929[1m]"
+    model: opusplan
+```
+
+Configuration layers (lowest to highest priority):
+1. Profile overrides
+2. Local `~/.ai-rules-config.yaml` overrides
+
+Your local config always wins, so you can use a profile as a base and tweak specific settings per-machine. Profiles are git-tracked and can be shared across your team.
+
+The active profile is tracked in `~/.ai-rules/state.yaml` and persists across sessions. Use `profile current` to see which profile is active, or `profile switch` to quickly change profiles without re-running the full install.
+
 ## Structure
 
 ```
@@ -250,10 +327,18 @@ config/
 │   ├── settings.json      # → ~/.claude/settings.json
 │   ├── agents/*.md        # → ~/.claude/agents/*.md (dynamic)
 │   └── commands/*.md      # → ~/.claude/commands/*.md (dynamic)
+├── cursor/
+│   ├── settings.json      # → ~/Library/Application Support/Cursor/User/ (macOS)
+│   │                      #    ~/AppData/Roaming/Cursor/User/ (Windows)
+│   │                      #    ~/.config/Cursor/User/ (Linux)
+│   └── keybindings.json   # → (same paths as settings.json)
 └── goose/
     └── config.yaml        # → ~/.config/goose/config.yaml
 ```
 
+> **Note:** The Cursor config files contain the maintainer's personal preferences
+> (e.g., macOS-specific terminal settings). Customize for your environment.
+
 ## Optional Tools
 
 AI Rules automatically installs optional tools that enhance functionality:

{ai_agent_rules-0.11.0.dist-info → ai_agent_rules-0.15.8.dist-info}/RECORD

@@ -1,26 +1,32 @@
-ai_agent_rules-0.11.0.dist-info/licenses/LICENSE,sha256=eRdOpQ8Kaod-FPwMA-sD9U2817DCp0QNub7f_UpqMe0,1070
+ai_agent_rules-0.15.8.dist-info/licenses/LICENSE,sha256=eRdOpQ8Kaod-FPwMA-sD9U2817DCp0QNub7f_UpqMe0,1070
 ai_rules/__init__.py,sha256=h0sNb8H1ED7Dy0IXON1Ww3O8cls08Sr_g1osdcQ-4i0,231
-ai_rules/cli.py,sha256=oSxAP5cZlv6LXW81zhDslMR17lpwwp0Ss_IICdVwNQg,77887
+ai_rules/cli.py,sha256=yi4iAjTRY6LzNtsoZLoHwmdy-TKCz78Q27pYYKszvn4,88918
 ai_rules/completions.py,sha256=7Ymgfzd93Owlscfn6sWkopbbAfT_J5PXnY5vl3CN_Xs,5736
-ai_rules/config.py,sha256=_updV-Uk2eHN1QK0GiVJv_hlvGefloxPZawisK-K9oA,20943
+ai_rules/config.py,sha256=-AbRaAI6LsGjqOHaoHYUIN_KxkfLAtnmH-5ChEQXI4E,21041
 ai_rules/display.py,sha256=dltgyoJZSseP1xrj-YBvj8_TOBSTouoiQMjwdC5d2MI,1225
-ai_rules/mcp.py,sha256=jbUgRaIyglVfwIFu61Dbtsbbk_o87NCTYwVgz4VclQ8,11958
+ai_rules/mcp.py,sha256=BFBD0MWEjbbGOjZmmLwE8atK0KN-ExylA7VeDAZnv-M,11942
+ai_rules/profiles.py,sha256=YI_p39bvwhtUAcgt6vv27ZymWUBSsRNIY4LjDyFOomg,6223
+ai_rules/state.py,sha256=3VHsdDVERMeNlNNK_s-NwjQKTjx5cH9qwu4Oh2_7W-A,1191
 ai_rules/symlinks.py,sha256=gXBVMcDU96pMHXR675ePZSnXKY9d0kEEwXnUazd0xhw,6674
+ai_rules/utils.py,sha256=_mjJzcNbi3-zwQLGVdgqeVUv9eVj0SYI0xebZh3262E,1324
 ai_rules/agents/__init__.py,sha256=VG6BFISMVTETyfs7aAXTa_co6NH_dmvp_5aw09HI35w,32
 ai_rules/agents/base.py,sha256=vVPEkdczTz8oLUS5XdjHrJbARL2kDfaKDwQOVBX6bYI,1981
-ai_rules/agents/claude.py,sha256=5O4e_cOxBdPGYEkL-_pevQquSU7VRb9ohxx6Grn89ko,3756
-ai_rules/agents/goose.py,sha256=7zkXWtSZIdnfCEg3k_2-eUOL9bnIQ2HOInBupELRIrc,1077
+ai_rules/agents/claude.py,sha256=XzlkW-E-4oZIWCZTvUihpzptPTiAKH23ADXlczdKHDM,3789
+ai_rules/agents/cursor.py,sha256=PK7sl64UBVJBySRffAsdvo7Azj7lCEE9G-4NeuSNdKk,2105
+ai_rules/agents/goose.py,sha256=omBEPTc0N8A0KenmDCNIkV5oqJsgeCEespJZVJakigw,1136
 ai_rules/agents/shared.py,sha256=Tj9ll1Z_wZzwM19368r2ku_6aTQYyNCwxzOc_4lXqqg,839
-ai_rules/bootstrap/__init__.py,sha256=HTykRNzbh8-kAByfRlvbeS0pefrbR4VlA4AS-5lwcpY,1840
+ai_rules/bootstrap/__init__.py,sha256=zDqyT51J9K_8Ys2vORgXuPLMlS0c4vONpvlFDKoT5bE,1922
 ai_rules/bootstrap/config.py,sha256=Cp133LLC2xnyM-RRtmKsZ73cSMdm8GVzCmwHjFrcK1I,6970
-ai_rules/bootstrap/installer.py,sha256=5t0XJh4yKtaXxA5SnprK62eNalNUdrKBWQ-TFhIFpKg,6757
-ai_rules/bootstrap/updater.py,sha256=kW9YUy4DT1F1nNRIvjDHkiuNaLoFP7V4RhbDZO0TiKs,6202
+ai_rules/bootstrap/installer.py,sha256=OrlVO6Bkky86_QE9f_UPD0Mol4k642sdDflf7DcegS0,9274
+ai_rules/bootstrap/updater.py,sha256=vytyMV3FsJqJbR56vSU_lICVz4zc93pXorPJzK4CutE,10581
 ai_rules/bootstrap/version.py,sha256=WCj4LwzZk-M62ViOf6qg7mQPk-AlGswwHsJWfv9bEko,1236
-ai_rules/config/AGENTS.md,sha256=BKch0ZjjTZfzBRJ6n_UWrLfrWKu3WtNh7DR-4mRY2-w,11298
+ai_rules/config/AGENTS.md,sha256=zwQCZ8DiK5t0FuXaLGhfDYl5tUro_32U-CrCL3KAY68,11616
 ai_rules/config/chat_agent_hints.md,sha256=lW3nCigFn4iuZ6vsCjntwd-Po7MVGFZynjR9X5__vY0,491
+ai_rules/config/claude/CLAUDE.md,sha256=2BtrA5bS05_z_SQYFreWFVUJ-C9ryln1axNLOS44PD4,13
 ai_rules/config/claude/mcps.json,sha256=yj0WO6sFU4GCciYUBWjzvvfqrBh869doeOC2Pp5EI1Y,3
-ai_rules/config/claude/settings.json,sha256=Kf1U5_F6V-c15ipiwAPwmuqiv1esOvl_uEE8PdaiA4E,2926
+ai_rules/config/claude/settings.json,sha256=MtJgKbyMgjx5fc8P0UVeePySXLJfsKKz9fkVcERp5Ok,2989
 ai_rules/config/claude/agents/code-reviewer.md,sha256=hFyRbuAzliQOmRVTTNAy1unV4Xx5kFb9JlWEwULL7nY,4417
+ai_rules/config/claude/commands/agents-md.md,sha256=9ohpiGf0kC2KkqmkJmx-ZxwrLZwBQYeTZWP3bXily7c,13420
 ai_rules/config/claude/commands/annotate-changelog.md,sha256=a9AL9Os8VLScL0hryHmesrMdusG2z0TTxH6myeu4aVU,5573
 ai_rules/config/claude/commands/comment-cleanup.md,sha256=gNLc36PlplP08By-QK4n44gefgPusSQa0lnLQDGujBA,5296
 ai_rules/config/claude/commands/continue-crash.md,sha256=rRi16p7PyS9IYuanuTUCh6fMmXleSoqbNqZFWzoJR0s,1378
@@ -34,9 +40,14 @@ ai_rules/config/claude/skills/doc-writer/resources/templates.md,sha256=qGkqvY78N
 ai_rules/config/claude/skills/prompt-engineer/SKILL.md,sha256=TA6c1SUvJKy0pQnTwGGj_IbQEXqe4wUrFZJuaBVpNJ4,9664
 ai_rules/config/claude/skills/prompt-engineer/resources/prompt_engineering_guide_2025.md,sha256=h3WlOQTYn1zGymJGSoD6dHCZsOTCe9Tne9a3tuRJFFQ,29592
 ai_rules/config/claude/skills/prompt-engineer/resources/templates.md,sha256=4gIR1i5k-_GxWrZXStFyYAEfqZJvzh1KngZfq1T2pLY,6856
+ai_rules/config/cursor/keybindings.json,sha256=nfCqj_G_WUjUNj6f3hkchMH6M-SHADhh9-GNS95ypEk,291
+ai_rules/config/cursor/settings.json,sha256=uzPbbyVBXJlNl0EKupT-ACDyoMT3-KNhEKKrXtgLIfk,2488
+ai_rules/config/goose/.goosehints,sha256=2BtrA5bS05_z_SQYFreWFVUJ-C9ryln1axNLOS44PD4,13
 ai_rules/config/goose/config.yaml,sha256=N_QzIANL_7WnX5xSrMZN_t94wbrGXXHMleQ6gzzIaC8,1396
-ai_agent_rules-0.11.0.dist-info/METADATA,sha256=nRRbjUL974E67Oz5UlCx1WYKfzUoochYPPOaqPGQiTI,12546
-ai_agent_rules-0.11.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-ai_agent_rules-0.11.0.dist-info/entry_points.txt,sha256=Dnt2pQp6vSWz374RsUNZ5Zh5qmuTy45xR02r5fH_p_E,82
-ai_agent_rules-0.11.0.dist-info/top_level.txt,sha256=1jJObrxql_i5okMXb4dxsiQa_cpjtzwwskVvwedEHow,9
-ai_agent_rules-0.11.0.dist-info/RECORD,,
+ai_rules/config/profiles/default.yaml,sha256=B1sjVz0V11gE1t3_XYXD5HpiaOWPPXEdzzotwVH8UmI,140
+ai_rules/config/profiles/work.yaml,sha256=e982yg7kY6Mp0h6wE94m48s-mK_kpm7zAQ5OYyBIpBo,314
+ai_agent_rules-0.15.8.dist-info/METADATA,sha256=doQIzH2GCY8A97ZVAhdlsfNFJLMgo7IbYvlqXBRq6GI,15749
+ai_agent_rules-0.15.8.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+ai_agent_rules-0.15.8.dist-info/entry_points.txt,sha256=Dnt2pQp6vSWz374RsUNZ5Zh5qmuTy45xR02r5fH_p_E,82
+ai_agent_rules-0.15.8.dist-info/top_level.txt,sha256=1jJObrxql_i5okMXb4dxsiQa_cpjtzwwskVvwedEHow,9
+ai_agent_rules-0.15.8.dist-info/RECORD,,

ai_rules/agents/claude.py

@@ -35,7 +35,9 @@ class ClaudeAgent(Agent):
         """Cached list of all Claude Code symlinks including dynamic agents/commands."""
         result = []
 
-        result.append((Path("~/.claude/CLAUDE.md"), self.config_dir / "AGENTS.md"))
+        result.append(
+            (Path("~/.claude/CLAUDE.md"), self.config_dir / "claude" / "CLAUDE.md")
+        )
 
         settings_file = self.config_dir / "claude" / "settings.json"
         if settings_file.exists():

ai_rules/agents/cursor.py

@@ -0,0 +1,70 @@
+"""Cursor editor agent implementation."""
+
+import sys
+
+from functools import cached_property
+from pathlib import Path
+
+from ai_rules.agents.base import Agent
+
+
+def _get_cursor_target_prefix() -> str:
+    """Get platform-specific Cursor config path with ~ prefix.
+
+    Returns:
+        Path string with ~ prefix for the current platform:
+        - macOS: ~/Library/Application Support/Cursor/User
+        - Windows: ~/AppData/Roaming/Cursor/User
+        - Linux/WSL: ~/.config/Cursor/User
+    """
+    if sys.platform == "darwin":
+        return "~/Library/Application Support/Cursor/User"
+    elif sys.platform == "win32":
+        return "~/AppData/Roaming/Cursor/User"
+    else:  # Linux/WSL
+        return "~/.config/Cursor/User"
+
+
+class CursorAgent(Agent):
+    """Agent for Cursor editor configuration."""
+
+    @property
+    def name(self) -> str:
+        return "Cursor"
+
+    @property
+    def agent_id(self) -> str:
+        return "cursor"
+
+    @property
+    def config_file_name(self) -> str:
+        return "settings.json"
+
+    @property
+    def config_file_format(self) -> str:
+        return "json"
+
+    @cached_property
+    def symlinks(self) -> list[tuple[Path, Path]]:
+        """Cached list of all Cursor symlinks.
+
+        Settings file uses cache-based approach with override merging.
+        Keybindings file uses direct symlink (array structure, no merging).
+        """
+        result = []
+        prefix = _get_cursor_target_prefix()
+
+        # Settings file - use cache if overrides exist
+        settings_file = self.config_dir / "cursor" / "settings.json"
+        if settings_file.exists():
+            target_file = self.config.get_settings_file_for_symlink(
+                "cursor", settings_file
+            )
+            result.append((Path(f"{prefix}/settings.json"), target_file))
+
+        # Keybindings file - direct symlink (no override merging for arrays)
+        keybindings_file = self.config_dir / "cursor" / "keybindings.json"
+        if keybindings_file.exists():
+            result.append((Path(f"{prefix}/keybindings.json"), keybindings_file))
+
+        return result

ai_rules/agents/goose.py

@@ -31,7 +31,10 @@ class GooseAgent(Agent):
         result = []
 
         result.append(
-            (Path("~/.config/goose/.goosehints"), self.config_dir / "AGENTS.md")
+            (
+                Path("~/.config/goose/.goosehints"),
+                self.config_dir / "goose" / ".goosehints",
+            )
         )
 
         config_file = self.config_dir / "goose" / "config.yaml"

ai_rules/bootstrap/__init__.py

@@ -24,8 +24,10 @@ from .config import (
 )
 from .installer import (
     UV_NOT_FOUND_ERROR,
+    ToolSource,
     ensure_statusline_installed,
     get_tool_config_dir,
+    get_tool_source,
     get_tool_version,
     install_tool,
     is_command_available,
@@ -35,10 +37,10 @@ from .updater import (
     UPDATABLE_TOOLS,
     ToolSpec,
     UpdateInfo,
-    check_pypi_updates,
+    check_index_updates,
     check_tool_updates,
     get_tool_by_id,
-    perform_pypi_update,
+    perform_tool_upgrade,
 )
 from .version import get_package_version, is_newer, parse_version
 
@@ -47,8 +49,10 @@ __all__ = [
     "is_newer",
     "parse_version",
     "UV_NOT_FOUND_ERROR",
+    "ToolSource",
     "ensure_statusline_installed",
     "get_tool_config_dir",
+    "get_tool_source",
     "get_tool_version",
     "install_tool",
     "is_command_available",
@@ -56,10 +60,10 @@ __all__ = [
     "UPDATABLE_TOOLS",
     "ToolSpec",
     "UpdateInfo",
-    "check_pypi_updates",
+    "check_index_updates",
     "check_tool_updates",
     "get_tool_by_id",
-    "perform_pypi_update",
+    "perform_tool_upgrade",
     "AutoUpdateConfig",
     "clear_all_pending_updates",
     "clear_pending_update",

ai_rules/bootstrap/installer.py

@@ -6,6 +6,7 @@ import shutil
 import subprocess
 import sys
 
+from enum import Enum, auto
 from pathlib import Path
 
 if sys.version_info >= (3, 11):
@@ -13,7 +14,30 @@ if sys.version_info >= (3, 11):
 else:
     import tomli as tomllib
 
+
+class ToolSource(Enum):
+    """Source from which a tool was installed."""
+
+    PYPI = auto()
+    GITHUB = auto()
+
+
+def make_github_install_url(repo: str) -> str:
+    """Construct GitHub install URL for uv tool install.
+
+    Args:
+        repo: GitHub repository in format "owner/repo"
+
+    Returns:
+        Full git+ssh URL for uv tool install
+    """
+    return f"git+ssh://git@github.com/{repo}.git"
+
+
 UV_NOT_FOUND_ERROR = "uv not found in PATH. Install from https://docs.astral.sh/uv/"
+PACKAGE_NAME = "ai-agent-rules"
+GITHUB_REPO = "wpfleger96/ai-rules"
+STATUSLINE_GITHUB_REPO = "wpfleger96/claude-code-status-line"
 
 
 def _validate_package_name(package_name: str) -> bool:
@@ -50,15 +74,15 @@ def get_tool_config_dir(package_name: str = "ai-agent-rules") -> Path:
     )
 
 
-def get_tool_source(package_name: str) -> str | None:
-    """Detect how a uv tool was installed (PyPI vs local file).
+def get_tool_source(package_name: str) -> ToolSource | None:
+    """Detect how a uv tool was installed.
 
     Args:
         package_name: Name of the uv tool package
 
     Returns:
-        "pypi" if installed from PyPI (no path key in requirements)
-        "local" if installed from local file (has path key)
+        ToolSource.PYPI if installed from PyPI
+        ToolSource.GITHUB if installed from GitHub
         None if tool not installed or receipt file not found
     """
     data_home = os.environ.get("XDG_DATA_HOME", str(Path.home() / ".local" / "share"))
@@ -75,12 +99,12 @@ def get_tool_source(package_name: str) -> str | None:
         if not requirements:
             return None
 
-        # Check first requirement for path key (indicates local install)
         first_req = requirements[0]
-        if isinstance(first_req, dict) and "path" in first_req:
-            return "local"
+        if isinstance(first_req, dict):
+            if "git" in first_req and "github.com" in first_req["git"]:
+                return ToolSource.GITHUB
 
-        return "pypi"
+        return ToolSource.PYPI
 
     except (OSError, tomllib.TOMLDecodeError, KeyError, IndexError):
         return None
@@ -100,28 +124,39 @@ def is_command_available(command: str) -> bool:
 
 def install_tool(
     package_name: str = "ai-agent-rules",
+    from_github: bool = False,
+    github_url: str | None = None,
     force: bool = False,
     dry_run: bool = False,
 ) -> tuple[bool, str]:
-    """Install package as a uv tool from PyPI.
+    """Install package as a uv tool.
 
     Args:
-        package_name: Name of package to install
+        package_name: Name of package to install (ignored if from_github=True)
+        from_github: Install from GitHub instead of PyPI
+        github_url: GitHub URL to install from (only used if from_github=True)
         force: Force reinstall if already installed
         dry_run: Show what would be done without executing
 
     Returns:
         Tuple of (success, message)
     """
-    if not _validate_package_name(package_name):
+    if not from_github and not _validate_package_name(package_name):
         return False, f"Invalid package name: {package_name}"
 
     if not is_command_available("uv"):
         return False, UV_NOT_FOUND_ERROR
 
-    cmd = ["uv", "tool", "install", package_name]
+    if from_github:
+        source = github_url if github_url else make_github_install_url(GITHUB_REPO)
+    else:
+        source = package_name
+    cmd = ["uv", "tool", "install", source]
+
     if force:
         cmd.insert(3, "--force")
+        if from_github:
+            cmd.insert(4, "--reinstall")
 
     if dry_run:
         return True, f"Would run: {' '.join(cmd)}"
@@ -227,23 +262,60 @@ def get_tool_version(tool_name: str) -> str | None:
         return None
 
 
-def ensure_statusline_installed(dry_run: bool = False) -> str:
-    """Install claude-code-statusline if not already present. Fails open.
+def ensure_statusline_installed(
+    dry_run: bool = False, from_github: bool = False
+) -> tuple[str, str | None]:
+    """Install or upgrade claude-code-statusline if needed. Fails open.
 
     Args:
-        dry_run: If True, skip installation
+        dry_run: If True, show what would be done without executing
+        from_github: Install from GitHub instead of PyPI
 
     Returns:
-        Status: "already_installed", "installed", "failed", or "skipped"
+        Tuple of (status, message) where status is:
+        "already_installed", "installed", "upgraded", "upgrade_available", "failed", or "skipped"
+        Message is only provided in dry_run mode or when upgraded
     """
     if is_command_available("claude-statusline"):
-        return "already_installed"
-
-    if dry_run:
-        return "skipped"
+        try:
+            from ai_rules.bootstrap.updater import (
+                check_tool_updates,
+                get_tool_by_id,
+                perform_tool_upgrade,
+            )
+
+            statusline_tool = get_tool_by_id("statusline")
+            if statusline_tool:
+                update_info = check_tool_updates(statusline_tool, timeout=10)
+                if update_info and update_info.has_update:
+                    if dry_run:
+                        return (
+                            "upgrade_available",
+                            f"Would upgrade statusline {update_info.current_version} → {update_info.latest_version}",
+                        )
+                    success, msg, _ = perform_tool_upgrade(statusline_tool)
+                    if success:
+                        return (
+                            "upgraded",
+                            f"{update_info.current_version} → {update_info.latest_version}",
+                        )
+        except Exception:
+            pass
+        return "already_installed", None
 
     try:
-        success, _ = install_tool("claude-code-statusline", force=False, dry_run=False)
-        return "installed" if success else "failed"
+        success, message = install_tool(
+            "claude-code-statusline",
+            from_github=from_github,
+            github_url=make_github_install_url(STATUSLINE_GITHUB_REPO)
+            if from_github
+            else None,
+            force=False,
+            dry_run=dry_run,
+        )
+        if success:
+            return "installed", message if dry_run else None
+        else:
+            return "failed", None
     except Exception:
-        return "failed"
+        return "failed", None