Metadata-Version: 2.4
Name: claudehub-hooks
Version: 0.1.5
Summary: Claude Code hook dispatcher — forwards lifecycle events to Claude Monitor
Author-email: Pandiyaraj Karuppasamy <pandiyarajk@live.com>
License-Expression: MIT
Keywords: claude,claude-code,claudehub,hooks,monitor,dispatcher
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# claudehub-hooks

Pip-installable [Claude Code](https://docs.anthropic.com/en/docs/claude-code) hook dispatcher.
Install once, then wire any repository to a Claude Monitor HTTP
endpoint in one command — no manual script copying or JSON editing.

Events flow: **Claude Code → claudehub-hooks dispatcher → Claude Monitor**.

## Install

```bash
pip install claudehub-hooks
```

Requires Python 3.10+. No third-party runtime dependencies (stdlib only).

## Quick start

```bash
claudehub-hooks install
```

Run from a repository root (or pass `--repo`). The command is **idempotent** — safe to re-run.

```bash
claudehub-hooks install --repo /path/to/repo
claudehub-hooks install --url http://192.168.1.50:7070/event
claudehub-hooks install --python /usr/bin/python3   # interpreter the hooks run with
claudehub-hooks install --dry-run
```

### Install once for every repo

```bash
claudehub-hooks install --user
```

Writes the same files under `~/.claude` instead of a repo, so sessions in every
repo report to the monitor and no repo files change. The hook entries use the
absolute path of the interpreter that ran the command (override with
`--python`). A repo install keeps the portable `python`, because its
`settings.json` is usually committed. In a repo that registers its own
`claude_hook.py` (a repo install), the user-level copy stays silent and the
repo's copy reports, so each event still arrives once, with the repo's monitor
URL (0.1.5+).

### What it writes

| File | Purpose |
|------|---------|
| `.claude/hooks/claude_hook.py` | Hook dispatcher (invoked by Claude Code); replaced when the installed copy is outdated |
| `.claude/hooks/monitor_config.json` | Transport config with the monitor URL |
| `.claude/settings.json` | Hook entries merged in. Hooks already there for the same event are kept |

If `settings.json` exists but is not valid JSON, install stops without changing
anything, rather than overwriting the file.

## Uninstall

```bash
claudehub-hooks uninstall
```

Removes all claudehub hook entries from `.claude/settings.json` and deletes
`claude_hook.py` and `monitor_config.json`. Any hooks you added manually are
left untouched.

```bash
claudehub-hooks uninstall --repo /path/to/repo
claudehub-hooks uninstall --user      # undo install --user
claudehub-hooks uninstall --dry-run   # preview without changing anything
```

## Change the monitor URL

Edit `.claude/hooks/monitor_config.json` in the repo:

```json
{
  "transport": {
    "http": { "url": "http://192.168.1.50:7070/event" }
  }
}
```

Or set an environment variable (overrides the file):

```bash
export CLAUDE_HUB_URL="http://192.168.1.50:7070/event"
```

On Windows (persistent):

```bat
setx CLAUDE_HUB_URL "http://192.168.1.50:7070/event"
```

## Test connectivity

```bash
python .claude/hooks/claude_hook.py --test
```

## Hooks installed

| Event | Trigger |
|-------|---------|
| `SessionStart` | Claude session begins |
| `UserPromptSubmit` | User sends a message |
| `Notification` | Claude needs input |
| `PostToolUse` | File read/edited (Edit · Write · NotebookEdit · MultiEdit · Read) |
| `Stop` | Turn completes |
| `StopFailure` | API error |
| `PermissionRequest` | Allow/deny dialog shown |
| `PermissionGranted` | User approved a tool |
| `PermissionDenied` | User denied a tool |
| `PreToolUse` | Tool about to run (resolves permission) |

## Configuration

| Variable | Default | Meaning |
|----------|---------|---------|
| `CLAUDE_HUB_URL` | `http://127.0.0.1:7070/event` | Monitor endpoint |
| `CLAUDE_HUB_TIMEOUT` | `2.0` | HTTP timeout (seconds) |
| `CLAUDE_HUB_HTTP_ENABLED` | `true` | Set to `false` to silence all hooks |
| `CLAUDE_HOOK_LOG_LEVEL` | `INFO` | Dispatcher log level |
| `CLAUDE_HOOK_LOG_FILE` | `~/.claude/claude_hook.log` | Override log path |
| `CLAUDE_HUB_CONFIG` | — | Path to a `monitor_config.json` override |

## License

MIT — see [LICENSE](LICENSE).

**Author:** Pandiyaraj Karuppasamy · pandiyarajk@live.com
