{"id":50760507,"url":"https://github.com/ek33450505/cast-hooks","last_synced_at":"2026-06-11T09:30:53.994Z","repository":{"id":349625747,"uuid":"1200770440","full_name":"ek33450505/cast-hooks","owner":"ek33450505","description":"CAST hook scripts — lifecycle hooks for Claude Code sessions","archived":false,"fork":false,"pushed_at":"2026-06-05T23:18:14.000Z","size":175,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-06T01:12:36.152Z","etag":null,"topics":["agents","ai-agents","anthropic","bash","cast","claude-code","cli","developer-tools","hooks","observability","open-source","shell"],"latest_commit_sha":null,"homepage":null,"language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ek33450505.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","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-03T20:05:35.000Z","updated_at":"2026-06-05T23:18:17.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/ek33450505/cast-hooks","commit_stats":null,"previous_names":["ek33450505/cast-hooks"],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/ek33450505/cast-hooks","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ek33450505%2Fcast-hooks","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ek33450505%2Fcast-hooks/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ek33450505%2Fcast-hooks/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ek33450505%2Fcast-hooks/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ek33450505","download_url":"https://codeload.github.com/ek33450505/cast-hooks/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ek33450505%2Fcast-hooks/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34192870,"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-11T02:00:06.485Z","response_time":57,"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":["agents","ai-agents","anthropic","bash","cast","claude-code","cli","developer-tools","hooks","observability","open-source","shell"],"created_at":"2026-06-11T09:30:51.982Z","updated_at":"2026-06-11T09:30:53.988Z","avatar_url":"https://github.com/ek33450505.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# cast-hooks\n\n[![CI](https://github.com/ek33450505/cast-hooks/actions/workflows/ci.yml/badge.svg)](https://github.com/ek33450505/cast-hooks/actions/workflows/ci.yml)\n![version](https://img.shields.io/badge/version-0.2.0-blue)\n![license](https://img.shields.io/badge/license-MIT-green)\n![platform](https://img.shields.io/badge/platform-macOS%20%7C%20Linux-lightgrey)\n![hooks](https://img.shields.io/badge/hooks-13-purple)\n\n13 lifecycle hook scripts that add observability, safety guards, and agent dispatch directives to Claude Code — without the full CAST agent team. Install cast-hooks for session tracking, tool audit trails, git safety guards, compaction recovery, and structured event logging. Works standalone with any Claude Code setup.\n\n## What you get\n\nHook scripts are shell commands that Claude Code executes at specific lifecycle events — session start, tool use, agent dispatch, compaction, session end. They run automatically in the background, logging everything to `cast.db` (SQLite) and injecting directives like `[CAST-CHAIN]` and `[CAST-REVIEW]` into the conversation when conditions are met.\n\ncast-hooks gives you the hook layer without requiring the full CAST framework, its \u003c!-- CAST_AGENT_COUNT --\u003e23\u003c!-- /CAST_AGENT_COUNT --\u003e agents, or its orchestrator. Install the hooks, merge the settings, and Claude Code starts producing structured observability data immediately.\n\n## Install\n\n### Homebrew\n\n```bash\nbrew tap ek33450505/cast-hooks\nbrew install cast-hooks\ncast-hooks install\n```\n\n### Manual\n\n```bash\ngit clone https://github.com/ek33450505/cast-hooks.git\ncd cast-hooks\nbash install.sh\n```\n\n## Hooks\n\n| Hook ID | Event | Script | What it does |\n|---|---|---|---|\n| `cast-session-start` | SessionStart | `cast-session-start-hook.sh` | Initialize session, log to cast.db |\n| `cast-user-prompt` | UserPromptSubmit | `cast-user-prompt-hook.sh` | Prompt analytics and tracking |\n| `cast-post-tool` | PostToolUse | `post-tool-hook.sh` | CAST-CHAIN/CAST-REVIEW directives, ADM detection |\n| `cast-tool-failure` | PostToolUseFailure | `cast-tool-failure-hook.sh` | Error logging for failed tool calls |\n| `cast-instructions` | InstructionsLoaded | `cast-instructions-loaded-hook.sh` | Session context initialization |\n| `cast-audit` | PreToolUse (Write\\|Edit) | `cast-audit-hook.sh` | Audit trail for file changes |\n| `cast-git-guard` | PreToolUse (Bash) | `pre-tool-guard.sh` | Git safety — blocks force-push, destructive ops |\n| `cast-headless-guard` | PreToolUse (AskUserQuestion) | `cast-headless-guard.sh` | Blocks interactive prompts in headless/cron mode |\n| `cast-session-end` | SessionEnd | `cast-session-end.sh` | Session cleanup, DB finalize |\n| `cast-subagent-start` | SubagentStart | `cast-subagent-start-hook.sh` | Agent run logging (start) |\n| `cast-subagent-stop` | SubagentStop | `cast-subagent-stop-hook.sh` | Agent run logging (completion) |\n| `cast-pre-compact` | PreCompact | `cast-pre-compact-hook.sh` | Pre-compaction snapshot |\n| `cast-post-compact` | PostCompact | `cast-post-compact-hook.sh` | Post-compaction recovery |\n\n### Supporting scripts\n\n| Script | Purpose |\n|---|---|\n| `cast-events.sh` | Event-sourcing protocol (sourced by multiple hooks) |\n| `cast_db.py` | DB abstraction layer (WAL mode, swappable backend) |\n| `cast-db-log.py` | Routing event dual-writer |\n| `cast-agent-run-log.py` | Agent run logger |\n| `cast-log-append.py` | JSONL append helper |\n| `cast-db-init.sh` | DB schema initialization |\n\n## Usage\n\n### List all hooks\n\n```\n$ cast-hooks list\n\ncast-hooks v0.2.0 — Hook Registry\n════════════════════════════════════════════════════════════════════════════\n  Hook ID                  Event                  Script                  Timeout  Async\n  ──────────────────────────────────────────────────────────────────────────\n  cast-session-start       SessionStart           cast-session-start-ho   5        no\n  cast-user-prompt         UserPromptSubmit       cast-user-prompt-hook   5        no\n  cast-post-tool           PostToolUse            post-tool-hook.sh       10       yes\n  cast-tool-failure        PostToolUseFailure     cast-tool-failure-hoo   5        yes\n  ...\n\n13 hooks across 11 lifecycle events\n```\n\n### Check active status\n\n```\n$ cast-hooks status\n\ncast-hooks v0.2.0 — Active Status\n══════════════════════════════════════════════════════════════\n  Hook ID                  Event                  Status\n  ────────────────────────────────────────────────────────\n  cast-session-start       SessionStart           active\n  cast-user-prompt         UserPromptSubmit       active\n  cast-post-tool           PostToolUse            active\n  cast-git-guard           PreToolUse             inactive\n  ...\n\n  11 active, 2 inactive\n```\n\n### Install hooks\n\n```bash\ncast-hooks install\n```\n\nThis copies all 20 scripts (13 hooks + 7 supporting) to `~/.claude/scripts/`, initializes the cast.db schema, and merges hook entries into your `~/.claude/settings.json`.\n\n## How hooks work\n\nClaude Code v4 hooks fire at lifecycle events. Each hook receives context as JSON on stdin:\n\n```json\n{\n  \"session_id\": \"abc123\",\n  \"tool_name\": \"Bash\",\n  \"tool_input\": { \"command\": \"git push --force\" }\n}\n```\n\nThe hook script processes the event and responds:\n\n- **Exit 0** — success (async hooks always exit 0)\n- **Exit 2** — block the tool use (PreToolUse hooks only — used by `pre-tool-guard.sh` to block dangerous git commands)\n- **stdout JSON** — `hookSpecificOutput` to inject directives into the conversation\n\n## Configuration\n\nHooks are configured in `~/.claude/settings.json` under the `hooks` key. The template is at `config/settings.json` in this repo.\n\nTo enable or disable a specific hook, add or remove its entry from the appropriate lifecycle event in your settings file. Each hook entry has a unique `id` that `cast-hooks status` uses to detect whether it is active.\n\nTimeout tuning: increase `timeout` values if hooks time out on slow machines. The defaults (3-15 seconds) work on most systems.\n\n## Requirements\n\n- [Claude Code](https://claude.ai/claude-code) CLI\n- Bash 4+ (`brew install bash` on macOS)\n- Python 3.9+\n- SQLite3\n\n## Part of CAST\n\ncast-hooks ships as part of the [CAST framework](https://github.com/ek33450505/claude-agent-team). If you install CAST, you get the full hook layer automatically. This standalone repo is for Claude Code users who want just the hooks — observability, safety gates, and dispatch directives — without the full agent team.\n\n## CAST Ecosystem\n\n\u003e Auto-synced from [claude-agent-team/docs/ecosystem.md](https://github.com/ek33450505/claude-agent-team/blob/main/docs/ecosystem.md). Run `~/Projects/personal/claude-agent-team/scripts/sync-ecosystem-readme.sh` to refresh.\n\n\u003c!-- ECOSYSTEM_START --\u003e\n| Repo | Description | Latest | Install |\n|---|---|---|---|\n| [cast-hooks](https://github.com/ek33450505/cast-hooks) | 13 auditable hook scripts — observability, safety guards, quality gates. SessionStart, PreToolUse, PostToolUse, PostCompact. | ![](https://img.shields.io/github/v/release/ek33450505/cast-hooks?style=flat-square) | `brew tap ek33450505/cast-hooks \u0026\u0026 brew install cast-hooks` |\n| [cast-agents](https://github.com/ek33450505/cast-agents) | 23 specialist agents — commit, debug, review, plan, test, research, and more. Agent definitions with YAML frontmatter. v7-synced. | ![](https://img.shields.io/github/v/release/ek33450505/cast-agents?style=flat-square) | `brew tap ek33450505/cast-agents \u0026\u0026 brew install cast-agents` |\n| [cast-memory](https://github.com/ek33450505/cast-memory) | Persistent agent memory with FTS5 search, relevance scoring, shared pool, semantic embeddings. Per-agent knowledge accumulation. | ![](https://img.shields.io/github/v/release/ek33450505/cast-memory?style=flat-square) | `brew tap ek33450505/cast-memory \u0026\u0026 brew install cast-memory` |\n| [cast-routines](https://github.com/ek33450505/cast-routines) | Scheduled autonomous Claude Code routines via YAML + cron. Daily briefings, inbox triage, release celebration, weekly cost reports. | ![](https://img.shields.io/github/v/release/ek33450505/cast-routines?style=flat-square) | `brew tap ek33450505/cast-routines \u0026\u0026 brew install cast-routines` |\n| [cast-parallel](https://github.com/ek33450505/cast-parallel) | Parallel agent execution across worktree sessions. Agent Dispatch Manifest (ADM) support. | ![](https://img.shields.io/github/v/release/ek33450505/cast-parallel?style=flat-square) | `brew tap ek33450505/cast-parallel \u0026\u0026 brew install cast-parallel` |\n| [cast-observe](https://github.com/ek33450505/cast-observe) | Session-level observability — cost tracking, agent run history, token spend, event sourcing. Feeds cast.db. | ![](https://img.shields.io/github/v/release/ek33450505/cast-observe?style=flat-square) | `brew tap ek33450505/cast-observe \u0026\u0026 brew install cast-observe` |\n| [cast-security](https://github.com/ek33450505/cast-security) | Security hooks and audit trails. PII redaction, parry-guard integration, compliance logging. | ![](https://img.shields.io/github/v/release/ek33450505/cast-security?style=flat-square) | `brew tap ek33450505/cast-security \u0026\u0026 brew install cast-security` |\n| [cast-doctor](https://github.com/ek33450505/cast-doctor) | Read-only health check for any Claude Code install. Validates hooks, MCP servers, agent frontmatter, cast.db schema, stale memories. | ![](https://img.shields.io/github/v/release/ek33450505/cast-doctor?style=flat-square) | `brew tap ek33450505/cast-doctor \u0026\u0026 brew install cast-doctor` |\n| [cast-time](https://github.com/ek33450505/cast-time) | Gives Claude Code a clock — injects local time, timezone, and a semantic time-of-day bucket at every SessionStart. | ![](https://img.shields.io/github/v/release/ek33450505/cast-time?style=flat-square) | `brew tap ek33450505/cast-time \u0026\u0026 brew install cast-time` |\n| [cast-dash](https://github.com/ek33450505/cast-dash) | Terminal UI dashboard for live swarm monitoring. 4-panel real-time display (Textual framework). | ![](https://img.shields.io/github/v/release/ek33450505/cast-dash?style=flat-square) | `brew tap ek33450505/cast-dash \u0026\u0026 brew install cast-dash` |\n| [cast-claudes_journal](https://github.com/ek33450505/cast-claudes_journal) | Session continuity — Claude's Journal auto-injects prior-day context via SessionStart hook. Obsidian vault sync. | ![](https://img.shields.io/github/v/release/ek33450505/cast-claudes_journal?style=flat-square) | `brew tap ek33450505/homebrew-claudes-journal \u0026\u0026 brew install claudes-journal` |\n| [cast-website](https://github.com/ek33450505/cast-website) | castframework.dev — marketing site and docs portal for the CAST ecosystem. | ![](https://img.shields.io/github/v/release/ek33450505/cast-website?style=flat-square) | — |\n| [cast-desktop](https://github.com/ek33450505/cast-desktop) | Tauri 2 native app — embedded PTY terminal, command palette, 11 dashboard views. NEW. | ![](https://img.shields.io/github/v/release/ek33450505/cast-desktop?style=flat-square) | `brew tap ek33450505/homebrew-cast-desktop \u0026\u0026 brew install cast-desktop` |\n\u003c!-- ECOSYSTEM_END --\u003e\n\n## License\n\nMIT — see [LICENSE](LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fek33450505%2Fcast-hooks","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fek33450505%2Fcast-hooks","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fek33450505%2Fcast-hooks/lists"}