{"id":51007660,"url":"https://github.com/jason810496/agent-hooks","last_synced_at":"2026-06-20T22:02:36.891Z","repository":{"id":366161073,"uuid":"1203951015","full_name":"jason810496/agent-hooks","owner":"jason810496","description":"One local callback layer for Claude Code and Codex: a macOS-ready CLI for native permission dialogs and notifications, plus a FastAPI-like Python framework","archived":false,"fork":false,"pushed_at":"2026-06-20T15:13:53.000Z","size":1694,"stargazers_count":8,"open_issues_count":6,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-20T15:26:21.308Z","etag":null,"topics":["agent","claude-code","codex","hooks"],"latest_commit_sha":null,"homepage":"http://www.zhu424.dev/agent-hooks/latest/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jason810496.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","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-04-07T14:44:59.000Z","updated_at":"2026-06-20T14:43:11.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/jason810496/agent-hooks","commit_stats":null,"previous_names":["jason810496/agent-hooks"],"tags_count":4,"template":false,"template_full_name":null,"purl":"pkg:github/jason810496/agent-hooks","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jason810496%2Fagent-hooks","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jason810496%2Fagent-hooks/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jason810496%2Fagent-hooks/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jason810496%2Fagent-hooks/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jason810496","download_url":"https://codeload.github.com/jason810496/agent-hooks/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jason810496%2Fagent-hooks/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34586667,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-20T02:00:06.407Z","response_time":98,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"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":["agent","claude-code","codex","hooks"],"created_at":"2026-06-20T22:02:36.199Z","updated_at":"2026-06-20T22:02:36.885Z","avatar_url":"https://github.com/jason810496.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Agent Hooks\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"https://www.zhu424.dev/agent-hooks/latest/assets/agent-hooks-landing.svg\" alt=\"Agent Hooks landing graphic\" width=\"100%\"\u003e\n\u003c/p\u003e\n\n**No more swipe-and-sweep context switching for multi-session AI coding.**\n\nAgent Hooks gives Claude Code and Codex one local callback layer: a macOS-ready CLI for native permission dialogs and notifications, plus a FastAPI-like framework when you want to own the policy in Python.\n\n## Install\n\nUse the standalone CLI. See the [Built-in CLI](https://www.zhu424.dev/agent-hooks/latest/cli/builtin-callback/) docs for wiring it into your provider config.\n\n```bash\nuv tool install agent-hooks\n```\n\nOr install it inside a Python project:\n\n```bash\nuv pip install agent-hooks\n```\n\n## What It Looks Like\n\n### Claude Code\n\n![Claude Code permission request shown as a macOS dialog](https://www.zhu424.dev/agent-hooks/latest/assets/agent-hooks-claude-code-example.png)\n\nClaude Code permission requests become a native local dialog with `Deny`, `Allow Once`, and session-scoped `Always Allow`.\n\n### Codex\n\n![Codex permission request shown as a macOS dialog](https://www.zhu424.dev/agent-hooks/latest/assets/agent-hooks-codex-example.png)\n\nCodex `PreToolUse` requests become the same local dialog flow, with `Deny`, `Allow Once`, and optional `execpolicy` short-circuiting for already-allowed Bash commands.\n\n### `AgentHook` Framework\n\n```python\nfrom agent_hooks import AgentHook, PermissionRequestEvent, build_permission_response\nfrom agent_hooks.enums import DialogButton\n\napp = AgentHook()\n\n\n@app.permission()\ndef permission_handler(hook_event: PermissionRequestEvent):\n    if hook_event.tool_name == \"Bash\":\n        return build_permission_response(DialogButton.ALLOW_ONCE, hook_event)\n    return build_permission_response(DialogButton.DENY, hook_event)\n```\n\n```bash\nagent-hooks run my_hooks:app --provider codex\n```\n\nA single typed handler can serve Claude Code's `PermissionRequest` and Codex's `PreToolUse` without requiring provider-specific schema glue.\n\n## Why It Exists\n\nMulti-session AI coding tends to break flow in the same places:\n\n- permission prompts appear in separate sessions\n- provider payloads differ\n- local hook responses need provider-specific wire shapes\n- stop and notification events want OS-local behavior, not more terminal noise\n\nAgent Hooks normalizes those problems into one package.\n\n## Two Products In One Package\n\nUse `agent-hooks callback` when you want a working local callback target immediately.\n\nUse `AgentHook` when you need to define custom permission, notification, or stop behavior in Python.\n\n### Built-in CLI\n\nThe built-in app is exposed as `agent_hooks.cli_app.app:app` and can be run with:\n\n```bash\nagent-hooks callback\n```\n\nThis path is designed for local-first usage on macOS:\n\n- permission dialogs\n- notifications\n- provider-aware response rendering\n- rotating logs and audit logs\n\n### Framework\n\nThe framework is centered on `AgentHook`, a decorator-based router that looks and feels closer to FastAPI than to handwritten hook glue.\n\nYou register handlers with route decorators such as:\n\n- `@app.notification()`\n- `@app.permission()`\n- `@app.session_start()`\n- `@app.user_prompt_submit()`\n- `@app.post_tool_use()`\n- `@app.stop()`\n- `@app.stop_failure()`\n\n## Provider-Neutral Core\n\nInternally, incoming payloads are normalized into shared models before dispatch. That gives you one app-level programming model even when providers use different raw event names.\n\nExamples:\n\n- Claude `PermissionRequest` and Codex `PreToolUse` both route through `@app.permission()`\n- both providers share the same `HookPayload` base model\n- provider-specific response wire formats are handled by adapters\n\n## Start Here\n\nIf you want the fastest path, install the tool and wire the built-in callback into your provider config.\n\n### Claude Code\n\nInstall the CLI:\n\n```bash\nuv tool install agent-hooks\n```\n\nPut this in `~/.claude/settings.json`:\n\n```json\n{\n  \"hooks\": {\n    \"PermissionRequest\": [\n      {\n        \"hooks\": [\n          {\n            \"type\": \"command\",\n            \"command\": \"agent-hooks callback --provider claude-code\"\n          }\n        ]\n      }\n    ],\n    \"Notification\": [\n      {\n        \"matcher\": \"permission_prompt\",\n        \"hooks\": [\n          {\n            \"type\": \"command\",\n            \"command\": \"agent-hooks callback --provider claude-code\"\n          }\n        ]\n      }\n    ],\n    \"Stop\": [\n      {\n        \"hooks\": [\n          {\n            \"type\": \"command\",\n            \"command\": \"agent-hooks callback --provider claude-code\"\n          }\n        ]\n      }\n    ],\n    \"StopFailure\": [\n      {\n        \"hooks\": [\n          {\n            \"type\": \"command\",\n            \"command\": \"agent-hooks callback --provider claude-code\"\n          }\n        ]\n      }\n    ]\n  }\n}\n```\n\nThis is enough to route Claude Code permission, notification, and stop events into the built-in callback.\n\n### Codex\n\nInstall the CLI:\n\n```bash\nuv tool install agent-hooks\n```\n\nIf your Codex build still requires the feature flag, add this to `~/.codex/config.toml`:\n\n```toml\n[features]\ncodex_hooks = true\n```\n\nPut this in `~/.codex/hooks.json`:\n\n```json\n{\n  \"hooks\": {\n    \"PreToolUse\": [\n      {\n        \"matcher\": \"Bash\",\n        \"hooks\": [\n          {\n            \"type\": \"command\",\n            \"command\": \"agent-hooks callback --provider codex\",\n            \"timeout\": 30\n          }\n        ]\n      }\n    ],\n    \"Stop\": [\n      {\n        \"hooks\": [\n          {\n            \"type\": \"command\",\n            \"command\": \"agent-hooks callback --provider codex\",\n            \"timeout\": 30\n          }\n        ]\n      }\n    ]\n  }\n}\n```\n\nThis is enough to route Codex Bash permission checks and stop notifications into the built-in callback.\n\nRecommended setup: pass `--provider` explicitly in your provider config when you can. The built-in callback can infer providers from payload markers, but the explicit flag keeps local setup easier to reason about and debug.\n\nIf you want to build your own hook app, start with [`AgentHook`](https://www.zhu424.dev/agent-hooks/latest/framework/agenthook/) and then run it with [`agent-hooks run`](https://www.zhu424.dev/agent-hooks/latest/cli/custom-apps/).\n\n## Docs Map\n\n- [Features](https://www.zhu424.dev/agent-hooks/latest/features/)\n- [macOS Quickstart](https://www.zhu424.dev/agent-hooks/latest/getting-started/macos-quickstart/)\n- [Built-in Callback](https://www.zhu424.dev/agent-hooks/latest/cli/builtin-callback/)\n- [AgentHook](https://www.zhu424.dev/agent-hooks/latest/framework/agenthook/)\n- [Architecture Overview](https://www.zhu424.dev/agent-hooks/latest/architecture/overview/)\n- [Claude Code](https://www.zhu424.dev/agent-hooks/latest/providers/claude-code/)\n- [Codex](https://www.zhu424.dev/agent-hooks/latest/providers/codex/)\n\n## Maintainers\n\n- [Release Process](https://github.com/jason810496/agent-hooks/blob/main/scripts/release/README.md)\n\n## Scope\n\nAgent Hooks currently supports only two providers:\n\n- Claude Code\n- Codex\n\nThe docs stay aligned with the current implementation. They describe supported behavior that exists today, not placeholder integrations for future providers.\n\n## License\n\nAgent Hooks is licensed under Apache 2.0. See [LICENSE](https://github.com/jason810496/agent-hooks/blob/main/LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjason810496%2Fagent-hooks","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjason810496%2Fagent-hooks","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjason810496%2Fagent-hooks/lists"}