agentpack-cli 0.1.0__py3-none-any.whl

agentpack/installers/claude.py

@@ -0,0 +1,160 @@
+from __future__ import annotations
+
+import json
+import re
+from pathlib import Path
+
+_AGENTPACK_BLOCK = """\
+<!-- agentpack:start -->
+## AgentPack Context
+
+AgentPack keeps context fresh automatically. When a session is running:
+
+1. Check `.agentpack/session.json` — if `"active": true`, read `.agentpack/context.md`.
+2. When the user gives you a new coding task, write a one-line summary to `.agentpack/task.md`.
+3. Re-read `.agentpack/context.md` after watch mode refreshes it (a few seconds).
+4. Prefer files listed in context, but verify with actual code before editing.
+
+If no session is running, generate context manually:
+
+```bash
+agentpack pack --agent claude --task "<task>"
+```
+
+Then read `.agentpack/context.claude.md`.
+<!-- agentpack:end -->"""
+
+_BLOCK_RE = re.compile(
+    r"<!-- agentpack:start -->.*?<!-- agentpack:end -->",
+    re.DOTALL,
+)
+
+
+class ClaudeInstaller:
+    """Configures Claude-specific repo and global files."""
+
+    def patch_claude_md(self, root: Path) -> str:
+        """Insert/update AgentPack block in CLAUDE.md. Returns action taken."""
+        claude_md = root / "CLAUDE.md"
+
+        if not claude_md.exists():
+            claude_md.write_text(f"{_AGENTPACK_BLOCK}\n")
+            return "created"
+
+        content = claude_md.read_text()
+        if _BLOCK_RE.search(content):
+            new_content = _BLOCK_RE.sub(_AGENTPACK_BLOCK, content)
+            if new_content != content:
+                claude_md.write_text(new_content)
+                return "updated"
+            return "unchanged"
+
+        claude_md.write_text(content.rstrip() + "\n\n" + _AGENTPACK_BLOCK + "\n")
+        return "appended"
+
+    def patch_claude_settings(self, root: Path, global_install: bool = False) -> str:
+        """Merge agentpack hooks into .claude/settings.json. Returns action taken."""
+        if global_install:
+            settings_path = Path.home() / ".claude" / "settings.json"
+        else:
+            settings_path = root / ".claude" / "settings.json"
+
+        settings_path.parent.mkdir(parents=True, exist_ok=True)
+
+        existing: dict = {}
+        if settings_path.exists():
+            try:
+                existing = json.loads(settings_path.read_text())
+            except json.JSONDecodeError:
+                existing = {}
+
+        hooks = existing.setdefault("hooks", {})
+
+        # SessionStart: delete sentinel + kick off background repack so first prompt
+        # gets fresh context without blocking the session.
+        sentinel_cmd = (
+            "rm -f .agentpack/.context_injected"
+            " && agentpack pack --task auto --mode balanced >/dev/null 2>&1 &"
+        )
+        session_start = hooks.setdefault("SessionStart", [])
+        # Replace any stale agentpack session hooks (old cmd only deleted sentinel).
+        for entry in session_start:
+            entry["hooks"] = [
+                h for h in entry.get("hooks", [])
+                if not (".context_injected" in h.get("command", "") and "rm -f" in h.get("command", ""))
+            ]
+        session_start[:] = [e for e in session_start if e.get("hooks")]
+        already_has_session_hook = any(
+            any(h.get("command", "") == sentinel_cmd for h in entry.get("hooks", []))
+            for entry in session_start
+        )
+        if not already_has_session_hook:
+            session_start.append({"hooks": [{"type": "command", "command": sentinel_cmd}]})
+
+        # UserPromptSubmit: hash-gated injection.
+        # - Always runs `agentpack status` (cheap; uses cached file hashes).
+        # - Stale → background repack, no injection this turn.
+        # - Fresh + new pack hash → inject once, write hash to sentinel.
+        # - Fresh + same hash → skip (already injected this pack version).
+        inject_command = (
+            "python3 -c \"\n"
+            "import hashlib, json, pathlib, subprocess, sys\n"
+            "snap = pathlib.Path('.agentpack/snapshots/latest.json')\n"
+            "sentinel = pathlib.Path('.agentpack/.context_injected')\n"
+            "injected_hash = sentinel.read_text().strip() if sentinel.exists() else None\n"
+            "fresh_session = not sentinel.exists()\n"
+            # Fast path: compare snapshot hash directly — no subprocess needed.
+            # Only skip if snap exists AND matches injected hash (context already in window).
+            "current_hash = hashlib.md5(snap.read_bytes()).hexdigest() if snap.exists() else None\n"
+            "if current_hash and current_hash == injected_hash:\n"
+            "    sys.exit(0)\n"
+            # Snapshot changed or missing — need to check/rebuild the pack.
+            # fresh_session: sentinel was just cleared by SessionStart hook.
+            "ctx = pathlib.Path('.agentpack/context.claude.md')\n"
+            "status = subprocess.run(['agentpack', 'status'], capture_output=True, text=True)\n"
+            "if status.returncode != 0:\n"
+            "    if fresh_session and not ctx.exists():\n"
+            # No pack at all on fresh session — sync pack so first prompt has context.
+            "        subprocess.run(['agentpack', 'pack', '--task', 'auto', '--mode', 'balanced'],\n"
+            "                       capture_output=True)\n"
+            "        current_hash = hashlib.md5(snap.read_bytes()).hexdigest() if snap.exists() else None\n"
+            "    else:\n"
+            # Pack exists but stale — background repack; inject stale pack this turn.
+            "        subprocess.Popen(['agentpack', 'pack', '--task', 'auto', '--mode', 'balanced'],\n"
+            "                         stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL)\n"
+            "if not ctx.exists(): sys.exit(0)\n"
+            "content = ctx.read_text()\n"
+            "if len(content) > 60000: content = content[:60000] + '\\n... [truncated]'\n"
+            "sentinel.write_text(current_hash or '1')\n"
+            "print(json.dumps({'hookSpecificOutput': {'hookEventName': 'UserPromptSubmit',\n"
+            "    'additionalContext': '[agentpack: context injected]\\n\\n' + content}}))\n"
+            "\""
+        )
+        user_prompt = hooks.setdefault("UserPromptSubmit", [])
+        # Replace any stale agentpack inject hooks (identified by signature strings).
+        for entry in user_prompt:
+            entry["hooks"] = [
+                h for h in entry.get("hooks", [])
+                if "context.claude.md" not in h.get("command", "")
+                and ".context_injected" not in h.get("command", "")
+            ]
+        user_prompt[:] = [e for e in user_prompt if e.get("hooks")]
+        already_has_prompt_hook = any(
+            any(h.get("command", "") == inject_command for h in entry.get("hooks", []))
+            for entry in user_prompt
+        )
+        if not already_has_prompt_hook:
+            user_prompt.append({
+                "hooks": [{
+                    "type": "command",
+                    "command": inject_command,
+                    "timeout": 15,
+                    "statusMessage": "Checking agentpack context...",
+                }]
+            })
+
+        new_content = json.dumps(existing, indent=2) + "\n"
+        if settings_path.exists() and settings_path.read_text() == new_content:
+            return "unchanged"
+        settings_path.write_text(new_content)
+        return "updated"

agentpack/installers/codex.py

@@ -0,0 +1,54 @@
+from __future__ import annotations
+
+import re
+from pathlib import Path
+
+from agentpack.integrations.git_hooks import install_git_hooks
+
+_AGENTPACK_BLOCK = """\
+<!-- agentpack:start -->
+## AgentPack Context
+
+If `.agentpack/session.json` exists and `"active": true`:
+
+1. Read `.agentpack/context.md` before making code changes.
+2. For a new coding task, write a one-line summary to `.agentpack/task.md`.
+3. Re-read `.agentpack/context.md` after watch mode refreshes it.
+4. Use AgentPack-selected files as starting points, not as absolute truth.
+5. If context is missing or stale: `agentpack session refresh`
+<!-- agentpack:end -->"""
+
+_BLOCK_RE = re.compile(
+    r"<!-- agentpack:start -->.*?<!-- agentpack:end -->",
+    re.DOTALL,
+)
+
+
+class CodexInstaller:
+    """Configures Codex/OpenAI-specific repo files and auto-repack hooks."""
+
+    def patch_agents_md(self, root: Path) -> str:
+        """Insert/update AgentPack block in AGENTS.md. Returns action taken."""
+        agents_md = root / "AGENTS.md"
+
+        if not agents_md.exists():
+            agents_md.write_text(f"{_AGENTPACK_BLOCK}\n")
+            return "created"
+
+        content = agents_md.read_text()
+        if _BLOCK_RE.search(content):
+            new_content = _BLOCK_RE.sub(_AGENTPACK_BLOCK, content)
+            if new_content != content:
+                agents_md.write_text(new_content)
+                return "updated"
+            return "unchanged"
+
+        agents_md.write_text(content.rstrip() + "\n\n" + _AGENTPACK_BLOCK + "\n")
+        return "appended"
+
+    def install_auto_repack(self, root: Path) -> dict[str, str]:
+        """Install git hooks for auto-repack. Returns results dict."""
+        results: dict[str, str] = {}
+        hook_results = install_git_hooks(root, agent="codex")
+        results.update({f"git:{k}": v for k, v in hook_results.items()})
+        return results

agentpack/installers/cursor.py

@@ -0,0 +1,76 @@
+from __future__ import annotations
+
+import re
+from pathlib import Path
+
+from agentpack.integrations.git_hooks import install_git_hooks
+from agentpack.integrations.vscode_tasks import install_vscode_tasks
+
+_CURSOR_RULE = """\
+<!-- agentpack:rule:start -->
+If `.agentpack/session.json` exists and active, read `.agentpack/context.md` at the start of every conversation.
+For a new task, update `.agentpack/task.md` with a one-line summary.
+If context is stale or missing: agentpack session refresh
+<!-- agentpack:rule:end -->"""
+
+_RULE_RE = re.compile(
+    r"<!-- agentpack:rule:start -->.*?<!-- agentpack:rule:end -->",
+    re.DOTALL,
+)
+
+
+class CursorInstaller:
+    """Configures Cursor-specific repo files and auto-repack hooks."""
+
+    def patch_cursor_rules(self, root: Path) -> str:
+        """Insert/update agentpack rule in .cursorrules. Returns action taken."""
+        rules_file = root / ".cursorrules"
+
+        if not rules_file.exists():
+            rules_file.write_text(f"{_CURSOR_RULE}\n")
+            return "created"
+
+        content = rules_file.read_text()
+        if _RULE_RE.search(content):
+            new_content = _RULE_RE.sub(_CURSOR_RULE, content)
+            if new_content != content:
+                rules_file.write_text(new_content)
+                return "updated"
+            return "unchanged"
+
+        rules_file.write_text(content.rstrip() + "\n\n" + _CURSOR_RULE + "\n")
+        return "appended"
+
+    def patch_cursor_mdc(self, root: Path) -> str:
+        """Write agentpack rule as a Cursor .mdc rule file (Cursor v0.43+)."""
+        rules_dir = root / ".cursor" / "rules"
+        rules_dir.mkdir(parents=True, exist_ok=True)
+        mdc_path = rules_dir / "agentpack.mdc"
+
+        content = """\
+---
+description: AgentPack session context injection
+alwaysApply: true
+---
+
+When working in this repository:
+
+1. Check `.agentpack/session.json` — if `"active": true`, read `.agentpack/context.md` before editing code.
+2. For a new user task, write a one-line summary to `.agentpack/task.md`.
+3. Prefer files with high AgentPack scores as starting points.
+4. If context seems unrelated to the task, run: `agentpack session refresh`
+"""
+        already = mdc_path.exists()
+        if already and mdc_path.read_text() == content:
+            return "unchanged"
+
+        mdc_path.write_text(content)
+        return "updated" if already else "created"
+
+    def install_auto_repack(self, root: Path) -> dict[str, str]:
+        """Install git hooks + VS Code tasks for auto-repack. Returns results dict."""
+        results: dict[str, str] = {}
+        hook_results = install_git_hooks(root, agent="cursor")
+        results.update({f"git:{k}": v for k, v in hook_results.items()})
+        results["vscode:tasks"] = install_vscode_tasks(root, agent="cursor")
+        return results

agentpack/installers/windsurf.py

@@ -0,0 +1,50 @@
+from __future__ import annotations
+
+import re
+from pathlib import Path
+
+from agentpack.integrations.git_hooks import install_git_hooks
+from agentpack.integrations.vscode_tasks import install_vscode_tasks
+
+_WINDSURF_RULE = """\
+<!-- agentpack:rule:start -->
+If `.agentpack/session.json` exists and active, read `.agentpack/context.md` at the start of every conversation.
+For a new task, update `.agentpack/task.md` with a one-line summary.
+If context is stale or missing: agentpack session refresh
+<!-- agentpack:rule:end -->"""
+
+_RULE_RE = re.compile(
+    r"<!-- agentpack:rule:start -->.*?<!-- agentpack:rule:end -->",
+    re.DOTALL,
+)
+
+
+class WindsurfInstaller:
+    """Configures Windsurf-specific repo files and auto-repack hooks."""
+
+    def patch_windsurfrules(self, root: Path) -> str:
+        """Insert/update agentpack rule in .windsurfrules. Returns action taken."""
+        rules_file = root / ".windsurfrules"
+
+        if not rules_file.exists():
+            rules_file.write_text(f"{_WINDSURF_RULE}\n")
+            return "created"
+
+        content = rules_file.read_text()
+        if _RULE_RE.search(content):
+            new_content = _RULE_RE.sub(_WINDSURF_RULE, content)
+            if new_content != content:
+                rules_file.write_text(new_content)
+                return "updated"
+            return "unchanged"
+
+        rules_file.write_text(content.rstrip() + "\n\n" + _WINDSURF_RULE + "\n")
+        return "appended"
+
+    def install_auto_repack(self, root: Path) -> dict[str, str]:
+        """Install git hooks + VS Code tasks for auto-repack. Returns results dict."""
+        results: dict[str, str] = {}
+        hook_results = install_git_hooks(root, agent="windsurf")
+        results.update({f"git:{k}": v for k, v in hook_results.items()})
+        results["vscode:tasks"] = install_vscode_tasks(root, agent="windsurf")
+        return results

agentpack/integrations/git_hooks.py

@@ -0,0 +1,109 @@
+from __future__ import annotations
+
+import stat
+from pathlib import Path
+
+# Hooks that indicate the working tree changed and the pack may be stale.
+_HOOK_EVENTS = ("post-commit", "post-merge", "post-checkout")
+
+_AGENTPACK_MARKER = "# agentpack:auto-repack"
+
+
+def _hook_script(agent: str) -> str:
+    return (
+        f"{_AGENTPACK_MARKER}\n"
+        f"agentpack pack --agent {agent} --task auto --mode balanced "
+        f">/dev/null 2>&1 &\n"
+    )
+
+
+def install_git_hooks(root: Path, agent: str) -> dict[str, str]:
+    """Install agentpack auto-repack lines into .git/hooks/*.
+
+    Returns {hook_name: action} where action is created|updated|unchanged.
+    Idempotent — safe to re-run. Appends to existing hooks rather than replacing.
+    """
+    hooks_dir = root / ".git" / "hooks"
+    if not hooks_dir.exists():
+        return {}
+
+    results: dict[str, str] = {}
+    snippet = _hook_script(agent)
+
+    for event in _HOOK_EVENTS:
+        hook_path = hooks_dir / event
+        if hook_path.exists():
+            content = hook_path.read_text()
+            if _AGENTPACK_MARKER in content:
+                # Already installed — update the agent name if it changed
+                lines = content.splitlines(keepends=True)
+                new_lines = []
+                skip_next = False
+                for line in lines:
+                    if line.strip() == _AGENTPACK_MARKER:
+                        new_lines.append(snippet)
+                        skip_next = True
+                        continue
+                    if skip_next:
+                        skip_next = False
+                        continue
+                    new_lines.append(line)
+                new_content = "".join(new_lines)
+                if new_content != content:
+                    hook_path.write_text(new_content)
+                    results[event] = "updated"
+                else:
+                    results[event] = "unchanged"
+            else:
+                # Append to existing hook
+                sep = "" if content.endswith("\n") else "\n"
+                hook_path.write_text(content + sep + snippet)
+                results[event] = "appended"
+        else:
+            hook_path.write_text(f"#!/bin/sh\n{snippet}")
+            results[event] = "created"
+
+        # Ensure executable
+        current = hook_path.stat().st_mode
+        hook_path.chmod(current | stat.S_IXUSR | stat.S_IXGRP | stat.S_IXOTH)
+
+    return results
+
+
+def remove_git_hooks(root: Path) -> dict[str, str]:
+    """Remove agentpack lines from .git/hooks/*. Returns {hook_name: action}."""
+    hooks_dir = root / ".git" / "hooks"
+    if not hooks_dir.exists():
+        return {}
+
+    results: dict[str, str] = {}
+    for event in _HOOK_EVENTS:
+        hook_path = hooks_dir / event
+        if not hook_path.exists():
+            continue
+        content = hook_path.read_text()
+        if _AGENTPACK_MARKER not in content:
+            results[event] = "unchanged"
+            continue
+        lines = content.splitlines(keepends=True)
+        new_lines = []
+        skip_next = False
+        for line in lines:
+            if line.strip() == _AGENTPACK_MARKER:
+                skip_next = True
+                continue
+            if skip_next:
+                skip_next = False
+                continue
+            new_lines.append(line)
+        new_content = "".join(new_lines)
+        # Remove file if only shebang remains
+        stripped = new_content.strip()
+        if stripped in ("", "#!/bin/sh", "#!/bin/bash"):
+            hook_path.unlink()
+            results[event] = "removed"
+        else:
+            hook_path.write_text(new_content)
+            results[event] = "cleaned"
+
+    return results

agentpack/integrations/global_install.py

@@ -0,0 +1,221 @@
+from __future__ import annotations
+
+import os
+import re
+import stat
+from pathlib import Path
+
+# ---------------------------------------------------------------------------
+# Git template hooks — copied into .git/hooks/ on every git init / git clone
+# ---------------------------------------------------------------------------
+
+_GIT_TEMPLATE_DIR = Path.home() / ".git-templates"
+_AGENTPACK_MARKER = "# agentpack:global"
+
+_POST_CHECKOUT_SCRIPT = """\
+#!/bin/sh
+# agentpack:global
+# Repack only if this repo has already been opted in to agentpack.
+[ -f .agentpack/config.toml ] && agentpack pack --task auto --mode balanced >/dev/null 2>&1 &
+"""
+
+_POST_COMMIT_SCRIPT = """\
+#!/bin/sh
+# agentpack:global
+# Repack only if this repo has already been opted in to agentpack.
+[ -f .agentpack/config.toml ] && agentpack pack --task auto --mode balanced >/dev/null 2>&1 &
+"""
+
+_POST_MERGE_SCRIPT = """\
+#!/bin/sh
+# agentpack:global
+# Repack only if this repo has already been opted in to agentpack.
+[ -f .agentpack/config.toml ] && agentpack pack --task auto --mode balanced >/dev/null 2>&1 &
+"""
+
+_HOOK_SCRIPTS = {
+    "post-checkout": _POST_CHECKOUT_SCRIPT,
+    "post-commit": _POST_COMMIT_SCRIPT,
+    "post-merge": _POST_MERGE_SCRIPT,
+}
+
+
+def install_git_template_hooks(dry_run: bool = False) -> dict[str, str]:
+    """Install agentpack hooks into ~/.git-templates/hooks/.
+
+    Git copies these into every new repo on `git init` or `git clone`.
+    Returns {hook_name: action}. With dry_run=True, reports what would happen.
+    """
+    hooks_dir = _GIT_TEMPLATE_DIR / "hooks"
+    if not dry_run:
+        hooks_dir.mkdir(parents=True, exist_ok=True)
+
+    results: dict[str, str] = {}
+    for name, script in _HOOK_SCRIPTS.items():
+        hook_path = hooks_dir / name
+        if hook_path.exists():
+            content = hook_path.read_text()
+            if _AGENTPACK_MARKER in content:
+                results[name] = "unchanged"
+                continue
+            results[name] = "would-append" if dry_run else "appended"
+            if not dry_run:
+                sep = "" if content.endswith("\n") else "\n"
+                hook_path.write_text(content + sep + script)
+        else:
+            results[name] = "would-create" if dry_run else "created"
+            if not dry_run:
+                hook_path.write_text(script)
+        if not dry_run:
+            hook_path.chmod(hook_path.stat().st_mode | stat.S_IXUSR | stat.S_IXGRP | stat.S_IXOTH)
+
+    return results
+
+
+def configure_git_template_dir(dry_run: bool = False) -> str:
+    """Set git's global init.templateDir to ~/.git-templates. Returns action taken."""
+    if dry_run:
+        return "would-configure"
+    import subprocess
+    result = subprocess.run(
+        ["git", "config", "--global", "init.templateDir", str(_GIT_TEMPLATE_DIR)],
+        capture_output=True, text=True,
+    )
+    return "configured" if result.returncode == 0 else "failed"
+
+
+def remove_git_template_hooks() -> dict[str, str]:
+    """Remove agentpack lines from ~/.git-templates/hooks/*."""
+    hooks_dir = _GIT_TEMPLATE_DIR / "hooks"
+    if not hooks_dir.exists():
+        return {}
+
+    results: dict[str, str] = {}
+    for name in _HOOK_SCRIPTS:
+        hook_path = hooks_dir / name
+        if not hook_path.exists():
+            continue
+        content = hook_path.read_text()
+        if _AGENTPACK_MARKER not in content:
+            results[name] = "unchanged"
+            continue
+        # Remove agentpack block (shebang + marker + agentpack lines)
+        lines = content.splitlines(keepends=True)
+        new_lines: list[str] = []
+        skip = False
+        for line in lines:
+            if _AGENTPACK_MARKER in line:
+                skip = True
+                # Also remove the preceding shebang if it was the only line before marker
+                if new_lines and new_lines[-1].strip().startswith("#!/"):
+                    prev = "".join(new_lines[:-1])
+                    if not prev.strip():
+                        new_lines.pop()
+                continue
+            if skip:
+                if line.startswith("agentpack ") or line.strip() == "":
+                    continue
+                skip = False
+            new_lines.append(line)
+
+        new_content = "".join(new_lines).strip()
+        if new_content in ("", "#!/bin/sh", "#!/bin/bash"):
+            hook_path.unlink()
+            results[name] = "removed"
+        else:
+            hook_path.write_text(new_content + "\n")
+            results[name] = "cleaned"
+
+    return results
+
+
+# ---------------------------------------------------------------------------
+# Shell rc hook — `cd` into any git repo → auto-bootstrap agentpack
+# ---------------------------------------------------------------------------
+
+_SHELL_MARKER_START = "# agentpack:chpwd:start"
+_SHELL_MARKER_END = "# agentpack:chpwd:end"
+
+_ZSH_HOOK = """\
+# agentpack:chpwd:start
+_agentpack_chpwd() {
+  # Only act on repos explicitly opted in (have .agentpack/config.toml).
+  # Does NOT auto-init unknown repos — that's an explicit 'agentpack init' decision.
+  if [ -f .agentpack/config.toml ]; then
+    agentpack status >/dev/null 2>&1 || agentpack pack --task auto --mode balanced >/dev/null 2>&1 &
+  fi
+}
+autoload -Uz add-zsh-hook
+add-zsh-hook chpwd _agentpack_chpwd
+# agentpack:chpwd:end"""
+
+_BASH_HOOK = """\
+# agentpack:chpwd:start
+_agentpack_chpwd() {
+  # Only act on repos explicitly opted in (have .agentpack/config.toml).
+  if [ -f .agentpack/config.toml ]; then
+    agentpack status >/dev/null 2>&1 || agentpack pack --task auto --mode balanced >/dev/null 2>&1 &
+  fi
+}
+if [[ "$PROMPT_COMMAND" != *"_agentpack_chpwd"* ]]; then
+  PROMPT_COMMAND="${PROMPT_COMMAND:+$PROMPT_COMMAND; }_agentpack_chpwd"
+fi
+# agentpack:chpwd:end"""
+
+_BLOCK_RE = re.compile(
+    r"# agentpack:chpwd:start.*?# agentpack:chpwd:end\n?",
+    re.DOTALL,
+)
+
+
+def _detect_rc_file() -> Path | None:
+    shell = os.environ.get("SHELL", "")
+    if "zsh" in shell:
+        return Path.home() / ".zshrc"
+    if "bash" in shell:
+        rc = Path.home() / ".bashrc"
+        profile = Path.home() / ".bash_profile"
+        return rc if rc.exists() else profile
+    return None
+
+
+def install_shell_hook(rc_file: Path | None = None, dry_run: bool = False) -> tuple[str, Path | None]:
+    """Append agentpack chpwd hook to shell rc. Returns (action, rc_path)."""
+    target = rc_file or _detect_rc_file()
+    if target is None:
+        return "skipped (unknown shell)", None
+
+    shell_hook = _ZSH_HOOK if "zsh" in str(target) else _BASH_HOOK
+
+    if target.exists():
+        content = target.read_text()
+        if _SHELL_MARKER_START in content:
+            new_content = _BLOCK_RE.sub(shell_hook + "\n", content)
+            if new_content != content:
+                if not dry_run:
+                    target.write_text(new_content)
+                return "would-update" if dry_run else "updated", target
+            return "unchanged", target
+        if not dry_run:
+            sep = "" if content.endswith("\n") else "\n"
+            target.write_text(content + sep + shell_hook + "\n")
+        return "would-append" if dry_run else "appended", target
+    else:
+        if not dry_run:
+            target.write_text(shell_hook + "\n")
+        return "would-create" if dry_run else "created", target
+
+
+def remove_shell_hook(rc_file: Path | None = None) -> tuple[str, Path | None]:
+    """Remove agentpack chpwd hook from shell rc. Returns (action, rc_path)."""
+    target = rc_file or _detect_rc_file()
+    if target is None or not target.exists():
+        return "unchanged", target
+
+    content = target.read_text()
+    if _SHELL_MARKER_START not in content:
+        return "unchanged", target
+
+    new_content = _BLOCK_RE.sub("", content)
+    target.write_text(new_content)
+    return "removed", target