agentpack-cli 0.3.0__tar.gz → 0.3.1__tar.gz

{agentpack_cli-0.3.0 → agentpack_cli-0.3.1}/.gitignore

@@ -12,6 +12,8 @@ env/
 
 # agentpack:start
 # AgentPack generated context/cache (safe to ignore)
+.agentpack/*
+!.agentpack/config.toml
 .agentpack/cache/
 .agentpack/snapshots/
 .agentpack/context*
@@ -23,9 +25,11 @@ env/
 .agentpack/session.json
 .agentpack/task.md
 .agentpack/benchmark_results.jsonl
+.agentignore
 .agent/skills/agentpack/
+.vscode/tasks.json
+GEMINI.md
 # agentpack:end
-
 .pytest_cache/
 .mypy_cache/
 .ruff_cache/

{agentpack_cli-0.3.0 → agentpack_cli-0.3.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agentpack-cli
-Version: 0.3.0
+Version: 0.3.1
 Summary: Task-aware context packing for AI coding agents — Claude, Cursor, Windsurf, Codex, and Antigravity
 License: MIT
 License-File: LICENSE
@@ -44,7 +44,7 @@ Description-Content-Type: text/markdown
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![CI](https://github.com/vishal2612200/agentpack/actions/workflows/ci.yml/badge.svg)](https://github.com/vishal2612200/agentpack/actions/workflows/ci.yml)
 
-> **Status: alpha (v0.3.0).** Works, tested, used in real sessions. Python and JavaScript/TypeScript are the best-supported languages. Public benchmark proof exists for the current suite, but broader repo coverage is still growing. API may change before 1.0.
+> **Status: alpha (v0.3.1).** Works, tested, used in real sessions. Python and JavaScript/TypeScript are the best-supported languages. Public benchmark proof exists for the current suite, but broader repo coverage is still growing. API may change before 1.0.
 >
 > **Platform note:** macOS and Linux are fully supported. Windows support is not yet implemented (git hooks use POSIX shell; the Claude Code session hooks use `python3`/`rm -f`). Contributions welcome.
 
@@ -80,11 +80,30 @@ AgentPack is useful when a repo is too large to paste, but a blank agent session
 ## Install
 
 ```bash
-pip install agentpack-cli
+pipx install agentpack-cli
 agentpack --version
 ```
 
-Requires Python 3.10+. The PyPI package is `agentpack-cli`; the command is `agentpack`.
+Requires Python 3.10+. The PyPI package is `agentpack-cli`; the command is `agentpack`. Use `pipx` for normal installs because many macOS/Linux Python distributions block global `pip install` with PEP 668's `externally-managed-environment` error. If you prefer `pip`, install inside a virtual environment.
+
+Install `pipx` with your OS package manager first if needed:
+
+```bash
+# macOS
+brew install pipx
+
+# Ubuntu/Debian
+sudo apt install pipx
+
+# Fedora
+sudo dnf install pipx
+
+# Arch
+sudo pacman -S python-pipx
+
+# Then ensure pipx apps are on PATH
+pipx ensurepath
+```
 
 JavaScript-heavy teams can install the npm wrapper:
 
@@ -454,7 +473,7 @@ jobs:
         with:
           python-version: "3.12"
 
-      - run: pip install agentpack-cli
+      - run: python -m pip install agentpack-cli
 
       - name: Generate context pack
         run: |
@@ -767,7 +786,7 @@ Uses `watchdog` if installed, falls back to polling. Context is refreshed whenev
 
 Install watchdog for better performance:
 ```bash
-pip install "agentpack-cli[watch]"
+pipx inject agentpack-cli watchdog
 ```
 
 ---
@@ -789,7 +808,7 @@ Requires an initialized project (`agentpack init`). Refreshes context, prints th
 Run AgentPack as an MCP server — exposes context packing as tools that Claude Code (and any MCP-compatible agent) can call directly.
 
 ```bash
-pip install "agentpack-cli[mcp]"
+pipx inject agentpack-cli "agentpack-cli[mcp]"
 agentpack mcp
 ```
 
@@ -1464,9 +1483,9 @@ Post-0.3 release focus: broader real-repo proof, npm publish reliability, and co
 ## Optional dependencies
 
 ```bash
-pip install "agentpack-cli[watch]"    # watchdog — faster file watching for agentpack watch
-pip install "agentpack-cli[mcp]"      # mcp — expose agentpack as MCP server tools
-pip install "agentpack-cli[all]"      # watch + mcp
+pipx inject agentpack-cli watchdog              # faster file watching for agentpack watch
+pipx inject agentpack-cli "agentpack-cli[mcp]"  # expose agentpack as MCP server tools
+pipx inject agentpack-cli "agentpack-cli[all]"  # watch + mcp
 ```
 
 ---

{agentpack_cli-0.3.0 → agentpack_cli-0.3.1}/README.md

@@ -5,7 +5,7 @@
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![CI](https://github.com/vishal2612200/agentpack/actions/workflows/ci.yml/badge.svg)](https://github.com/vishal2612200/agentpack/actions/workflows/ci.yml)
 
-> **Status: alpha (v0.3.0).** Works, tested, used in real sessions. Python and JavaScript/TypeScript are the best-supported languages. Public benchmark proof exists for the current suite, but broader repo coverage is still growing. API may change before 1.0.
+> **Status: alpha (v0.3.1).** Works, tested, used in real sessions. Python and JavaScript/TypeScript are the best-supported languages. Public benchmark proof exists for the current suite, but broader repo coverage is still growing. API may change before 1.0.
 >
 > **Platform note:** macOS and Linux are fully supported. Windows support is not yet implemented (git hooks use POSIX shell; the Claude Code session hooks use `python3`/`rm -f`). Contributions welcome.
 
@@ -41,11 +41,30 @@ AgentPack is useful when a repo is too large to paste, but a blank agent session
 ## Install
 
 ```bash
-pip install agentpack-cli
+pipx install agentpack-cli
 agentpack --version
 ```
 
-Requires Python 3.10+. The PyPI package is `agentpack-cli`; the command is `agentpack`.
+Requires Python 3.10+. The PyPI package is `agentpack-cli`; the command is `agentpack`. Use `pipx` for normal installs because many macOS/Linux Python distributions block global `pip install` with PEP 668's `externally-managed-environment` error. If you prefer `pip`, install inside a virtual environment.
+
+Install `pipx` with your OS package manager first if needed:
+
+```bash
+# macOS
+brew install pipx
+
+# Ubuntu/Debian
+sudo apt install pipx
+
+# Fedora
+sudo dnf install pipx
+
+# Arch
+sudo pacman -S python-pipx
+
+# Then ensure pipx apps are on PATH
+pipx ensurepath
+```
 
 JavaScript-heavy teams can install the npm wrapper:
 
@@ -415,7 +434,7 @@ jobs:
         with:
           python-version: "3.12"
 
-      - run: pip install agentpack-cli
+      - run: python -m pip install agentpack-cli
 
       - name: Generate context pack
         run: |
@@ -728,7 +747,7 @@ Uses `watchdog` if installed, falls back to polling. Context is refreshed whenev
 
 Install watchdog for better performance:
 ```bash
-pip install "agentpack-cli[watch]"
+pipx inject agentpack-cli watchdog
 ```
 
 ---
@@ -750,7 +769,7 @@ Requires an initialized project (`agentpack init`). Refreshes context, prints th
 Run AgentPack as an MCP server — exposes context packing as tools that Claude Code (and any MCP-compatible agent) can call directly.
 
 ```bash
-pip install "agentpack-cli[mcp]"
+pipx inject agentpack-cli "agentpack-cli[mcp]"
 agentpack mcp
 ```
 
@@ -1425,9 +1444,9 @@ Post-0.3 release focus: broader real-repo proof, npm publish reliability, and co
 ## Optional dependencies
 
 ```bash
-pip install "agentpack-cli[watch]"    # watchdog — faster file watching for agentpack watch
-pip install "agentpack-cli[mcp]"      # mcp — expose agentpack as MCP server tools
-pip install "agentpack-cli[all]"      # watch + mcp
+pipx inject agentpack-cli watchdog              # faster file watching for agentpack watch
+pipx inject agentpack-cli "agentpack-cli[mcp]"  # expose agentpack as MCP server tools
+pipx inject agentpack-cli "agentpack-cli[all]"  # watch + mcp
 ```
 
 ---

{agentpack_cli-0.3.0 → agentpack_cli-0.3.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "agentpack-cli"
-version = "0.3.0"
+version = "0.3.1"
 description = "Task-aware context packing for AI coding agents — Claude, Cursor, Windsurf, Codex, and Antigravity"
 readme = "README.md"
 requires-python = ">=3.10"

{agentpack_cli-0.3.0 → agentpack_cli-0.3.1}/src/agentpack/__init__.py

@@ -1,3 +1,3 @@
 """AgentPack — task-aware context packing for AI coding agents."""
 
-__version__ = "0.3.0"
+__version__ = "0.3.1"

agentpack_cli-0.3.1/src/agentpack/commands/init.py

@@ -0,0 +1,408 @@
+from __future__ import annotations
+
+import sys
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Optional
+
+import typer
+
+from agentpack.core.config import DEFAULT_CONFIG, CONFIG_TEMPLATE
+from agentpack.core.ignore import DEFAULT_AGENTIGNORE
+from agentpack.commands._shared import console, _root
+from agentpack.integrations.agents import check_agent_integration, install_agent_integration
+from agentpack.session.state import load_session, create_session, SESSION_FILE, TASK_FILE
+
+_GITIGNORE_START = "# agentpack:start"
+_GITIGNORE_END = "# agentpack:end"
+_INIT_MODES = ("minimal", "balanced", "deep")
+_INIT_AGENTS = ("auto", "claude", "cursor", "windsurf", "codex", "antigravity", "generic")
+_AGENT_GITIGNORE_ENTRIES = {
+    "cursor": (".vscode/tasks.json",),
+    "windsurf": (".vscode/tasks.json",),
+    "antigravity": (".agent/skills/agentpack/", ".vscode/tasks.json", "GEMINI.md"),
+}
+
+
+@dataclass
+class InitResult:
+    path: str
+    action: str
+
+
+@dataclass
+class InitHealth:
+    label: str
+    ok: bool
+    detail: str
+
+
+def _repo_gitignore_entries(share_cache: bool = False, agent: str = "generic") -> list[str]:
+    entries = [
+        ".agentpack/*",
+        "!.agentpack/config.toml",
+    ]
+    if share_cache:
+        entries.extend(["!.agentpack/cache/", "!.agentpack/cache/**"])
+    else:
+        entries.append(".agentpack/cache/")
+    entries.extend(
+        [
+            ".agentpack/snapshots/",
+            ".agentpack/context*",
+            ".agentpack/metrics.jsonl",
+            ".agentpack/pack_metadata.json",
+            ".agentpack/activity.log",
+            ".agentpack/.gitignore",
+            ".agentpack/.mcp_reminded",
+            ".agentpack/session.json",
+            ".agentpack/task.md",
+            ".agentpack/benchmark_results.jsonl",
+            ".agentignore",
+        ]
+    )
+    entries.extend(_AGENT_GITIGNORE_ENTRIES.get(agent, ()))
+    return entries
+
+
+def _repo_gitignore_block(share_cache: bool = False, agent: str = "generic") -> str:
+    return (
+        f"{_GITIGNORE_START}\n"
+        "# AgentPack generated context/cache (safe to ignore)\n"
+        + "\n".join(_repo_gitignore_entries(share_cache, agent))
+        + "\n"
+        f"{_GITIGNORE_END}\n"
+    )
+
+
+def _agentpack_gitignore_content(share_cache: bool = False) -> str:
+    entries = []
+    if not share_cache:
+        entries.append("cache/")
+    entries.extend(
+        [
+            "snapshots/",
+            "context.*",
+            "metrics.jsonl",
+            "pack_metadata.json",
+            "activity.log",
+            ".mcp_reminded",
+            "session.json",
+            "task.md",
+            "benchmark_results.jsonl",
+        ]
+    )
+    return "\n".join(entries) + "\n"
+
+
+def _backup_file(path: Path) -> Path:
+    backup = path.with_name(f"{path.name}.bak")
+    index = 1
+    while backup.exists():
+        backup = path.with_name(f"{path.name}.bak.{index}")
+        index += 1
+    backup.write_text(path.read_text(encoding="utf-8"), encoding="utf-8")
+    return backup
+
+
+def _write_text(root: Path, path: Path, content: str, *, force: bool = False, backups: list[InitResult] | None = None) -> str:
+    existed = path.exists()
+    if existed and path.read_text(encoding="utf-8") == content:
+        return "unchanged"
+    if force and existed and backups is not None:
+        backup = _backup_file(path)
+        backups.append(InitResult(str(backup.relative_to(root)), "created"))
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(content, encoding="utf-8")
+    return "updated" if existed else "created"
+
+
+def _patch_repo_gitignore(root: Path, share_cache: bool = False, agent: str = "generic", *, force: bool = False, backups: list[InitResult] | None = None) -> str:
+    gitignore = root / ".gitignore"
+    block = _repo_gitignore_block(share_cache, agent)
+    if not gitignore.exists():
+        gitignore.write_text(block, encoding="utf-8")
+        return "created"
+
+    content = gitignore.read_text(encoding="utf-8")
+    start = content.find(_GITIGNORE_START)
+    end = content.find(_GITIGNORE_END)
+    if start != -1 and end != -1 and end >= start:
+        end += len(_GITIGNORE_END)
+        replacement = block.rstrip()
+        updated = content[:start].rstrip() + "\n\n" + replacement + "\n" + content[end:].lstrip("\n")
+        if updated == content:
+            return "unchanged"
+        if force and backups is not None:
+            backup = _backup_file(gitignore)
+            backups.append(InitResult(str(backup.relative_to(root)), "created"))
+        gitignore.write_text(updated, encoding="utf-8")
+        return "updated"
+
+    prefix = content.rstrip() + "\n\n" if content.strip() else ""
+    if force and backups is not None:
+        backup = _backup_file(gitignore)
+        backups.append(InitResult(str(backup.relative_to(root)), "created"))
+    gitignore.write_text(prefix + block, encoding="utf-8")
+    return "updated"
+
+
+def _install_agent_integration(root, agent: str) -> dict[str, str]:
+    """Install repo-local agent integration files after `agentpack init`."""
+    return install_agent_integration(root, agent)
+
+
+def _print_agent_integration_results(results: dict[str, str]) -> None:
+    for key, action in results.items():
+        if action == "unchanged":
+            continue
+        if key.startswith("git:"):
+            console.print(f"[green].git/hooks/{key[4:]} {action}[/]")
+        elif key == "vscode:tasks":
+            console.print(f"[green].vscode/tasks.json {action}[/]")
+        else:
+            console.print(f"[green]{key} {action}[/]")
+
+
+def _validate_init_options(agent: str, mode: str | None, budget: int) -> None:
+    if agent not in _INIT_AGENTS:
+        console.print(f"[yellow]Unknown agent: {agent}. Supported: {', '.join(_INIT_AGENTS)}[/]")
+        raise typer.Exit(1)
+    if mode is not None and mode not in _INIT_MODES:
+        console.print(f"[yellow]Unknown mode: {mode}. Supported: {', '.join(_INIT_MODES)}[/]")
+        raise typer.Exit(1)
+    if budget < 0:
+        console.print("[yellow]Budget must be 0 or greater.[/]")
+        raise typer.Exit(1)
+
+
+def _resolve_init_agent(root: Path, agent: str, *, force: bool = False) -> str:
+    if agent != "auto":
+        return agent
+    existing_session = load_session(root)
+    if existing_session is not None and not force:
+        return existing_session.agent
+    from agentpack.adapters.detect import detect_agent
+
+    return detect_agent(root)
+
+
+def _agent_integration_paths(agent: str) -> tuple[str, ...]:
+    if agent == "claude":
+        return ("CLAUDE.md", ".claude/settings.json", ".mcp.json")
+    if agent == "cursor":
+        return (".cursorrules", ".cursor/rules/agentpack.mdc", ".vscode/tasks.json")
+    if agent == "windsurf":
+        return (".windsurfrules", ".vscode/tasks.json")
+    if agent == "codex":
+        return ("AGENTS.md", ".codex/hooks.json")
+    if agent == "antigravity":
+        return ("GEMINI.md", ".vscode/tasks.json")
+    return ()
+
+
+def _backup_existing_paths(root: Path, paths: tuple[str, ...], backups: list[InitResult]) -> None:
+    for rel in paths:
+        path = root / rel
+        if path.exists() and path.is_file():
+            backup = _backup_file(path)
+            backups.append(InitResult(str(backup.relative_to(root)), "created"))
+
+
+def _planned_action(path: Path, expected: str | None = None) -> str:
+    if not path.exists():
+        return "create"
+    if expected is None:
+        return "update"
+    try:
+        return "unchanged" if path.read_text(encoding="utf-8") == expected else "update"
+    except OSError:
+        return "update"
+
+
+def _print_dry_run(root: Path, agent: str, share_cache: bool, mode: str | None, budget: int) -> None:
+    console.print("[bold yellow]Dry run — no files will be changed.[/]\n")
+    items = [
+        InitResult(".agentpack/", "ensure"),
+        InitResult(".agentpack/snapshots/", "ensure"),
+        InitResult(".agentpack/cache/", "ensure"),
+        InitResult(".agentpack/.gitignore", _planned_action(root / ".agentpack" / ".gitignore")),
+        InitResult(".gitignore", _planned_action(root / ".gitignore")),
+        InitResult(".agentpack/config.toml", _planned_action(root / ".agentpack" / "config.toml")),
+        InitResult(".agentignore", _planned_action(root / ".agentignore", DEFAULT_AGENTIGNORE)),
+        InitResult(SESSION_FILE, _planned_action(root / SESSION_FILE)),
+        InitResult(TASK_FILE, _planned_action(root / TASK_FILE)),
+    ]
+    for rel in _agent_integration_paths(agent):
+        items.append(InitResult(rel, _planned_action(root / rel)))
+    _print_init_summary("Dry Run", items)
+    console.print(f"  Agent: {agent}")
+    console.print(f"  Mode: {mode or DEFAULT_CONFIG.context.default_mode}")
+    console.print(f"  Budget: {budget or DEFAULT_CONFIG.context.default_budget:,}")
+    console.print(f"  Share cache: {'yes' if share_cache else 'no'}")
+
+
+def _print_init_summary(title: str, results: list[InitResult]) -> None:
+    console.print(f"\n[bold]{title}[/]")
+    grouped: dict[str, list[str]] = {}
+    for result in results:
+        grouped.setdefault(result.action, []).append(result.path)
+    for action in ("created", "updated", "unchanged", "skipped", "ensure", "create", "update"):
+        paths = grouped.get(action)
+        if not paths:
+            continue
+        console.print(f"  {action}: {', '.join(paths)}")
+
+
+def _init_health(root: Path, agent: str) -> list[InitHealth]:
+    checks = [
+        InitHealth(".gitignore", (root / ".gitignore").exists(), "repo ignore file present"),
+        InitHealth(".agentpack/config.toml", (root / ".agentpack" / "config.toml").exists(), "config file present"),
+        InitHealth(".agentignore", (root / ".agentignore").exists(), "agent ignore file present"),
+        InitHealth(SESSION_FILE, (root / SESSION_FILE).exists(), "session file present"),
+        InitHealth(TASK_FILE, (root / TASK_FILE).exists(), "task file present"),
+    ]
+    try:
+        from agentpack.core.config import load_config
+
+        load_config(root)
+        checks.append(InitHealth("config", True, "loads successfully"))
+    except Exception as exc:
+        checks.append(InitHealth("config", False, f"failed to load: {exc}"))
+    for check in check_agent_integration(root, agent):
+        checks.append(InitHealth(check.label, check.ok, check.detail))
+    return checks
+
+
+def _print_health(root: Path, agent: str) -> None:
+    console.print("\n[bold]Init health[/]")
+    for check in _init_health(root, agent):
+        marker = "[green]✓[/]" if check.ok else "[yellow]![/]"
+        console.print(f"  {marker} {check.label}: {check.detail}")
+
+
+def register(app: typer.Typer) -> None:
+    @app.command()
+    def init(
+        force: bool = typer.Option(False, "--force", help="Overwrite existing files."),
+        mode: Optional[str] = typer.Option(None, "--mode", help="Default pack mode (minimal|balanced|deep)."),
+        budget: int = typer.Option(0, "--budget", help="Default token budget (0 = keep default 25000)."),
+        yes: bool = typer.Option(False, "--yes", "-y", help="Skip interactive prompts, use defaults."),
+        silent: bool = typer.Option(False, "--silent", help="Suppress all output (for use in hooks/scripts)."),
+        share_cache: bool = typer.Option(False, "--share-cache", help="Commit summary cache to git (recommended for teams)."),
+        agent: str = typer.Option("auto", "--agent", help="Target agent (auto|claude|cursor|windsurf|codex|antigravity|generic)."),
+        dry_run: bool = typer.Option(False, "--dry-run", help="Show what would change without writing files."),
+        health_check: bool = typer.Option(True, "--health-check/--no-health-check", help="Verify init outputs after setup."),
+    ) -> None:
+        """Initialize AgentPack in the current directory.
+
+        One-time setup. After this, just run `agentpack watch` — no other commands needed.
+        """
+        if silent:
+            yes = True
+            console.quiet = True
+        _validate_init_options(agent, mode, budget)
+        root = _root()
+        resolved_agent = _resolve_init_agent(root, agent, force=force)
+        if dry_run:
+            _print_dry_run(root, resolved_agent, share_cache, mode, budget)
+            return
+
+        results: list[InitResult] = []
+        backups: list[InitResult] = []
+        agentpack_dir = root / ".agentpack"
+        agentpack_existed = agentpack_dir.exists()
+        snapshots_existed = (agentpack_dir / "snapshots").exists()
+        cache_existed = (agentpack_dir / "cache").exists()
+        agentpack_dir.mkdir(exist_ok=True)
+        (agentpack_dir / "snapshots").mkdir(exist_ok=True)
+        (agentpack_dir / "cache").mkdir(exist_ok=True)
+        results.extend(
+            [
+                InitResult(".agentpack/", "unchanged" if agentpack_existed else "created"),
+                InitResult(".agentpack/snapshots/", "unchanged" if snapshots_existed else "created"),
+                InitResult(".agentpack/cache/", "unchanged" if cache_existed else "created"),
+            ]
+        )
+
+        gitignore = agentpack_dir / ".gitignore"
+        if not gitignore.exists() or force:
+            action = _write_text(root, gitignore, _agentpack_gitignore_content(share_cache), force=force, backups=backups)
+            results.append(InitResult(".agentpack/.gitignore", action))
+        else:
+            results.append(InitResult(".agentpack/.gitignore", "unchanged"))
+
+        gitignore_action = _patch_repo_gitignore(root, share_cache=share_cache, agent=resolved_agent, force=force, backups=backups)
+        results.append(InitResult(".gitignore", gitignore_action))
+
+        config_path_file = agentpack_dir / "config.toml"
+        if not config_path_file.exists() or force:
+            cfg = DEFAULT_CONFIG.model_copy(deep=True)
+
+            # Interactive mode selection
+            if not yes and mode is None and sys.stdin.isatty():
+                console.print("\n[bold]Choose default pack mode:[/]")
+                console.print("  [cyan]1[/] minimal  — changed files + configs only (fastest, fewest tokens)")
+                console.print("  [cyan]2[/] balanced — + deps, tests, summaries [bold](recommended)[/]")
+                console.print("  [cyan]3[/] deep     — + docs, more full files (most context)")
+                choice = typer.prompt("Mode", default="2")
+                mode_map = {"1": "minimal", "2": "balanced", "3": "deep",
+                            "minimal": "minimal", "balanced": "balanced", "deep": "deep"}
+                cfg.context.default_mode = mode_map.get(choice.strip(), "balanced")
+            elif mode in ("minimal", "balanced", "deep"):
+                cfg.context.default_mode = mode
+
+            if budget > 0:
+                cfg.context.default_budget = budget
+
+            config_toml = CONFIG_TEMPLATE.replace(
+                'default_mode = "balanced"',
+                f'default_mode = "{cfg.context.default_mode}"',
+            )
+            if budget > 0:
+                config_toml = config_toml.replace(
+                    "default_budget = 25000",
+                    f"default_budget = {cfg.context.default_budget}",
+                )
+            action = _write_text(root, config_path_file, config_toml, force=force, backups=backups)
+            results.append(InitResult(".agentpack/config.toml", action))
+        else:
+            results.append(InitResult(".agentpack/config.toml", "unchanged"))
+
+        ignore_path = root / ".agentignore"
+        if not ignore_path.exists() or force:
+            action = _write_text(root, ignore_path, DEFAULT_AGENTIGNORE, force=force, backups=backups)
+            results.append(InitResult(".agentignore", action))
+        else:
+            results.append(InitResult(".agentignore", "unchanged"))
+
+        # Bootstrap session so `agentpack watch` works immediately — no separate `session start` needed
+        from agentpack.core.config import load_config
+        resolved_mode = load_config(root).context.default_mode
+        existing_session = load_session(root)
+        if existing_session is None or force:
+            create_session(root, agent=resolved_agent, mode=resolved_mode)
+            results.append(InitResult(SESSION_FILE, "created" if existing_session is None else "updated"))
+            results.append(InitResult(TASK_FILE, "created" if existing_session is None else "updated"))
+        else:
+            results.append(InitResult(SESSION_FILE, "unchanged"))
+            results.append(InitResult(TASK_FILE, "unchanged"))
+
+        if force:
+            _backup_existing_paths(root, _agent_integration_paths(resolved_agent), backups)
+        integration_results = _install_agent_integration(root, resolved_agent)
+        for key, action in integration_results.items():
+            if key.startswith("git:"):
+                results.append(InitResult(f".git/hooks/{key[4:]}", action))
+            elif key == "vscode:tasks":
+                results.append(InitResult(".vscode/tasks.json", action))
+            else:
+                results.append(InitResult(key, action))
+
+        if backups:
+            _print_init_summary("Backups", backups)
+        _print_init_summary("Init Summary", results)
+        if health_check:
+            _print_health(root, resolved_agent)
+        console.print(f"\n[bold green]AgentPack initialized.[/] [dim]agent={resolved_agent} mode={resolved_mode}[/]")
+        console.print("Run [bold]agentpack watch[/] to start auto-refreshing context.")

{agentpack_cli-0.3.0 → agentpack_cli-0.3.1}/src/agentpack/commands/install.py

@@ -1,6 +1,5 @@
 from __future__ import annotations
 
-import sys
 from pathlib import Path
 
 import typer
@@ -129,16 +128,12 @@ def register(app: typer.Typer) -> None:
             if result.returncode == 0:
                 console.print("[green]agentpack installed globally.[/] Available as `agentpack` in any shell.")
             else:
-                console.print("[yellow]pipx install failed. Trying pip install --user...[/]")
-                result2 = sp.run(
-                    [sys.executable, "-m", "pip", "install", "--user", "agentpack-cli"],
-                    capture_output=True,
-                    text=True,
-                )
-                if result2.returncode != 0:
-                    console.print(f"[red]Install failed:[/] {result2.stderr[:200]}")
-                    raise typer.Exit(1)
-                console.print("[green]Installed via pip --user.[/]")
+                console.print("[red]pipx install failed.[/]")
+                console.print(result.stderr[:300])
+                console.print("Install pipx with your OS package manager, then retry: [bold]pipx ensurepath && pipx install agentpack-cli[/]")
+                console.print("Examples: [bold]brew install pipx[/], [bold]sudo apt install pipx[/], [bold]sudo dnf install pipx[/], [bold]sudo pacman -S python-pipx[/].")
+                console.print("Avoid global [bold]pip3 install[/] on system-managed Python; PEP 668 may block it.")
+                raise typer.Exit(1)
         elif pipx and dry_run:
             console.print("[dim]Would run: pipx install agentpack-cli[/]")
 

{agentpack_cli-0.3.0 → agentpack_cli-0.3.1}/src/agentpack/commands/pack.py

@@ -259,7 +259,7 @@ def _pack_watch(
         from watchdog.events import FileSystemEventHandler
     except ImportError:
         console.print("[red]watchdog is required for --watch mode.[/]")
-        console.print("Install it: [bold]pip install watchdog[/]")
+        console.print("Install it: [bold]pipx inject agentpack-cli watchdog[/]")
         raise typer.Exit(1)
 
     root = _root()

{agentpack_cli-0.3.0 → agentpack_cli-0.3.1}/src/agentpack/data/agentpack.md

@@ -82,7 +82,7 @@ Then read `.agentpack/context.claude.md` in full.
 ### Step 1: Check agentpack is installed
 
 ```bash
-agentpack --help 2>/dev/null || pip install agentpack-cli
+agentpack --help 2>/dev/null || pipx install agentpack-cli
 ```
 
 ### Step 2: Initialize if not already done

{agentpack_cli-0.3.0 → agentpack_cli-0.3.1}/src/agentpack/mcp_server.py

@@ -419,7 +419,7 @@ def serve() -> None:
     except ImportError:
         print(
             "mcp package required for MCP server. "
-            "Install: pip install 'agentpack-cli[mcp]'",
+            "Install: pipx inject agentpack-cli 'agentpack-cli[mcp]'",
             file=sys.stderr,
         )
         sys.exit(1)

agentpack_cli-0.3.0/src/agentpack/commands/init.py

@@ -1,186 +0,0 @@
-from __future__ import annotations
-
-import sys
-from typing import Optional
-
-import typer
-
-from agentpack.core.config import DEFAULT_CONFIG, CONFIG_TEMPLATE
-from agentpack.core.ignore import DEFAULT_AGENTIGNORE
-from agentpack.commands._shared import console, _root
-from agentpack.integrations.agents import install_agent_integration
-from agentpack.session.state import load_session, create_session, SESSION_FILE, TASK_FILE
-
-_GITIGNORE_START = "# agentpack:start"
-_GITIGNORE_END = "# agentpack:end"
-
-
-def _repo_gitignore_block(share_cache: bool = False) -> str:
-    cache_line = "" if share_cache else ".agentpack/cache/\n"
-    return (
-        f"{_GITIGNORE_START}\n"
-        "# AgentPack generated context/cache (safe to ignore)\n"
-        f"{cache_line}"
-        ".agentpack/snapshots/\n"
-        ".agentpack/context*\n"
-        ".agentpack/metrics.jsonl\n"
-        ".agentpack/pack_metadata.json\n"
-        ".agentpack/activity.log\n"
-        ".agentpack/.gitignore\n"
-        ".agentpack/.mcp_reminded\n"
-        ".agentpack/session.json\n"
-        ".agentpack/task.md\n"
-        ".agentpack/benchmark_results.jsonl\n"
-        ".agent/skills/agentpack/\n"
-        f"{_GITIGNORE_END}\n"
-    )
-
-
-def _patch_repo_gitignore(root, share_cache: bool = False) -> str:
-    gitignore = root / ".gitignore"
-    block = _repo_gitignore_block(share_cache)
-    if not gitignore.exists():
-        gitignore.write_text(block, encoding="utf-8")
-        return "created"
-
-    content = gitignore.read_text(encoding="utf-8")
-    start = content.find(_GITIGNORE_START)
-    end = content.find(_GITIGNORE_END)
-    if start != -1 and end != -1 and end >= start:
-        end += len(_GITIGNORE_END)
-        replacement = block.rstrip()
-        updated = content[:start].rstrip() + "\n\n" + replacement + "\n" + content[end:].lstrip("\n")
-        if updated == content:
-            return "unchanged"
-        gitignore.write_text(updated, encoding="utf-8")
-        return "updated"
-
-    prefix = content.rstrip() + "\n\n" if content.strip() else ""
-    gitignore.write_text(prefix + block, encoding="utf-8")
-    return "updated"
-
-
-def _install_agent_integration(root, agent: str) -> dict[str, str]:
-    """Install repo-local agent integration files after `agentpack init`."""
-    return install_agent_integration(root, agent)
-
-
-def _print_agent_integration_results(results: dict[str, str]) -> None:
-    for key, action in results.items():
-        if action == "unchanged":
-            continue
-        if key.startswith("git:"):
-            console.print(f"[green].git/hooks/{key[4:]} {action}[/]")
-        elif key == "vscode:tasks":
-            console.print(f"[green].vscode/tasks.json {action}[/]")
-        else:
-            console.print(f"[green]{key} {action}[/]")
-
-
-def register(app: typer.Typer) -> None:
-    @app.command()
-    def init(
-        force: bool = typer.Option(False, "--force", help="Overwrite existing files."),
-        mode: Optional[str] = typer.Option(None, "--mode", help="Default pack mode (minimal|balanced|deep)."),
-        budget: int = typer.Option(0, "--budget", help="Default token budget (0 = keep default 25000)."),
-        yes: bool = typer.Option(False, "--yes", "-y", help="Skip interactive prompts, use defaults."),
-        silent: bool = typer.Option(False, "--silent", help="Suppress all output (for use in hooks/scripts)."),
-        share_cache: bool = typer.Option(False, "--share-cache", help="Commit summary cache to git (recommended for teams)."),
-        agent: str = typer.Option("auto", "--agent", help="Target agent (auto|claude|cursor|windsurf|codex|antigravity|generic)."),
-    ) -> None:
-        """Initialize AgentPack in the current directory.
-
-        One-time setup. After this, just run `agentpack watch` — no other commands needed.
-        """
-        if silent:
-            yes = True
-            console.quiet = True
-        root = _root()
-        agentpack_dir = root / ".agentpack"
-        agentpack_dir.mkdir(exist_ok=True)
-        (agentpack_dir / "snapshots").mkdir(exist_ok=True)
-        (agentpack_dir / "cache").mkdir(exist_ok=True)
-
-        gitignore = agentpack_dir / ".gitignore"
-        if not gitignore.exists() or force:
-            # With --share-cache, cache/ is committed so teammates skip the summarize step
-            cache_line = "" if share_cache else ".agentpack/cache/\n"
-            gitignore.write_text(
-                f"{cache_line}.agentpack/snapshots/\n.agentpack/context.*\n.agentpack/metrics.jsonl\n"
-            )
-            console.print("[green]Created[/] .agentpack/.gitignore")
-            if share_cache:
-                console.print("  [dim]cache/ not gitignored — commit it so teammates skip agentpack summarize[/]")
-        else:
-            console.print("[dim]Skipped[/] .agentpack/.gitignore (exists)")
-
-        gitignore_action = _patch_repo_gitignore(root, share_cache=share_cache)
-        if gitignore_action == "created":
-            console.print("[green]Created[/] .gitignore [dim](AgentPack generated artifacts ignored)[/]")
-        elif gitignore_action == "updated":
-            console.print("[green]Updated[/] .gitignore [dim](AgentPack generated artifacts ignored)[/]")
-        else:
-            console.print("[dim]Skipped[/] .gitignore (AgentPack block unchanged)")
-
-        config_path_file = agentpack_dir / "config.toml"
-        if not config_path_file.exists() or force:
-            cfg = DEFAULT_CONFIG.model_copy(deep=True)
-
-            # Interactive mode selection
-            if not yes and mode is None and sys.stdin.isatty():
-                console.print("\n[bold]Choose default pack mode:[/]")
-                console.print("  [cyan]1[/] minimal  — changed files + configs only (fastest, fewest tokens)")
-                console.print("  [cyan]2[/] balanced — + deps, tests, summaries [bold](recommended)[/]")
-                console.print("  [cyan]3[/] deep     — + docs, more full files (most context)")
-                choice = typer.prompt("Mode", default="2")
-                mode_map = {"1": "minimal", "2": "balanced", "3": "deep",
-                            "minimal": "minimal", "balanced": "balanced", "deep": "deep"}
-                cfg.context.default_mode = mode_map.get(choice.strip(), "balanced")
-            elif mode in ("minimal", "balanced", "deep"):
-                cfg.context.default_mode = mode
-
-            if budget > 0:
-                cfg.context.default_budget = budget
-
-            config_toml = CONFIG_TEMPLATE.replace(
-                'default_mode = "balanced"',
-                f'default_mode = "{cfg.context.default_mode}"',
-            )
-            if budget > 0:
-                config_toml = config_toml.replace(
-                    "default_budget = 25000",
-                    f"default_budget = {cfg.context.default_budget}",
-                )
-            config_path_file.parent.mkdir(parents=True, exist_ok=True)
-            config_path_file.write_text(config_toml)
-            console.print(f"[green]Created[/] .agentpack/config.toml  [dim](mode: {cfg.context.default_mode}, budget: {cfg.context.default_budget:,})[/]")
-        else:
-            console.print("[dim]Skipped[/] .agentpack/config.toml (exists)")
-
-        ignore_path = root / ".agentignore"
-        if not ignore_path.exists() or force:
-            ignore_path.write_text(DEFAULT_AGENTIGNORE)
-            console.print("[green]Created[/] .agentignore")
-        else:
-            console.print("[dim]Skipped[/] .agentignore (exists)")
-
-        # Bootstrap session so `agentpack watch` works immediately — no separate `session start` needed
-        from agentpack.core.config import load_config
-        resolved_mode = load_config(root).context.default_mode
-        existing_session = load_session(root)
-        resolved_agent = agent
-        if existing_session is None or force:
-            from agentpack.adapters.detect import detect_agent
-            resolved_agent = agent if agent != "auto" else detect_agent(root)
-            create_session(root, agent=resolved_agent, mode=resolved_mode)
-            console.print(f"[green]Created[/] {SESSION_FILE}  [dim]agent={resolved_agent} mode={resolved_mode}[/]")
-            console.print(f"[green]Created[/] {TASK_FILE}  [dim]edit to set your task[/]")
-        else:
-            console.print(f"[dim]Skipped[/] {SESSION_FILE} (exists)")
-            if agent == "auto":
-                resolved_agent = existing_session.agent
-
-        _print_agent_integration_results(_install_agent_integration(root, resolved_agent))
-
-        console.print("\n[bold green]AgentPack initialized.[/]")
-        console.print("Run [bold]agentpack watch[/] to start auto-refreshing context.")