@hasna/hooks 0.0.1

package/.npmrc.example

@@ -0,0 +1,2 @@
+@hasna:registry=https://registry.npmjs.org/
+//registry.npmjs.org/:_authToken=${NPM_TOKEN}

package/AGENTS.md

@@ -0,0 +1,54 @@
+# AGENTS.md
+
+Guidance for AI agents working with this repository.
+
+## Overview
+
+This is `@hasna/hooks`, an open-source monorepo of Claude Code hooks providing CLI installation and management of 15+ lifecycle hooks.
+
+## Quick Commands
+
+```bash
+bun install          # Install dependencies
+bun run dev          # Run CLI
+bun run build        # Build
+bun run typecheck    # Type check
+```
+
+## Adding Hooks
+
+1. Copy to `hooks/hook-{name}/`
+2. Ensure it follows the standard hook pattern (stdin JSON → stdout JSON)
+3. Remove any internal references (hasnaxyz, etc.)
+4. Verify no secrets or API keys are committed
+5. Update `src/lib/registry.ts` to include the hook
+
+## Structure
+
+```
+hooks/hook-{name}/
+├── src/
+│   ├── hook.ts      # Main hook logic
+│   ├── cli.ts       # CLI commands
+│   └── index.ts     # Exports
+├── package.json
+├── CLAUDE.md
+└── README.md
+```
+
+## Hook Events
+
+| Event | Timing | Can Block | Use Case |
+|-------|--------|-----------|----------|
+| PreToolUse | Before tool | Yes | Security, safety guards |
+| PostToolUse | After tool | No | Quality checks, async tasks |
+| Stop | Session end | No | Notifications, cleanup |
+| Notification | On notify | No | Context management |
+
+## Security Checks
+
+Before committing any hook:
+- [ ] No hardcoded API keys/tokens
+- [ ] No internal references (hasnaxyz)
+- [ ] Uses `@hasna` namespace for public packages
+- [ ] .env.example has placeholders only

package/CLAUDE.md

@@ -0,0 +1,70 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code when working with this repository.
+
+## Project Overview
+
+`@hasna/hooks` is an open-source monorepo of Claude Code hooks. It provides a CLI to install hooks into projects and register them in Claude settings.
+
+## Build & Run Commands
+
+```bash
+# Install dependencies
+bun install
+
+# Run CLI in development
+bun run dev
+
+# Build for distribution
+bun run build
+
+# Type check
+bun run typecheck
+```
+
+## Code Style
+
+- TypeScript with strict mode
+- ESM modules (`type: module`)
+- Async/await for all async operations
+- Minimal dependencies: commander, chalk, ink (for CLI)
+- Type annotations required everywhere
+
+## Project Structure
+
+```
+├── src/
+│   ├── cli/           # Interactive CLI (Ink/React)
+│   │   ├── components/
+│   │   └── index.tsx
+│   ├── lib/           # Core library
+│   │   ├── installer.ts
+│   │   └── registry.ts
+│   └── index.ts       # Library exports
+├── hooks/             # Individual hook packages
+│   └── hook-*/        # Each hook
+└── bin/               # Built CLI output
+```
+
+## Adding New Hooks
+
+When adding hooks:
+
+1. Copy to `hooks/hook-{name}/`
+2. Update `src/lib/registry.ts` to include the hook
+3. Ensure no secrets or API keys are committed
+4. Follow the standard hook structure (src/hook.ts, src/cli.ts)
+
+## Hook Events
+
+- **PreToolUse**: Fires before tool execution, can block
+- **PostToolUse**: Fires after tool execution, async
+- **Stop**: Fires on session end, async
+- **Notification**: Fires on notification events, async
+
+## Dependencies
+
+- commander: CLI argument parsing
+- chalk: Terminal styling
+- ink: React-based interactive CLI
+- ink-select-input: Selection component for Ink

package/CONTRIBUTING.md

@@ -0,0 +1,45 @@
+# Contributing
+
+Thanks for helping improve the hooks. Please follow these guidelines so we can keep publishing safe and consistent.
+
+## NPM Auth (Optional)
+
+If you need a scoped registry token (publish or private installs), copy an example file and set `NPM_TOKEN`:
+
+```bash
+cp .npmrc.example .npmrc
+```
+
+- Do not commit `.npmrc` files with real tokens.
+- Use environment variables in CI: `NPM_TOKEN` only.
+
+## Adding a New Hook
+
+1. Create the hook directory: `hooks/hook-{name}/`
+2. Follow the standard structure:
+   ```
+   hook-{name}/
+   ├── src/
+   │   ├── hook.ts     # Main hook logic
+   │   ├── cli.ts      # CLI commands
+   │   └── index.ts    # Exports
+   ├── package.json
+   ├── CLAUDE.md
+   ├── README.md
+   └── tsconfig.json
+   ```
+3. Register it in `src/lib/registry.ts`
+4. Test with `bun run dev`
+
+## Hook Conventions
+
+- Hooks receive JSON on stdin and output JSON on stdout
+- PreToolUse hooks return `{ "decision": "approve" | "block", "reason": "..." }`
+- PostToolUse/Stop/Notification hooks return `{ "continue": true }`
+- Log diagnostic info to stderr, not stdout
+- No external dependencies (use Node.js builtins only)
+
+## Secrets
+
+- Never commit `.env` files with real values.
+- Keep credentials in your local environment only.

package/README.md

@@ -0,0 +1,232 @@
+# Hooks
+
+Open source library of 15 Claude Code hooks. Install any hook with a single command.
+
+## Quick Start
+
+```bash
+# Interactive mode - browse and select hooks
+npx @hasna/hooks
+
+# Install specific hooks
+npx @hasna/hooks install gitguard branchprotect checkpoint
+
+# List all available hooks
+npx @hasna/hooks list
+```
+
+## Installation
+
+```bash
+# Global install
+bun install -g @hasna/hooks
+
+# Or use npx (no install needed)
+npx @hasna/hooks
+```
+
+## NPM Auth (Optional)
+
+If you need a scoped registry token (publish or private installs), copy an example file and set `NPM_TOKEN`:
+
+```bash
+cp .npmrc.example .npmrc
+```
+
+See `CONTRIBUTING.md` for publishing and secrets guidance.
+
+## Usage
+
+### Interactive Mode
+
+Run without arguments to browse hooks by category:
+
+```bash
+hooks
+```
+
+### Install Hooks
+
+```bash
+# Install one or more hooks
+hooks install gitguard branchprotect checkpoint
+
+# Hooks are installed to .hooks/ and registered in ~/.claude/settings.json
+```
+
+### Search
+
+```bash
+# Search by name, description, or tags
+hooks search security
+hooks search git
+```
+
+### List by Category
+
+```bash
+hooks list --category "Git Safety"
+hooks list --category "Code Quality"
+```
+
+### Hook Info
+
+```bash
+hooks info gitguard
+```
+
+### Check Registered Hooks
+
+```bash
+hooks list --registered
+```
+
+### Remove
+
+```bash
+hooks remove gitguard
+```
+
+## Available Hooks (15)
+
+### Git Safety (3)
+| Hook | Event | Description |
+|------|-------|-------------|
+| gitguard | PreToolUse | Blocks destructive git operations like reset --hard, push --force, clean -f |
+| branchprotect | PreToolUse | Prevents editing files directly on main/master branch |
+| checkpoint | PreToolUse | Creates shadow git snapshots before file modifications for easy rollback |
+
+### Code Quality (6)
+| Hook | Event | Description |
+|------|-------|-------------|
+| checktests | PostToolUse | Checks for missing tests after file edits |
+| checklint | PostToolUse | Runs linting after file edits and creates tasks for errors |
+| checkfiles | PostToolUse | Runs headless agent to review files and create tasks |
+| checkbugs | PostToolUse | Checks for bugs via Codex headless agent |
+| checkdocs | PostToolUse | Checks for missing documentation and creates tasks |
+| checktasks | PostToolUse | Validates task completion and tracks progress |
+
+### Security (2)
+| Hook | Event | Description |
+|------|-------|-------------|
+| checksecurity | PostToolUse | Runs security checks via Claude and Codex headless agents |
+| packageage | PreToolUse | Checks package age before install to prevent typosquatting |
+
+### Notifications (2)
+| Hook | Event | Description |
+|------|-------|-------------|
+| phonenotify | Stop | Sends push notifications to phone via ntfy.sh |
+| agentmessages | Stop | Inter-agent messaging integration for service-message |
+
+### Context Management (2)
+| Hook | Event | Description |
+|------|-------|-------------|
+| contextrefresh | Notification | Re-injects important context every N prompts to prevent drift |
+| precompact | Notification | Saves session state before context compaction |
+
+## How Hooks Work
+
+Claude Code hooks are lifecycle interceptors that run during agent sessions:
+
+- **PreToolUse**: Runs before a tool executes. Can **block** the operation.
+- **PostToolUse**: Runs after a tool executes. Async, non-blocking.
+- **Stop**: Runs when a session ends. Async, non-blocking.
+- **Notification**: Runs on notification events. Async, non-blocking.
+
+Each hook receives JSON on stdin and outputs JSON on stdout:
+
+```json
+// PreToolUse input
+{
+  "session_id": "abc123",
+  "cwd": "/path/to/project",
+  "tool_name": "Bash",
+  "tool_input": { "command": "git push --force" }
+}
+
+// PreToolUse output (block)
+{ "decision": "block", "reason": "Destructive git operation blocked" }
+
+// PreToolUse output (approve)
+{ "decision": "approve" }
+```
+
+## Hook Structure
+
+Each hook follows a consistent structure:
+
+```
+hook-{name}/
+├── src/
+│   ├── hook.ts     # Main hook logic (stdin → stdout)
+│   ├── cli.ts      # CLI for install/uninstall/status
+│   └── index.ts    # Library exports
+├── package.json
+├── CLAUDE.md
+├── README.md
+└── tsconfig.json
+```
+
+## Installing Individual Hooks
+
+You can also install hooks individually as npm packages:
+
+```bash
+bun install -g @hasna/hook-gitguard
+bun install -g @hasna/hook-branchprotect
+bun install -g @hasna/hook-checkpoint
+```
+
+Then use their built-in CLI:
+
+```bash
+hook-gitguard install    # Register in Claude settings
+hook-gitguard status     # Check if registered
+hook-gitguard uninstall  # Unregister
+```
+
+## Configuration
+
+Hooks are registered in `~/.claude/settings.json`:
+
+```json
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          { "type": "command", "command": "hook-gitguard" }
+        ]
+      }
+    ]
+  }
+}
+```
+
+## Development
+
+```bash
+# Install dependencies
+bun install
+
+# Run CLI in development
+bun run dev
+
+# Build
+bun run build
+
+# Type check
+bun run typecheck
+```
+
+## Contributing
+
+1. Fork the repository
+2. Create a new hook in `hooks/hook-{name}/`
+3. Follow the existing hook patterns
+4. Submit a pull request
+
+## License
+
+MIT