agent-hygiene 0.1.0__py3-none-any.whl

agent_hygiene/__init__.py

@@ -0,0 +1,3 @@
+"""agent-hygiene: inventory and clean up the footprint of coding-agent CLIs."""
+
+__version__ = "0.1.0"

agent_hygiene/__main__.py

@@ -0,0 +1,4 @@
+from .cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

agent_hygiene/agents.py

@@ -0,0 +1,222 @@
+"""Registry of known coding-agent CLIs and where each one leaves its footprint.
+
+Everything the scanner knows about a specific agent lives here, so adding an agent
+means adding one AgentSpec. Paths are relative to $HOME unless absolute and may
+contain glob characters.
+"""
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from typing import List, Optional, Tuple
+
+
+@dataclass(frozen=True)
+class SelfUpdateSpec:
+    """A JSON settings file plus the nested key that turns self-update off."""
+
+    path: str
+    key: Tuple[str, ...]
+    disabled_value: object
+    note: str = ""
+
+
+@dataclass(frozen=True)
+class AgentSpec:
+    name: str
+    display: str
+    home_dirs: Tuple[str, ...] = ()
+    data_dirs: Tuple[str, ...] = ()
+    npm_packages: Tuple[str, ...] = ()
+    pip_packages: Tuple[str, ...] = ()
+    binaries: Tuple[str, ...] = ()
+    versions_roots: Tuple[str, ...] = ()
+    current_links: Tuple[str, ...] = ()
+    process_patterns: Tuple[str, ...] = ()
+    autostart_patterns: Tuple[str, ...] = ()
+    self_update: Optional[SelfUpdateSpec] = None
+    self_update_note: str = ""
+
+    def process_regex(self) -> List["re.Pattern[str]"]:
+        return [re.compile(p) for p in self.process_patterns]
+
+    def autostart_regex(self) -> List["re.Pattern[str]"]:
+        return [re.compile(p, re.IGNORECASE) for p in self.autostart_patterns]
+
+    def matches_process(self, command: str) -> bool:
+        return any(r.search(command) for r in self.process_regex())
+
+    def matches_autostart(self, text: str) -> bool:
+        return any(r.search(text) for r in self.autostart_regex())
+
+
+_CURSOR_IDE_MAC = "~/Library/Application Support/Cursor/User/globalStorage/anysphere.cursor-agent-worker"
+_CURSOR_IDE_LINUX = "~/.config/Cursor/User/globalStorage/anysphere.cursor-agent-worker"
+
+AGENTS: List[AgentSpec] = [
+    AgentSpec(
+        name="codex",
+        display="OpenAI Codex CLI",
+        home_dirs=("~/.codex",),
+        npm_packages=("@openai/codex",),
+        binaries=("codex",),
+        process_patterns=(r"(^|/)codex(\s|$)", r"@openai/codex", r"codex-(x86_64|aarch64)-"),
+        autostart_patterns=(r"openai", r"\bcodex\b"),
+        self_update_note="Codex CLI has no background self-updater; it only prints an "
+        "update notice. Update with `npm i -g @openai/codex`.",
+    ),
+    AgentSpec(
+        name="claude",
+        display="Anthropic Claude Code",
+        home_dirs=("~/.claude", "~/.claude.json", "~/.claude.json.backup"),
+        data_dirs=("~/.local/share/claude", "~/.cache/claude", "~/Library/Caches/claude-cli-nodejs"),
+        npm_packages=("@anthropic-ai/claude-code",),
+        binaries=("claude",),
+        versions_roots=("~/.local/share/claude/versions",),
+        current_links=("~/.local/bin/claude", "~/.claude/local/claude"),
+        process_patterns=(
+            r"(^|/)claude(\s|$)",
+            r"/\.local/share/claude/versions/",
+            r"@anthropic-ai/claude-code",
+        ),
+        autostart_patterns=(r"anthropic", r"\bclaude\b"),
+        self_update=SelfUpdateSpec(
+            path="~/.claude/settings.json",
+            key=("env", "DISABLE_AUTOUPDATER"),
+            disabled_value="1",
+            note="Sets env.DISABLE_AUTOUPDATER=\"1\" in ~/.claude/settings.json.",
+        ),
+    ),
+    AgentSpec(
+        name="cursor",
+        display="Cursor Agent CLI",
+        home_dirs=("~/.cursor",),
+        data_dirs=(
+            "~/.local/share/cursor-agent",
+            "~/.cache/cursor-agent",
+            # the Cursor IDE ships its own copy of the agent CLI and keeps every version
+            _CURSOR_IDE_MAC + "/agent-cli",
+            _CURSOR_IDE_LINUX + "/agent-cli",
+        ),
+        binaries=("cursor-agent", "agent"),
+        versions_roots=(
+            "~/.local/share/cursor-agent/versions",
+            _CURSOR_IDE_MAC + "/agent-cli/.local/share/cursor-agent/versions",
+            _CURSOR_IDE_LINUX + "/agent-cli/.local/share/cursor-agent/versions",
+        ),
+        current_links=(
+            "~/.local/bin/cursor-agent",
+            "~/.local/bin/agent",
+            _CURSOR_IDE_MAC + "/agent-cli/.local/bin/cursor-agent",
+            _CURSOR_IDE_LINUX + "/agent-cli/.local/bin/cursor-agent",
+        ),
+        process_patterns=(r"cursor[-_]agent", r"/\.local/share/cursor-agent/"),
+        autostart_patterns=(r"cursor[-_.]agent", r"anysphere.*agent"),
+        self_update_note="Cursor Agent CLI versions are managed by `cursor-agent update`; "
+        "there is no documented setting to disable the updater.",
+    ),
+    AgentSpec(
+        name="gemini",
+        display="Google Gemini CLI",
+        home_dirs=("~/.gemini",),
+        npm_packages=("@google/gemini-cli",),
+        binaries=("gemini",),
+        process_patterns=(r"(^|/)gemini(\s|$)", r"@google/gemini-cli"),
+        autostart_patterns=(r"gemini[-_.]cli", r"\bgemini\b"),
+        self_update=SelfUpdateSpec(
+            path="~/.gemini/settings.json",
+            key=("general", "disableAutoUpdate"),
+            disabled_value=True,
+            note="Sets general.disableAutoUpdate=true in ~/.gemini/settings.json.",
+        ),
+    ),
+    AgentSpec(
+        name="copilot",
+        display="GitHub Copilot CLI",
+        home_dirs=("~/.copilot",),
+        npm_packages=("@github/copilot",),
+        binaries=("copilot",),
+        process_patterns=(r"(^|/)copilot(\s|$)", r"@github/copilot"),
+        autostart_patterns=(r"github[-_.]copilot", r"\bcopilot\b"),
+        self_update_note="No documented setting; update with `npm i -g @github/copilot`.",
+    ),
+    AgentSpec(
+        name="opencode",
+        display="OpenCode",
+        home_dirs=("~/.config/opencode",),
+        data_dirs=("~/.local/share/opencode", "~/.cache/opencode", "~/.opencode"),
+        npm_packages=("opencode-ai",),
+        binaries=("opencode",),
+        process_patterns=(r"(^|/)opencode(\s|$)",),
+        autostart_patterns=(r"\bopencode\b",),
+        self_update=SelfUpdateSpec(
+            path="~/.config/opencode/opencode.json",
+            key=("autoupdate",),
+            disabled_value=False,
+            note="Sets autoupdate=false in ~/.config/opencode/opencode.json.",
+        ),
+    ),
+    AgentSpec(
+        name="devin",
+        display="Devin CLI",
+        data_dirs=("~/.local/share/devin", "~/.config/devin"),
+        binaries=("devin",),
+        process_patterns=(r"(^|/)devin(\s|$)", r"/\.local/share/devin/"),
+        autostart_patterns=(r"\bdevin\b", r"cognition"),
+        self_update_note="No documented setting to disable updates.",
+    ),
+    AgentSpec(
+        name="aider",
+        display="Aider",
+        home_dirs=("~/.aider", "~/.aider.conf.yml", "~/.aider.model.settings.yml"),
+        data_dirs=("~/.local/pipx/venvs/aider-chat", "~/.local/share/uv/tools/aider-chat"),
+        pip_packages=("aider-chat",),
+        binaries=("aider",),
+        process_patterns=(r"(^|/)aider(\s|$)",),
+        autostart_patterns=(r"\baider\b",),
+        self_update_note="Aider checks for updates at start; disable with --no-check-update "
+        "in ~/.aider.conf.yml (check-update: false).",
+    ),
+]
+
+# Anything matching these is never attributed to an agent, even if an agent pattern hits.
+EXCLUDE_PROCESS_PATTERNS = [
+    re.compile(r"agent[-_]hygiene"),
+    re.compile(r"(^|/)(rg|grep|egrep|ps|lsof|less|more|tail|cat|vim|nano|code)\s"),
+]
+
+
+def by_name(name: str) -> Optional[AgentSpec]:
+    for spec in AGENTS:
+        if spec.name == name:
+            return spec
+    return None
+
+
+def names() -> List[str]:
+    return [a.name for a in AGENTS]
+
+
+def match_process(command: str) -> Optional[str]:
+    if any(p.search(command) for p in EXCLUDE_PROCESS_PATTERNS):
+        return None
+    for spec in AGENTS:
+        if spec.matches_process(command):
+            return spec.name
+    return None
+
+
+def match_autostart(text: str) -> Optional[str]:
+    for spec in AGENTS:
+        if spec.matches_autostart(text):
+            return spec.name
+    return None
+
+
+def guess_from_argv0(argv0: str) -> Optional[str]:
+    """Map the executable passed to `run -- <agent>` to a registered agent."""
+    base = argv0.rsplit("/", 1)[-1]
+    for spec in AGENTS:
+        if base in spec.binaries:
+            return spec.name
+    return match_process(argv0 + " ")

agent_hygiene/clean.py

@@ -0,0 +1,274 @@
+"""Build a plan of fixes from an inventory, preview it, and apply it with a backup journal.
+
+Each applied action writes a restore record into the journal; `restore.py` reverses them
+in reverse order. Killing a process is the only irreversible action and is opt-in.
+"""
+from __future__ import annotations
+
+import json
+import os
+import shutil
+import signal
+import time
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+
+from . import agents
+from .journal import Journal
+from .model import AutostartEntry, Inventory
+from .output import human_bytes, shorten_home, table
+from .platform import have, run, uid
+from .scan.autostart import read_crontab
+from .scan.footprint import select_prunable
+
+DEFAULT_KEEP = 2
+
+
+@dataclass
+class Action:
+    kind: str  # disable-launchagent | disable-systemd | disable-cron | disable-self-update | prune-version | kill-process
+    agent: str
+    target: str
+    description: str
+    reversible: bool = True
+    bytes: int = 0
+    data: Dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass
+class Plan:
+    actions: List[Action] = field(default_factory=list)
+    skipped: List[str] = field(default_factory=list)
+
+    @property
+    def bytes_to_trash(self) -> int:
+        return sum(a.bytes for a in self.actions if a.kind == "prune-version")
+
+
+# --- planning -----------------------------------------------------------------------
+
+def build_plan(
+    inv: Inventory,
+    autostart: bool = True,
+    self_update: bool = True,
+    prune: bool = True,
+    kill: bool = False,
+    keep: int = DEFAULT_KEEP,
+    keep_per_agent: Optional[Dict[str, int]] = None,
+) -> Plan:
+    plan = Plan()
+    keep_per_agent = keep_per_agent or {}
+
+    if autostart:
+        for e in inv.autostarts:
+            if not e.enabled:
+                continue
+            if not e.user_writable:
+                plan.skipped.append(f"{e.kind} {e.id} is system-wide ({e.path}); needs sudo, skipped")
+                continue
+            plan.actions.append(_plan_autostart(e))
+
+    if self_update:
+        for a in inv.agents:
+            su = a.self_update
+            if su is None or not su.supported or su.disabled or not a.installed:
+                continue
+            plan.actions.append(Action(
+                kind="disable-self-update", agent=a.name, target=su.path or "",
+                description=f"set {su.key} in {shorten_home(su.path or '')} (backup of file kept)",
+                data={"path": su.path},
+            ))
+
+    if prune:
+        for a in inv.agents:
+            n = keep_per_agent.get(a.name, keep)
+            for v in select_prunable(a.versions, n):
+                plan.actions.append(Action(
+                    kind="prune-version", agent=a.name, target=v.path, bytes=v.bytes,
+                    description=f"move {a.name} {v.version} ({human_bytes(v.bytes)}) to trash; keep newest {n}",
+                    data={"path": v.path, "version": v.version},
+                ))
+
+    if kill:
+        for p in inv.processes:
+            if p.orphaned:
+                plan.actions.append(Action(
+                    kind="kill-process", agent=p.agent or "?", target=str(p.pid), reversible=False,
+                    description=f"terminate pid {p.pid} ({p.command[:60]}) — session ended, parent gone",
+                    data={"pid": p.pid, "command": p.command},
+                ))
+    return plan
+
+
+def _plan_autostart(e: AutostartEntry) -> Action:
+    if e.kind == "launchagent":
+        return Action(kind="disable-launchagent", agent=e.agent or "?", target=e.id,
+                      description=f"unload LaunchAgent {e.id} and move {shorten_home(e.path)} to backup",
+                      data={"label": e.id, "path": e.path})
+    if e.kind == "systemd-user":
+        return Action(kind="disable-systemd", agent=e.agent or "?", target=e.id,
+                      description=f"systemctl --user disable --now {e.id} (unit file left in place)",
+                      data={"unit": e.id, "path": e.path})
+    return Action(kind="disable-cron", agent=e.agent or "?", target=e.id,
+                  description=f"comment out crontab line: {e.detail} {e.program}"[:110],
+                  data={"line_id": e.id, "program": e.program, "schedule": e.detail})
+
+
+def render_plan(plan: Plan) -> str:
+    if not plan.actions and not plan.skipped:
+        return "nothing to clean"
+    rows = [[i + 1, a.kind, a.agent, "yes" if a.reversible else "NO",
+             human_bytes(a.bytes) if a.bytes else "", a.description] for i, a in enumerate(plan.actions)]
+    out = []
+    if rows:
+        out.append(table(["#", "action", "agent", "reversible", "size", "detail"], rows, max_col=110))
+    if plan.bytes_to_trash:
+        out.append(f"\n{human_bytes(plan.bytes_to_trash)} would move to trash; run `agent-hygiene purge` "
+                   f"later to free it permanently, or `agent-hygiene restore` to put it back.")
+    for s in plan.skipped:
+        out.append(f"skipped: {s}")
+    return "\n".join(out)
+
+
+# --- applying -------------------------------------------------------------------------
+
+def apply_plan(plan: Plan, log=print) -> Optional[Journal]:
+    if not plan.actions:
+        return None
+    journal = Journal.create()
+    log(f"backup id: {journal.id}  ({shorten_home(str(journal.root))})")
+    for action in plan.actions:
+        handler = _APPLIERS[action.kind]
+        try:
+            record = handler(action, journal)
+        except Exception as exc:  # keep going; the journal only records what actually happened
+            log(f"  FAILED {action.kind} {action.target}: {exc}")
+            continue
+        record.update({"kind": action.kind, "agent": action.agent, "target": action.target,
+                       "reversible": action.reversible, "applied_at": time.time()})
+        journal.record(record)
+        log(f"  done   {action.kind} {action.target}")
+    return journal
+
+
+def _apply_launchagent(action: Action, journal: Journal) -> Dict[str, Any]:
+    plist = Path(action.data["path"])
+    label = action.data["label"]
+    bootout = None
+    if have("launchctl"):
+        res = run(["launchctl", "bootout", f"gui/{uid()}/{label}"], timeout=15)
+        if res.returncode != 0:
+            res = run(["launchctl", "unload", str(plist)], timeout=15)
+        bootout = res.returncode
+    dest = journal.unique_file("launchagents", plist.name)
+    shutil.move(str(plist), str(dest))
+    return {"label": label, "original": str(plist), "backup": str(dest), "bootout_rc": bootout}
+
+
+def _apply_systemd(action: Action, journal: Journal) -> Dict[str, Any]:
+    unit = action.data["unit"]
+    was_enabled = run(["systemctl", "--user", "is-enabled", unit], timeout=10).stdout.strip()
+    was_active = run(["systemctl", "--user", "is-active", unit], timeout=10).stdout.strip()
+    res = run(["systemctl", "--user", "disable", "--now", unit], timeout=20)
+    if res.returncode != 0:
+        raise RuntimeError(res.stderr.strip() or f"systemctl exited {res.returncode}")
+    return {"unit": unit, "was_enabled": was_enabled, "was_active": was_active}
+
+
+def _apply_cron(action: Action, journal: Journal) -> Dict[str, Any]:
+    from .scan.autostart import cron_line_id
+
+    text = read_crontab() or ""
+    backup = journal.unique_file("cron", "crontab")
+    backup.write_text(text)
+    new_lines = []
+    hit = False
+    for line in text.splitlines():
+        if not hit and cron_line_id(line.strip()) == action.data["line_id"]:
+            new_lines.append(f"# agent-hygiene disabled: {line}")
+            hit = True
+        else:
+            new_lines.append(line)
+    if not hit:
+        raise RuntimeError("crontab line not found (changed since scan?)")
+    new_text = "\n".join(new_lines) + "\n"
+    res = run(["crontab", "-"], input_text=new_text, timeout=10)
+    if res.returncode != 0:
+        raise RuntimeError(res.stderr.strip() or "crontab write failed")
+    return {"backup": str(backup), "line_id": action.data["line_id"]}
+
+
+def _apply_self_update(action: Action, journal: Journal) -> Dict[str, Any]:
+    spec = agents.by_name(action.agent)
+    assert spec is not None and spec.self_update is not None
+    path = Path(action.data["path"])
+    existed = path.is_file()
+    backup = None
+    if existed:
+        backup = journal.unique_file("settings", f"{action.agent}-{path.name}")
+        shutil.copy2(str(path), str(backup))
+        try:
+            data = json.loads(path.read_text() or "{}")
+        except ValueError as exc:
+            raise RuntimeError(f"{path} is not valid JSON: {exc}")
+    else:
+        data = {}
+        path.parent.mkdir(parents=True, exist_ok=True)
+    cur = data
+    for k in spec.self_update.key[:-1]:
+        if not isinstance(cur.get(k), dict):
+            cur[k] = {}
+        cur = cur[k]
+    cur[spec.self_update.key[-1]] = spec.self_update.disabled_value
+    tmp = path.with_suffix(path.suffix + ".agent-hygiene.tmp")
+    tmp.write_text(json.dumps(data, indent=2) + "\n")
+    if existed:
+        shutil.copymode(str(path), str(tmp))
+    os.replace(tmp, path)
+    return {"path": str(path), "existed": existed, "backup": str(backup) if backup else None}
+
+
+def _apply_prune(action: Action, journal: Journal) -> Dict[str, Any]:
+    src = Path(action.data["path"])
+    dest = journal.trash_slot(action.agent, src.name)
+    # rename within the same filesystem is instant and keeps every attribute intact
+    shutil.move(str(src), str(dest))
+    return {"original": str(src), "trash": str(dest), "bytes": action.bytes}
+
+
+def _apply_kill(action: Action, journal: Journal) -> Dict[str, Any]:
+    pid = int(action.data["pid"])
+    os.kill(pid, signal.SIGTERM)
+    deadline = time.time() + 5
+    while time.time() < deadline:
+        if not _alive(pid):
+            return {"pid": pid, "signal": "TERM", "command": action.data["command"]}
+        time.sleep(0.1)
+    os.kill(pid, signal.SIGKILL)
+    return {"pid": pid, "signal": "KILL", "command": action.data["command"]}
+
+
+def _alive(pid: int) -> bool:
+    try:
+        os.kill(pid, 0)
+    except ProcessLookupError:
+        return False
+    except PermissionError:
+        return True
+    # zombie check on Linux
+    try:
+        with open(f"/proc/{pid}/stat") as fh:
+            return fh.read().split(") ")[-1][0] != "Z"
+    except OSError:
+        return True
+
+
+_APPLIERS = {
+    "disable-launchagent": _apply_launchagent,
+    "disable-systemd": _apply_systemd,
+    "disable-cron": _apply_cron,
+    "disable-self-update": _apply_self_update,
+    "prune-version": _apply_prune,
+    "kill-process": _apply_kill,
+}