harness-hooks 0.1.0__py3-none-any.whl

harness_hooks-0.1.0.dist-info/METADATA

@@ -0,0 +1,103 @@
+Metadata-Version: 2.5
+Name: harness-hooks
+Version: 0.1.0
+Summary: Installs the hooks that a config file lists into Claude Code and Codex, and removes them
+Project-URL: Homepage, https://github.com/a-pertsev/harness-hooks
+Author: Alexei Pertsev
+License-Expression: MIT
+License-File: LICENSE
+Keywords: claude-code,codex,hooks
+Classifier: Environment :: Console
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+# harness-hooks
+
+Installs the hooks that a config file lists into Claude Code and Codex, and removes them.
+Works on macOS and Linux.
+
+Run it with [uv](https://docs.astral.sh/uv/):
+
+```sh
+uvx harness-hooks install path/to/harness-hooks.json
+uvx harness-hooks remove path/to/harness-hooks.json
+```
+
+Or install it once, which puts `harness-hooks` on your `PATH`:
+
+```sh
+uv tool install harness-hooks
+```
+
+## Config
+
+```json
+{
+  "name": "notify",
+  "files": ["notify.py"],
+  "hooks": {
+    "Stop": [{"command": "python3 {dir}/notify.py {agent}", "timeout": 5}]
+  },
+  "claude": {
+    "Notification": [{"matcher": "idle_prompt", "command": "python3 {dir}/notify.py claude"}]
+  },
+  "codex": {
+    "PreToolUse": [{"matcher": "^request_user_input", "command": "python3 {dir}/notify.py codex"}]
+  }
+}
+```
+
+- `hooks` go to both agents, `claude` and `codex` only to that agent.
+- `{dir}` becomes the folder with the hooks' files, so hooks can call scripts there.
+  `{agent}` becomes `claude` or `codex`.
+- `matcher` and `command` mean what they mean in each agent's own hook files. Other
+  fields, such as `timeout`, are copied as they are.
+- `files`, if given, lists the files the hooks need, as paths inside the config's folder.
+
+## Copies
+
+With `files` in the config, `install` copies those files to `~/.claude/harness-hooks/<name>/`
+and `~/.codex/harness-hooks/<name>/`, and `{dir}` points there. The hooks keep working when
+the config's folder moves or is deleted. Run `install` again to bring in changed files;
+`remove` deletes the copies.
+
+Without `files`, or with `--editable`, `{dir}` is the config's folder, so an edit takes
+effect at once. `--editable` also deletes copies left by an earlier `install`. `--project`
+never copies.
+
+## Where hooks go
+
+By default into `~/.claude/settings.json` and `~/.codex/hooks.json`, so they run in every
+project. `CLAUDE_CONFIG_DIR` and `CODEX_HOME` move these files, as they do for the agents.
+
+With `--project`, into `.claude/settings.json` and `.codex/hooks.json` of the git repository
+that holds the config. Commit them, and everyone who clones the repository gets the hooks.
+`{dir}` is then found from the repository root, so the hooks work in any clone.
+Claude reads them only in sessions started at the repository root. Codex reads them only
+after you trust the project.
+
+`--agent claude` or `--agent codex` touches only that agent.
+
+## How it finds its hooks
+
+Each installed command ends with `# harness-hooks: <name>`. `install` replaces the commands
+with that mark and `remove` deletes them, so a hook dropped from the config disappears on
+the next run. Keep `name` the same once installed. It is also the copies' folder name, so it
+can't hold `/`. Hooks without the mark, such as ones you added by hand, are left alone, and
+the rest of each file is kept.
+
+Codex asks you to review new or changed hooks at its next start. It remembers approvals
+by a hook's place in the file, so removing hooks can make it ask again about the hooks
+after them.
+
+## Development
+
+From a clone, `uv tool install --editable .` runs the code in the clone, so an edit takes
+effect at once.
+
+```sh
+python3 -m unittest
+```

harness_hooks-0.1.0.dist-info/RECORD

@@ -0,0 +1,6 @@
+harness_hooks.py,sha256=JS9RzEswLu2KgrwRrgbMli2GeCMA_IHWwFren3zfOO8,6609
+harness_hooks-0.1.0.dist-info/METADATA,sha256=QgsDWbBpxm3MCzlM1druiYX2poCawouPFfr3G2jfhpY,3700
+harness_hooks-0.1.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+harness_hooks-0.1.0.dist-info/entry_points.txt,sha256=iLa8DhRb2ZMMLr-3ASdIPw6xXBJMma0Mj8k2KcqpFIo,53
+harness_hooks-0.1.0.dist-info/licenses/LICENSE,sha256=p8oUZNv5Fjrsv9qd4y8QH-fjOrvAX_kfR9Z_X6d4BNA,1071
+harness_hooks-0.1.0.dist-info/RECORD,,

harness_hooks-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any

harness_hooks-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+harness-hooks = harness_hooks:main

harness_hooks-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Alexei Pertsev
+
+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.

harness_hooks.py

@@ -0,0 +1,157 @@
+#!/usr/bin/env python3
+"""Installs the hooks that a config file lists into Claude Code and Codex, and removes them.
+
+Usage: harness-hooks install|remove CONFIG [--project] [--editable] [--agent claude|codex]
+"""
+
+import argparse
+import json
+import os
+from pathlib import Path
+import shlex
+import shutil
+import subprocess
+import sys
+import tempfile
+
+AGENTS = ("claude", "codex")
+PROJECT_FILES = {"claude": ".claude/settings.json", "codex": ".codex/hooks.json"}
+# Codex runs a hook in the folder the session started in, which can be below the project root.
+PROJECT_ROOT = '"$(git rev-parse --show-toplevel)"'
+
+
+def hook_file(agent, project):
+    if project:
+        return project / PROJECT_FILES[agent]
+    if agent == "claude":
+        return Path(os.environ.get("CLAUDE_CONFIG_DIR", Path.home() / ".claude")) / "settings.json"
+    return Path(os.environ.get("CODEX_HOME", Path.home() / ".codex")) / "hooks.json"
+
+
+def git_root(folder):
+    result = subprocess.run(["git", "-C", str(folder), "rev-parse", "--show-toplevel"], capture_output=True, text=True)
+    if result.returncode:
+        sys.exit(f"--project needs the config inside a git repository: {result.stderr.strip()}")
+    return Path(result.stdout.strip())
+
+
+def config_dir(folder, project):
+    if not project:
+        return shlex.quote(str(folder))
+    rel = folder.relative_to(project)
+    return PROJECT_ROOT + ("" if rel == Path() else "/" + shlex.quote(str(rel)))
+
+
+def build(config, agent, folder, tag):
+    events = {}
+    for block in (config.get("hooks", {}), config.get(agent, {})):
+        for event, entries in block.items():
+            for entry in entries:
+                handler = {"type": "command", **entry}
+                matcher = handler.pop("matcher", None)
+                handler["command"] = handler["command"].replace("{dir}", folder).replace("{agent}", agent) + tag
+                group = {} if matcher is None else {"matcher": matcher}
+                group["hooks"] = [handler]
+                events.setdefault(event, []).append(group)
+    return events
+
+
+def strip(hooks, tag):
+    kept = {}
+    for event, groups in hooks.items():
+        groups = [{**g, "hooks": [h for h in g["hooks"] if not h.get("command", "").endswith(tag)]} for g in groups]
+        groups = [g for g in groups if g["hooks"]]
+        if groups:
+            kept[event] = groups
+    return kept
+
+
+def write(path, text):
+    path.parent.mkdir(parents=True, exist_ok=True)
+    fd, tmp = tempfile.mkstemp(dir=path.parent, suffix=".tmp")
+    with os.fdopen(fd, "w") as f:
+        f.write(text)
+    if path.exists():
+        shutil.copymode(path, tmp)
+    os.replace(tmp, path)
+
+
+def copy(folder, files, target):
+    """Builds the copy aside and swaps it in, so a hook never runs from a half-copied folder."""
+    target.parent.mkdir(parents=True, exist_ok=True)
+    fresh = Path(tempfile.mkdtemp(dir=target.parent))
+    for name in files:
+        (fresh / name).parent.mkdir(parents=True, exist_ok=True)
+        shutil.copy2(folder / name, fresh / name)
+    old = fresh.with_suffix(".old")
+    if target.exists():
+        os.rename(target, old)
+    os.rename(fresh, target)
+    shutil.rmtree(old, ignore_errors=True)
+
+
+def update(path, tag, new):
+    """Replaces the hooks carrying the tag with the new ones; returns whether the file changed."""
+    # Writing through a symlink keeps a settings file that lives elsewhere, such as in dotfiles.
+    path = path.resolve()
+    data = json.loads(path.read_text()) if path.exists() else {}
+    old = data.get("hooks", {})
+    hooks = strip(old, tag)
+    for event, groups in new.items():
+        hooks.setdefault(event, []).extend(groups)
+    if hooks == old:
+        return False
+    if hooks:
+        data["hooks"] = hooks
+    else:
+        data.pop("hooks", None)
+    write(path, json.dumps(data, indent=2, ensure_ascii=False) + "\n")
+    return True
+
+
+def main():
+    parser = argparse.ArgumentParser(description="Installs the hooks a config file lists into Claude Code and Codex, and removes them.")
+    parser.add_argument("action", choices=["install", "remove"])
+    parser.add_argument("config", type=Path)
+    parser.add_argument("--project", action="store_true", help="use the hook files of the git repository that holds the config, for everyone who clones it")
+    parser.add_argument("--editable", action="store_true", help="run hooks from the config's folder instead of a copy of its files, so edits take effect at once")
+    parser.add_argument("--agent", choices=AGENTS, help="only this agent")
+    args = parser.parse_args()
+
+    path = args.config.resolve()
+    config = json.loads(path.read_text())
+    if "name" not in config or set(config) - {"name", "files", "hooks", *AGENTS}:
+        sys.exit(f"{path}: needs a name, and allows only files, hooks, claude and codex besides it")
+    name = config["name"]
+    # The name is also a folder that remove deletes, so it must not lead out of its parent.
+    if name in ("", ".", "..") or "/" in name:
+        sys.exit(f"{path}: name must be a plain folder name")
+    files = config.get("files", [])
+    if args.action == "install":
+        for file in files:
+            if Path(file).is_absolute() or ".." in Path(file).parts or not (path.parent / file).is_file():
+                sys.exit(f"{path}: {file} is not a file in {path.parent}")
+    project = git_root(path.parent) if args.project else None
+    copying = args.action == "install" and bool(files) and not args.editable and not project
+    # Marks every installed command, so remove finds it even after the config changed.
+    tag = f" # harness-hooks: {name}"
+    folder = config_dir(path.parent, project)
+    for agent in [args.agent] if args.agent else AGENTS:
+        target = hook_file(agent, project)
+        # Next to the agent's own settings, so the hooks keep working after the config's folder moves.
+        copy_dir = target.parent / "harness-hooks" / name
+        if copying:
+            copy(path.parent, files, copy_dir)
+            print(f"{agent}: copied {', '.join(files)} to {copy_dir}")
+        hooks = build(config, agent, shlex.quote(str(copy_dir)) if copying else folder, tag) if args.action == "install" else {}
+        changed = update(target, tag, hooks)
+        print(f"{agent}: {'updated' if changed else 'unchanged'} {target}")
+        if not copying and not project and copy_dir.exists():
+            shutil.rmtree(copy_dir)
+            print(f"{agent}: removed {copy_dir}")
+        if agent == "codex" and changed and hooks:
+            print("codex: asks you to review the new hooks at its next start")
+
+
+if __name__ == "__main__":
+    main()