cc-tracer 0.1.3__tar.gz

cc_tracer-0.1.3/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 The Claude Code Tracer Authors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

cc_tracer-0.1.3/PKG-INFO

@@ -0,0 +1,148 @@
+Metadata-Version: 2.4
+Name: cc-tracer
+Version: 0.1.3
+Summary: A local, infra-free, raw-fidelity inspector for a single Claude Code session — a DevTools Network tab for Claude Code.
+License: MIT License
+        
+        Copyright (c) 2026 The Claude Code Tracer Authors
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+        
+Project-URL: Homepage, https://github.com/zhluo/claude-code-tracer
+Keywords: claude,claude-code,tracing,debugging,observability
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Environment :: Console
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Debuggers
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: fastapi
+Requires-Dist: uvicorn
+Requires-Dist: httpx
+Dynamic: license-file
+
+# cc-tracer (For Claude Code)
+
+A local, infra-free, raw-fidelity inspector for a **single** Claude Code session — a
+*DevTools Network tab for Claude Code*. Install it, point Claude Code at it, and watch
+one session's hook events and raw API turns on a live timeline.
+
+## How it captures
+
+A local FastAPI server (127.0.0.1:7355) with Two capture tiers:
+
+- **Hook tier** — Claude Code hooks POST to the tracer server. Captures *what Claude
+  did*: prompts, Pre/PostToolUse, results, stop reasons.
+- **API-proxy tier** — point `ANTHROPIC_BASE_URL` at the tracer; it streams `/v1/*` to
+  the real API (plain HTTP in, real HTTPS out — no cert trust needed) and reassembles
+  the streaming response into full API turns: system prompt, message context, reasoning
+  text, token usage — *what Claude saw and thought*.
+
+## Getting started
+
+Prerequisites: `python3` (3.9+), `pip`, and the `claude` CLI on your `PATH`.
+
+Install the package, then let one command do everything — configure the Claude Code
+hooks, start the tracer server, and launch Claude Code routed through it:
+
+```bash
+pip install cc-tracer          # or: pip install -e .   (from a clone)
+cc-tracer start
+```
+
+Then open the tracer UI at <http://127.0.0.1:7355> and use Claude Code as usual. The
+tracer **keeps running after you quit Claude Code** so you can keep browsing the
+capture — run `cc-tracer stop` when you're done.
+
+What `cc-tracer start` does:
+
+1. Merges the tracer hooks into the **project-local** `.claude/settings.json` (in the
+   current directory, so they apply only to this project — not every Claude session;
+   idempotent, backs the original up to `.bak` once). Use `--settings PATH` to target a
+   different file, e.g. `~/.claude/settings.json` to trace globally.
+2. Starts a detached tracer server on `:7355` (hook sink + UI + API proxy), or reuses
+   one already running there. The server is left running when Claude exits.
+3. Exports ANTHROPIC_BASE_URL=http://127.0.0.1:7355 and runs `claude` (you can pass claude args after `--`). 
+
+Session JSONL is written to `~/.cc-tracer/logs/` (override with `TRACER_LOG_DIR` or
+`--log-dir`).
+
+For instance:
+```bash
+cc-tracer start \
+  --log-dir ./logs/ \
+  -- -c # -c to continue recent claude session
+```
+
+To run **just the server** without launching Claude — e.g. to browse past captures in
+the UI — use 
+```bash
+cc-tracer start --server-only
+```
+
+### Stopping
+
+```bash
+cc-tracer stop    # stop the server AND remove the tracer's hooks
+```
+
+Hooks follow the server's lifecycle: `start` adds them and `stop` removes only the
+tracer's own entries (your other hooks are left alone). With the server running, you
+can also point a Claude session you launch yourself at it with
+`export ANTHROPIC_BASE_URL=http://127.0.0.1:7355`.
+
+## When to use this vs. OpenTelemetry
+
+Claude Code emits OpenTelemetry natively, and tools like SigNoz, Grafana, and
+LangSmith build on it. They are **aggregate observability** — dashboards, cost/latency
+trends, alerting, cross-session correlation across a fleet. If that's your goal, use
+them; this tracer doesn't try to.
+
+This tracer targets the thing those tools explicitly aren't: a **local, infra-free,
+raw-fidelity inspector for a single session** — think "DevTools Network tab for Claude
+Code."
+
+| | This tracer | Native OTel (SigNoz / Grafana / LangSmith) |
+| --- | --- | --- |
+| Raw API request/response body | ✅ | ❌ (spans/metrics; content redacted by default) |
+| Reasoning / thinking text | ✅ | ❌ |
+| Tool layer (Pre/Post, Edit diffs) | ✅ | ✅ |
+| Backend infra required | none (JSONL + one HTML file) | collector + storage + UI |
+| Data stays fully local | ✅ | configurable / often SaaS |
+| Cross-session stats & alerting | ❌ | ✅ |
+
+The closest off-the-shelf analog is a manual mitmproxy setup; the base-URL forwarder
+avoids that approach's CA forging and `NODE_EXTRA_CA_CERTS` fuss.
+
+### Caveats
+
+- **Proxy ≠ full coverage.** The API proxy only sees HTTP traffic. Transport that
+  isn't plain HTTP (e.g. the Agent SDK's IPC/WebSocket) is captured only at the hook
+  tier. Native OTel emits regardless of transport.
+- **SSE reassembly is schema-coupled.** Rebuilding turns depends on the current
+  Anthropic event shape, so it needs upkeep when the API evolves — a maintenance cost
+  the OTel-based tools don't carry.

cc_tracer-0.1.3/README.md

@@ -0,0 +1,101 @@
+# cc-tracer (For Claude Code)
+
+A local, infra-free, raw-fidelity inspector for a **single** Claude Code session — a
+*DevTools Network tab for Claude Code*. Install it, point Claude Code at it, and watch
+one session's hook events and raw API turns on a live timeline.
+
+## How it captures
+
+A local FastAPI server (127.0.0.1:7355) with Two capture tiers:
+
+- **Hook tier** — Claude Code hooks POST to the tracer server. Captures *what Claude
+  did*: prompts, Pre/PostToolUse, results, stop reasons.
+- **API-proxy tier** — point `ANTHROPIC_BASE_URL` at the tracer; it streams `/v1/*` to
+  the real API (plain HTTP in, real HTTPS out — no cert trust needed) and reassembles
+  the streaming response into full API turns: system prompt, message context, reasoning
+  text, token usage — *what Claude saw and thought*.
+
+## Getting started
+
+Prerequisites: `python3` (3.9+), `pip`, and the `claude` CLI on your `PATH`.
+
+Install the package, then let one command do everything — configure the Claude Code
+hooks, start the tracer server, and launch Claude Code routed through it:
+
+```bash
+pip install cc-tracer          # or: pip install -e .   (from a clone)
+cc-tracer start
+```
+
+Then open the tracer UI at <http://127.0.0.1:7355> and use Claude Code as usual. The
+tracer **keeps running after you quit Claude Code** so you can keep browsing the
+capture — run `cc-tracer stop` when you're done.
+
+What `cc-tracer start` does:
+
+1. Merges the tracer hooks into the **project-local** `.claude/settings.json` (in the
+   current directory, so they apply only to this project — not every Claude session;
+   idempotent, backs the original up to `.bak` once). Use `--settings PATH` to target a
+   different file, e.g. `~/.claude/settings.json` to trace globally.
+2. Starts a detached tracer server on `:7355` (hook sink + UI + API proxy), or reuses
+   one already running there. The server is left running when Claude exits.
+3. Exports ANTHROPIC_BASE_URL=http://127.0.0.1:7355 and runs `claude` (you can pass claude args after `--`). 
+
+Session JSONL is written to `~/.cc-tracer/logs/` (override with `TRACER_LOG_DIR` or
+`--log-dir`).
+
+For instance:
+```bash
+cc-tracer start \
+  --log-dir ./logs/ \
+  -- -c # -c to continue recent claude session
+```
+
+To run **just the server** without launching Claude — e.g. to browse past captures in
+the UI — use 
+```bash
+cc-tracer start --server-only
+```
+
+### Stopping
+
+```bash
+cc-tracer stop    # stop the server AND remove the tracer's hooks
+```
+
+Hooks follow the server's lifecycle: `start` adds them and `stop` removes only the
+tracer's own entries (your other hooks are left alone). With the server running, you
+can also point a Claude session you launch yourself at it with
+`export ANTHROPIC_BASE_URL=http://127.0.0.1:7355`.
+
+## When to use this vs. OpenTelemetry
+
+Claude Code emits OpenTelemetry natively, and tools like SigNoz, Grafana, and
+LangSmith build on it. They are **aggregate observability** — dashboards, cost/latency
+trends, alerting, cross-session correlation across a fleet. If that's your goal, use
+them; this tracer doesn't try to.
+
+This tracer targets the thing those tools explicitly aren't: a **local, infra-free,
+raw-fidelity inspector for a single session** — think "DevTools Network tab for Claude
+Code."
+
+| | This tracer | Native OTel (SigNoz / Grafana / LangSmith) |
+| --- | --- | --- |
+| Raw API request/response body | ✅ | ❌ (spans/metrics; content redacted by default) |
+| Reasoning / thinking text | ✅ | ❌ |
+| Tool layer (Pre/Post, Edit diffs) | ✅ | ✅ |
+| Backend infra required | none (JSONL + one HTML file) | collector + storage + UI |
+| Data stays fully local | ✅ | configurable / often SaaS |
+| Cross-session stats & alerting | ❌ | ✅ |
+
+The closest off-the-shelf analog is a manual mitmproxy setup; the base-URL forwarder
+avoids that approach's CA forging and `NODE_EXTRA_CA_CERTS` fuss.
+
+### Caveats
+
+- **Proxy ≠ full coverage.** The API proxy only sees HTTP traffic. Transport that
+  isn't plain HTTP (e.g. the Agent SDK's IPC/WebSocket) is captured only at the hook
+  tier. Native OTel emits regardless of transport.
+- **SSE reassembly is schema-coupled.** Rebuilding turns depends on the current
+  Anthropic event shape, so it needs upkeep when the API evolves — a maintenance cost
+  the OTel-based tools don't carry.

cc_tracer-0.1.3/pyproject.toml

@@ -0,0 +1,38 @@
+[build-system]
+requires = ["setuptools>=61"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "cc-tracer"
+version = "0.1.3"
+description = "A local, infra-free, raw-fidelity inspector for a single Claude Code session — a DevTools Network tab for Claude Code."
+readme = "README.md"
+requires-python = ">=3.9"
+license = { file = "LICENSE" }
+keywords = ["claude", "claude-code", "tracing", "debugging", "observability"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Environment :: Console",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Software Development :: Debuggers",
+]
+dependencies = ["fastapi", "uvicorn", "httpx"]
+
+[project.scripts]
+cc-tracer = "cc_tracer.cli:main"
+
+[project.urls]
+Homepage = "https://github.com/zhluo/claude-code-tracer"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+cc_tracer = ["static/*", "settings_example.json"]

cc_tracer-0.1.3/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

cc_tracer-0.1.3/src/cc_tracer/__init__.py

@@ -0,0 +1,3 @@
+"""cc-tracer — a local, infra-free inspector for a single Claude Code session."""
+
+__version__ = "0.1.3"

cc_tracer-0.1.3/src/cc_tracer/__main__.py

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

cc_tracer-0.1.3/src/cc_tracer/cli.py

@@ -0,0 +1,194 @@
+"""cc-tracer command-line interface.
+
+  start   install hooks (if needed), start a detached server, run Claude through it
+  stop    stop the server and remove its hooks
+
+(`_serve` is an internal, hidden command: the bare server process that `start`
+spawns detached. Use `start` instead.)
+"""
+
+import argparse
+import os
+import signal
+import socket
+import subprocess
+import sys
+import time
+from pathlib import Path
+
+from . import config, hooks as hooks_mod
+
+# Project-local by default so hooks only apply to Claude Code run in this project
+# (not every session on the machine). Override with --settings ~/.claude/settings.json.
+DEFAULT_SETTINGS = ".claude/settings.json"
+
+
+def _wait_port(port, timeout=10.0):
+    deadline = time.time() + timeout
+    while time.time() < deadline:
+        if _port_open(port):
+            return True
+        time.sleep(0.1)
+    return False
+
+
+def _port_open(port):
+    with socket.socket() as s:
+        s.settimeout(0.2)
+        try:
+            s.connect(("127.0.0.1", port))
+            return True
+        except OSError:
+            return False
+
+
+def _hook_url(port):
+    return f"http://127.0.0.1:{port}/event"
+
+
+def cmd_serve(a):
+    """Internal `_serve`: the bare server process (writes a pidfile so `stop`
+    can find it). Spawned detached by `start`; not meant to be run directly."""
+    if a.log_dir:
+        os.environ["TRACER_LOG_DIR"] = str(a.log_dir)
+    import uvicorn
+    from .server import app  # imported after env is set so LOG_DIR picks it up
+    pid_file = config.pid_file(a.port)
+    pid_file.parent.mkdir(parents=True, exist_ok=True)
+    pid_file.write_text(str(os.getpid()))
+    try:
+        uvicorn.run(app, host=a.host, port=a.port)
+    finally:
+        try:
+            pid_file.unlink()
+        except OSError:
+            pass
+    return 0
+
+
+def cmd_start(a):
+    base = f"http://127.0.0.1:{a.port}"
+    settings = Path(a.settings).expanduser()
+    log_dir = Path(a.log_dir) if a.log_dir else config.log_dir()
+    log_dir.mkdir(parents=True, exist_ok=True)
+
+    # 1. Ensure the tracer hooks are installed (idempotent).
+    added = hooks_mod.install(settings, _hook_url(a.port))
+    print(f"Hooks {'installed in' if added else 'already in'} {settings}")
+
+    # 2. Start a detached server (or reuse one already on the port). Detached +
+    #    own session so quitting Claude leaves the tracer running.
+    server = None
+    if _port_open(a.port):
+        print(f"Reusing tracer already running at {base}")
+    else:
+        env = os.environ.copy()
+        env["TRACER_LOG_DIR"] = str(log_dir)
+        server_log = open(log_dir / "server.log", "a")
+        server = subprocess.Popen(
+            [sys.executable, "-m", "cc_tracer", "_serve", "--host", "127.0.0.1", "--port", str(a.port)],
+            env=env, stdout=server_log, stderr=server_log, start_new_session=True,
+        )
+        if not _wait_port(a.port):
+            print(f"cc-tracer server failed to start; see {log_dir / 'server.log'}", file=sys.stderr)
+            server.terminate()
+            return 1
+        print(f"Started tracer at {base}  (log: {log_dir / 'server.log'})")
+
+    print(f"Tracer UI: {base}")
+    stop = "cc-tracer stop" + ("" if a.port == config.DEFAULT_PORT else f" --port {a.port}")
+
+    # 3. With --server-only, leave the detached server running and exit.
+    if a.server_only:
+        print(f"  point Claude at it:  export ANTHROPIC_BASE_URL={base}")
+        print(f"  stop it (and remove hooks) with:  {stop}")
+        return 0
+
+    # Otherwise run Claude Code routed through the tracer.
+    run_env = os.environ.copy()
+    run_env["ANTHROPIC_BASE_URL"] = base
+    claude_args = [x for x in a.claude_args if x != "--"]
+    try:
+        rc = subprocess.call(["claude", *claude_args], env=run_env)
+    except FileNotFoundError:
+        print("claude not found on PATH. The tracer is running; start Claude yourself "
+              f"with: export ANTHROPIC_BASE_URL={base}", file=sys.stderr)
+        rc = 127
+    except KeyboardInterrupt:
+        rc = 130
+
+    # Leave the server running after Claude exits; `stop` tears it down.
+    print(f"\nTracer still running at {base}")
+    print(f"  stop it (and remove hooks) with:  {stop}")
+    return rc
+
+
+def cmd_stop(a):
+    if a.log_dir:
+        os.environ["TRACER_LOG_DIR"] = str(a.log_dir)
+
+    # 1. Stop the server (via its pidfile), if one is running.
+    pid_file = config.pid_file(a.port)
+    if pid_file.exists():
+        try:
+            pid = int(pid_file.read_text().strip())
+        except ValueError:
+            print(f"Corrupt pidfile; removing {pid_file}")
+            pid_file.unlink()
+            pid = None
+        if pid is not None:
+            try:
+                os.kill(pid, signal.SIGTERM)
+                for _ in range(50):     # wait for shutdown to free the port
+                    if not _port_open(a.port):
+                        break
+                    time.sleep(0.1)
+                print(f"Stopped cc-tracer (pid {pid}) on port {a.port}.")
+            except ProcessLookupError:
+                print(f"Tracer (pid {pid}) wasn't running.")
+            try:
+                pid_file.unlink()
+            except OSError:
+                pass
+    else:
+        msg = f"No running tracer for port {a.port}."
+        if _port_open(a.port):
+            msg += f" (Something else is listening on {a.port}.)"
+        print(msg)
+
+    # 2. Remove the tracer hooks (only the entries pointing at our URL).
+    settings = Path(a.settings).expanduser()
+    url = _hook_url(a.port)
+    removed = hooks_mod.uninstall(settings, url)
+    print(f"{'Removed' if removed else 'No'} tracer hooks ({url}) in {settings}")
+    return 0
+
+
+def main(argv=None):
+    p = argparse.ArgumentParser(prog="cc-tracer", description="A local inspector for a single Claude Code session.")
+    sub = p.add_subparsers(dest="cmd", required=True)
+
+    s = sub.add_parser("start", help="install hooks, start a detached server, run Claude through it")
+    s.add_argument("--port", type=int, default=config.DEFAULT_PORT)
+    s.add_argument("--settings", default=DEFAULT_SETTINGS, help="settings.json for hooks (default: project-local .claude/settings.json)")
+    s.add_argument("--log-dir", type=Path, help="override $TRACER_LOG_DIR")
+    s.add_argument("--server-only", action="store_true",
+                   help="just start the server (don't launch Claude)")
+    s.add_argument("claude_args", nargs=argparse.REMAINDER, help="args passed through to `claude`")
+    s.set_defaults(func=cmd_start)
+
+    st = sub.add_parser("stop", help="stop the tracer server and remove its hooks")
+    st.add_argument("--port", type=int, default=config.DEFAULT_PORT)
+    st.add_argument("--settings", default=DEFAULT_SETTINGS, help="settings.json to remove hooks from (default: project-local)")
+    st.add_argument("--log-dir", type=Path, help="where start recorded its pidfile")
+    st.set_defaults(func=cmd_stop)
+
+    # Internal: the bare server process that `start` spawns detached.
+    sv = sub.add_parser("_serve", help=argparse.SUPPRESS)
+    sv.add_argument("--port", type=int, default=config.DEFAULT_PORT)
+    sv.add_argument("--host", default="127.0.0.1")
+    sv.add_argument("--log-dir", type=Path)
+    sv.set_defaults(func=cmd_serve)
+
+    a = p.parse_args(argv)
+    return a.func(a) or 0

cc_tracer-0.1.3/src/cc_tracer/config.py

@@ -0,0 +1,17 @@
+"""Shared configuration: where session JSONL lives, default port."""
+
+import os
+from pathlib import Path
+
+DEFAULT_PORT = 7355
+
+
+def log_dir() -> Path:
+    """Directory holding per-session JSONL. Override with $TRACER_LOG_DIR;
+    defaults to ~/.cc-tracer/logs so sessions land in one predictable place."""
+    return Path(os.environ.get("TRACER_LOG_DIR") or Path.home() / ".cc-tracer" / "logs")
+
+
+def pid_file(port: int) -> Path:
+    """Where `serve` records its PID so `stop` can find it (per port, in log_dir)."""
+    return log_dir() / f"cc-tracer-{port}.pid"

cc_tracer-0.1.3/src/cc_tracer/hooks.py

@@ -0,0 +1,70 @@
+"""Install / remove the tracer's HTTP hooks in a Claude Code settings.json."""
+
+import json
+import shutil
+from pathlib import Path
+
+# The Claude Code events we capture. The server records any event it receives,
+# so this list is purely which hooks we register.
+EVENTS = [
+    "SessionStart", "SessionEnd", "UserPromptSubmit",
+    "PreToolUse", "PostToolUse", "PostToolUseFailure",
+    "SubagentStart", "SubagentStop", "PreCompact", "PostCompact", "Stop",
+]
+
+
+def tracer_hooks(url):
+    """The hooks block that POSTs every captured event to `url`."""
+    return {ev: [{"hooks": [{"type": "http", "url": url}]}] for ev in EVENTS}
+
+
+def install(settings_path, url):
+    """Merge the tracer hooks into settings.json (idempotent). Backs the original
+    up to <name>.json.bak once. Returns True if anything was added."""
+    settings_path = Path(settings_path)
+    current = {}
+    if settings_path.exists():
+        current = json.loads(settings_path.read_text() or "{}")
+        bak = settings_path.with_suffix(".json.bak")
+        if not bak.exists():
+            shutil.copy(settings_path, bak)
+    settings_path.parent.mkdir(parents=True, exist_ok=True)
+
+    hooks = current.setdefault("hooks", {})
+    added = False
+    for event, entries in tracer_hooks(url).items():
+        bucket = hooks.setdefault(event, [])
+        serialized = json.dumps(bucket)
+        for entry in entries:
+            if json.dumps(entry) not in serialized:
+                bucket.append(entry)
+                added = True
+    settings_path.write_text(json.dumps(current, indent=2) + "\n")
+    return added
+
+
+def uninstall(settings_path, url):
+    """Remove only the HTTP hook entries pointing at `url`. Returns True if any
+    were removed. Leaves the user's other hooks untouched."""
+    settings_path = Path(settings_path)
+    if not settings_path.exists():
+        return False
+    current = json.loads(settings_path.read_text() or "{}")
+    hooks = current.get("hooks", {})
+    removed = False
+    for event in list(hooks):
+        kept_groups = []
+        for group in hooks[event]:
+            inner = [h for h in group.get("hooks", [])
+                     if not (h.get("type") == "http" and h.get("url") == url)]
+            if len(inner) != len(group.get("hooks", [])):
+                removed = True
+            if inner:
+                kept_groups.append({**group, "hooks": inner})
+        if kept_groups:
+            hooks[event] = kept_groups
+        else:
+            del hooks[event]
+    current["hooks"] = hooks
+    settings_path.write_text(json.dumps(current, indent=2) + "\n")
+    return removed