{"id":47998747,"url":"https://github.com/ugudlado/hooksmith","last_synced_at":"2026-04-11T15:03:40.382Z","repository":{"id":346508496,"uuid":"1189963140","full_name":"ugudlado/hooksmith","owner":"ugudlado","description":"Declarative YAML hook rules compiled to native Claude Code hooks. Supports regex, script, and prompt mechanisms with build-time validation.","archived":false,"fork":false,"pushed_at":"2026-04-04T12:03:56.000Z","size":169,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-04T12:28:01.834Z","etag":null,"topics":["claude-code","configuration","hooks","plugin"],"latest_commit_sha":null,"homepage":"","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ugudlado.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-03-23T20:51:56.000Z","updated_at":"2026-04-04T12:04:00.000Z","dependencies_parsed_at":"2026-03-25T08:03:48.313Z","dependency_job_id":null,"html_url":"https://github.com/ugudlado/hooksmith","commit_stats":null,"previous_names":["ugudlado/hooksmith"],"tags_count":6,"template":false,"template_full_name":null,"purl":"pkg:github/ugudlado/hooksmith","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ugudlado%2Fhooksmith","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ugudlado%2Fhooksmith/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ugudlado%2Fhooksmith/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ugudlado%2Fhooksmith/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ugudlado","download_url":"https://codeload.github.com/ugudlado/hooksmith/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ugudlado%2Fhooksmith/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31684525,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-11T13:07:20.380Z","status":"ssl_error","status_checked_at":"2026-04-11T13:06:47.903Z","response_time":54,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["claude-code","configuration","hooks","plugin"],"created_at":"2026-04-04T12:09:58.861Z","updated_at":"2026-04-11T15:03:40.338Z","avatar_url":"https://github.com/ugudlado.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# hooksmith\n\nA Claude Code plugin that compiles declarative YAML rule files into native `hooks.json` entries. Define hook behavior as simple YAML rules — the plugin automatically rebuilds when rules change.\n\n## How It Works\n\n```\n~/.config/hooksmith/rules/*.yaml    →    hooksmith build    →    hooks.json\n```\n\nEach YAML rule becomes a native hook entry:\n\n| Mechanism | hooks.json type | Runtime behavior |\n|-----------|----------------|------------------|\n| `regex`   | `type: command` | Thin bash wrapper tests a field against a pattern |\n| `script`  | `type: command` | Your bash script runs directly |\n| `prompt`  | `type: prompt`  | LLM evaluates the prompt natively — zero script overhead |\n\n## Installation\n\n```bash\nclaude plugin add ugudlado/hooksmith\n```\n\nOr install locally:\n\n```bash\ngit clone https://github.com/ugudlado/hooksmith.git\nclaude --plugin-dir /path/to/hooksmith\n```\n\n## CLI\n\n```bash\nhooksmith list [--json] [--scope user|project|all]   # Show registered rules\nhooksmith run \u003cid\u003e                                    # Execute a rule by id\nhooksmith build                                       # Rebuild hooks.json from rules\nhooksmith start                                       # SessionStart: rebuild if rules changed\nhooksmith convert [--apply] [--scope user|project]   # Migrate settings.json hooks to YAML\n```\n\n## Getting Started\n\n### Migrating existing hooks\n\nIf you already have hooks in `settings.json`, convert them to YAML rules first:\n\n```bash\n# Preview what will be converted (dry-run)\nhooksmith convert\n\n# Write the YAML rule files\nhooksmith convert --apply\n\n# Build hooks.json and activate immediately\nhooksmith build\n/reload-plugins\n```\n\nThen remove the converted entries from `settings.json` — hooksmith owns them now.\n\n### Creating your first rule\n\n1. Create a rule file (filename must match `id`):\n\n```yaml\n# ~/.config/hooksmith/rules/block-rm.yaml\nid: block-rm\nevent: PreToolUse\nmatcher: Bash\nmechanism: regex\nfield: command\npattern: 'rm[[:space:]]+-rf[[:space:]]+(/|~|\\$HOME)'\nresult: deny\nmessage: \"Blocked: destructive rm targeting system or home directory.\"\n```\n\n2. Build and activate:\n\n```bash\nhooksmith build\n/reload-plugins\n```\n\n\u003e **Auto-build:** `hooksmith start` runs at each session start and rebuilds `hooks.json` only when rules have changed.\n\n## Rule Scopes\n\n- **User-level** (`~/.config/hooksmith/rules/`): Applies to all projects\n- **Project-level** (`.hooksmith/rules/`): Applies to that project only\n\nProject rules override user rules with the same filename.\n\n## Rule Format\n\nEvery rule requires an `id` field matching the filename (without `.yaml`):\n\n```yaml\nid: my-rule            # Required — must match filename my-rule.yaml\nevent: PreToolUse      # Hook event\nmatcher: Bash          # Tool filter (optional)\nmechanism: regex       # regex, script, or prompt\nfield: command         # Field to test (regex only)\npattern: 'dangerous'   # Regex pattern (regex only)\nresult: deny           # deny, ask, warn, or context\nmessage: \"Blocked.\"    # Output message (optional)\nfail_mode: open        # open (default) or closed\nenabled: true          # false to exclude from build\ntimeout: 10            # Seconds\n```\n\n### Mechanisms\n\n| Use `regex` when... | Use `script` when... | Use `prompt` when... |\n|---------------------|----------------------|----------------------|\n| Matching a pattern in a known field | Logic is complex or stateful | Condition requires judgment |\n| Zero overhead | You have an existing `.sh` script | Natural language evaluation |\n\n### Result types\n\n| Result | Effect |\n|--------|--------|\n| `deny` | Block the action |\n| `ask` | Prompt user for approval |\n| `warn` | Inject a warning into context |\n| `context` | Inject information into context |\n\n## Testing\n\n```bash\nbash tests/run-tests.sh\n```\n\nCovers CLI commands, deny/ask/allow behaviors across multiple hooks. Zero dependencies — pure bash.\n\n## Dependencies\n\n- `jq`\n- `bash` 3.2+\n\n## Examples\n\nSee `examples/` for sample rules covering all three mechanisms.\n\nAsk Claude to \"create a hook rule\" or \"add a regex rule\" — the `hooksmith` skill provides the full field reference, result-event compatibility table, and guided rule creation workflow.\n\n---\n\n## Related \u0026 References\n\n### Claude Code Hooks\n\n- [Hooks reference](https://code.claude.com/docs/en/hooks) — Full event list, JSON payload shapes, decision fields by event\n- [Automate workflows with hooks](https://code.claude.com/docs/en/hooks-guide) — Guide to hook patterns and use cases\n- [Plugins reference](https://code.claude.com/docs/en/plugins-reference) — Plugin structure, `hooks.json` loading, `/reload-plugins`\n\n### Hookify (Official Anthropic Plugin)\n\n- [Hookify](https://claude.com/plugins/hookify) — Official Anthropic hook management plugin\n- [Hookify on GitHub](https://github.com/anthropics/claude-plugins-official/tree/main/plugins/hookify)\n- [Writing Hookify rules](https://lobehub.com/skills/anthropics-claude-code-writing-rules)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fugudlado%2Fhooksmith","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fugudlado%2Fhooksmith","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fugudlado%2Fhooksmith/lists"}