# disler/claude-code-hooks-mastery architecture

> Architecture diagram of the GitHub repository disler/claude-code-hooks-mastery, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/disler/claude-code-hooks-mastery
- Repository: https://github.com/disler/claude-code-hooks-mastery

## Overview

This repository is a Claude Code hooks and agent-orchestration demonstration. Its primary workflow is a Claude Code lifecycle event invoking a hook that can validate or enrich activity, provide feedback, and record event data. The README also describes subagents, team validation, status lines, and output styles. The tree includes a separate Bun task-manager CLI; its command-to-repository and repository-to-SQLite relationships are supported by the sampled source. Hook internals were not sampled, so their links reflect README documentation, not inspected implementations.

Main entry points: [`apps/task-manager/src/db/repository.ts`](https://github.com/disler/claude-code-hooks-mastery/blob/main/apps/task-manager/src/db/repository.ts) (Task repository), [`apps/task-manager/src/index.ts`](https://github.com/disler/claude-code-hooks-mastery/blob/main/apps/task-manager/src/index.ts) (CLI dispatcher), [`apps/task-manager/src/utils/formatter.ts`](https://github.com/disler/claude-code-hooks-mastery/blob/main/apps/task-manager/src/utils/formatter.ts) (CLI formatting), [`apps/task-manager/src/commands/add.ts`](https://github.com/disler/claude-code-hooks-mastery/blob/main/apps/task-manager/src/commands/add.ts) (Add task)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_hooks["Hook lifecycle"]
  node_hook_handlers["Lifecycle hooks<br/>[hooks]"]
  node_prompt_hook["Prompt control"]
  node_tool_hooks["Tool safeguards<br/>[pre_tool_use.py]"]
  node_post_tool["Post-tool processing<br/>[post_tool_use.py]"]
  node_logging["Event logging<br/>[hooks]"]
end

subgraph group_feedback["Feedback and context"]
  node_tts["Speech feedback<br/>[tts]"]
  node_llm["Completion messages<br/>[llm]"]
  node_context["Session context<br/>[session_start.py]"]
  node_status["Status lines<br/>[status_lines]"]
  node_styles["Output styles<br/>[output-styles]"]
end

subgraph group_agents["Agents and teams"]
  node_subagents["Research agents<br/>[agents]"]
  node_team["Builder validator<br/>[team]"]
end

subgraph group_cli["Task manager CLI"]
  node_task_cli["CLI dispatcher<br/>[index.ts]"]
  node_add["Add task<br/>[add.ts]"]
  node_list["List tasks<br/>[list.ts]"]
  node_complete["Complete task<br/>[complete.ts]"]
  node_delete["Delete task<br/>[delete.ts]"]
  node_stats["Task statistics<br/>[stats.ts]"]
  node_validation["Input validation<br/>[validation.ts]"]
  node_formatter["CLI formatting<br/>[formatter.ts]"]
end

subgraph group_storage["Task data"]
  node_repository["Task repository<br/>[repository.ts]"]
  node_database["Database setup<br/>[database.ts]"]
  node_migrations["Schema migrations<br/>[migrations.ts]"]
  node_sqlite[("SQLite task store")]
end

node_claude(("Claude Code"))

node_claude -->|"fires events"| node_hook_handlers
node_claude -->|"submits prompts"| node_prompt_hook
node_claude -->|"checks tools"| node_tool_hooks
node_claude -->|"reports tool result"| node_post_tool
node_hook_handlers -->|"logs events"| node_logging
node_prompt_hook -->|"enhances prompts"| node_claude
node_tool_hooks -->|"blocks unsafe access"| node_claude
node_post_tool -->|"extracts transcript"| node_claude
node_claude -->|"triggers speech"| node_tts
node_claude -->|"requests completion text"| node_llm
node_claude -->|"starts session"| node_context
node_claude -->|"shows status"| node_status
node_claude -->|"applies presentation"| node_styles
node_claude -->|"spawns agents"| node_subagents
node_team -->|"validates work"| node_claude
node_task_cli -->|"dispatches command"| node_add
node_task_cli -->|"dispatches command"| node_list
node_task_cli -->|"dispatches command"| node_complete
node_task_cli -->|"dispatches command"| node_delete
node_task_cli -->|"dispatches command"| node_stats
node_add -->|"validates input"| node_validation
node_add -->|"creates task"| node_repository
node_add -->|"formats output"| node_formatter
node_list -->|"fetches tasks"| node_repository
node_list -->|"formats output"| node_formatter
node_complete -->|"validates ID"| node_validation
node_complete -->|"updates task"| node_repository
node_complete -->|"formats output"| node_formatter
node_delete -->|"validates ID"| node_validation
node_delete -->|"deletes task"| node_repository
node_delete -->|"formats output"| node_formatter
node_stats -->|"gets statistics"| node_repository
node_stats -->|"formats output"| node_formatter
node_repository -->|"opens connection"| node_database
node_database -->|"runs schema"| node_migrations
node_repository -->|"reads and writes"| node_sqlite
node_database -->|"opens database"| node_sqlite

click node_hook_handlers "https://github.com/disler/claude-code-hooks-mastery/tree/main/.claude/hooks"
click node_prompt_hook "https://github.com/disler/claude-code-hooks-mastery/blob/main/.claude/hooks/user_prompt_submit.py"
click node_tool_hooks "https://github.com/disler/claude-code-hooks-mastery/blob/main/.claude/hooks/pre_tool_use.py"
click node_post_tool "https://github.com/disler/claude-code-hooks-mastery/blob/main/.claude/hooks/post_tool_use.py"
click node_logging "https://github.com/disler/claude-code-hooks-mastery/tree/main/.claude/hooks"
click node_tts "https://github.com/disler/claude-code-hooks-mastery/tree/main/.claude/hooks/utils/tts"
click node_llm "https://github.com/disler/claude-code-hooks-mastery/tree/main/.claude/hooks/utils/llm"
click node_context "https://github.com/disler/claude-code-hooks-mastery/blob/main/.claude/hooks/session_start.py"
click node_status "https://github.com/disler/claude-code-hooks-mastery/tree/main/.claude/status_lines"
click node_styles "https://github.com/disler/claude-code-hooks-mastery/tree/main/.claude/output-styles"
click node_subagents "https://github.com/disler/claude-code-hooks-mastery/tree/main/.claude/agents"
click node_team "https://github.com/disler/claude-code-hooks-mastery/tree/main/.claude/agents/team"
click node_task_cli "https://github.com/disler/claude-code-hooks-mastery/blob/main/apps/task-manager/src/index.ts"
click node_add "https://github.com/disler/claude-code-hooks-mastery/blob/main/apps/task-manager/src/commands/add.ts"
click node_list "https://github.com/disler/claude-code-hooks-mastery/blob/main/apps/task-manager/src/commands/list.ts"
click node_complete "https://github.com/disler/claude-code-hooks-mastery/blob/main/apps/task-manager/src/commands/complete.ts"
click node_delete "https://github.com/disler/claude-code-hooks-mastery/blob/main/apps/task-manager/src/commands/delete.ts"
click node_stats "https://github.com/disler/claude-code-hooks-mastery/blob/main/apps/task-manager/src/commands/stats.ts"
click node_validation "https://github.com/disler/claude-code-hooks-mastery/blob/main/apps/task-manager/src/utils/validation.ts"
click node_formatter "https://github.com/disler/claude-code-hooks-mastery/blob/main/apps/task-manager/src/utils/formatter.ts"
click node_repository "https://github.com/disler/claude-code-hooks-mastery/blob/main/apps/task-manager/src/db/repository.ts"
click node_database "https://github.com/disler/claude-code-hooks-mastery/blob/main/apps/task-manager/src/db/database.ts"
click node_migrations "https://github.com/disler/claude-code-hooks-mastery/blob/main/apps/task-manager/src/db/migrations.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_hook_handlers,node_prompt_hook,node_tool_hooks,node_post_tool,node_logging toneBlue
class node_tts,node_llm,node_context,node_status,node_styles toneAmber
class node_subagents,node_team toneMint
class node_task_cli,node_add,node_list,node_complete,node_delete,node_stats,node_validation,node_formatter toneRose
class node_repository,node_database,node_migrations,node_sqlite,node_claude toneIndigo
```

## Components

### Hook lifecycle

- [Lifecycle hooks](https://github.com/disler/claude-code-hooks-mastery/tree/main/.claude/hooks): `.claude/hooks`
- [Prompt control](https://github.com/disler/claude-code-hooks-mastery/blob/main/.claude/hooks/user_prompt_submit.py): `.claude/hooks/user_prompt_submit.py`
- [Tool safeguards](https://github.com/disler/claude-code-hooks-mastery/blob/main/.claude/hooks/pre_tool_use.py): `.claude/hooks/pre_tool_use.py`
- [Post-tool processing](https://github.com/disler/claude-code-hooks-mastery/blob/main/.claude/hooks/post_tool_use.py): `.claude/hooks/post_tool_use.py`
- [Event logging](https://github.com/disler/claude-code-hooks-mastery/tree/main/.claude/hooks): `.claude/hooks`

### Feedback and context

- [Speech feedback](https://github.com/disler/claude-code-hooks-mastery/tree/main/.claude/hooks/utils/tts): `.claude/hooks/utils/tts`
- [Completion messages](https://github.com/disler/claude-code-hooks-mastery/tree/main/.claude/hooks/utils/llm): `.claude/hooks/utils/llm`
- [Session context](https://github.com/disler/claude-code-hooks-mastery/blob/main/.claude/hooks/session_start.py): `.claude/hooks/session_start.py`
- [Status lines](https://github.com/disler/claude-code-hooks-mastery/tree/main/.claude/status_lines): `.claude/status_lines`
- [Output styles](https://github.com/disler/claude-code-hooks-mastery/tree/main/.claude/output-styles): `.claude/output-styles`

### Agents and teams

- [Research agents](https://github.com/disler/claude-code-hooks-mastery/tree/main/.claude/agents): `.claude/agents`
- [Builder validator](https://github.com/disler/claude-code-hooks-mastery/tree/main/.claude/agents/team): `.claude/agents/team`

### Task manager CLI

- [CLI dispatcher](https://github.com/disler/claude-code-hooks-mastery/blob/main/apps/task-manager/src/index.ts): `apps/task-manager/src/index.ts`
- [Add task](https://github.com/disler/claude-code-hooks-mastery/blob/main/apps/task-manager/src/commands/add.ts): `apps/task-manager/src/commands/add.ts`
- [List tasks](https://github.com/disler/claude-code-hooks-mastery/blob/main/apps/task-manager/src/commands/list.ts): `apps/task-manager/src/commands/list.ts`
- [Complete task](https://github.com/disler/claude-code-hooks-mastery/blob/main/apps/task-manager/src/commands/complete.ts): `apps/task-manager/src/commands/complete.ts`
- [Delete task](https://github.com/disler/claude-code-hooks-mastery/blob/main/apps/task-manager/src/commands/delete.ts): `apps/task-manager/src/commands/delete.ts`
- [Task statistics](https://github.com/disler/claude-code-hooks-mastery/blob/main/apps/task-manager/src/commands/stats.ts): `apps/task-manager/src/commands/stats.ts`
- [Input validation](https://github.com/disler/claude-code-hooks-mastery/blob/main/apps/task-manager/src/utils/validation.ts): `apps/task-manager/src/utils/validation.ts`
- [CLI formatting](https://github.com/disler/claude-code-hooks-mastery/blob/main/apps/task-manager/src/utils/formatter.ts): `apps/task-manager/src/utils/formatter.ts`

### Task data

- [Task repository](https://github.com/disler/claude-code-hooks-mastery/blob/main/apps/task-manager/src/db/repository.ts): `apps/task-manager/src/db/repository.ts`
- [Database setup](https://github.com/disler/claude-code-hooks-mastery/blob/main/apps/task-manager/src/db/database.ts): `apps/task-manager/src/db/database.ts`
- [Schema migrations](https://github.com/disler/claude-code-hooks-mastery/blob/main/apps/task-manager/src/db/migrations.ts): `apps/task-manager/src/db/migrations.ts`
- **SQLite task store**

### Other components

- **Claude Code**

## Connections

- Claude Code → Lifecycle hooks: fires events (evidence: `README.md`)
- Claude Code → Prompt control: submits prompts (evidence: `README.md`)
- Claude Code → Tool safeguards: checks tools (evidence: `README.md`)
- Claude Code → Post-tool processing: reports tool result (evidence: `README.md`)
- Lifecycle hooks → Event logging: logs events (evidence: `README.md`)
- Prompt control → Claude Code: enhances prompts (evidence: `README.md`)
- Tool safeguards → Claude Code: blocks unsafe access (evidence: `README.md`)
- Post-tool processing → Claude Code: extracts transcript (evidence: `README.md`)
- Claude Code → Speech feedback: triggers speech (evidence: `README.md`)
- Claude Code → Completion messages: requests completion text (evidence: `README.md`)
- Claude Code → Session context: starts session (evidence: `README.md`)
- Claude Code → Status lines: shows status (evidence: `README.md`)
- Claude Code → Output styles: applies presentation (evidence: `README.md`)
- Claude Code → Research agents: spawns agents (evidence: `README.md`)
- Builder validator → Claude Code: validates work (evidence: `README.md`)
- CLI dispatcher → Add task: dispatches command (evidence: `apps/task-manager/src/index.ts`)
- CLI dispatcher → List tasks: dispatches command (evidence: `apps/task-manager/src/index.ts`)
- CLI dispatcher → Complete task: dispatches command (evidence: `apps/task-manager/src/index.ts`)
- CLI dispatcher → Delete task: dispatches command (evidence: `apps/task-manager/src/index.ts`)
- CLI dispatcher → Task statistics: dispatches command (evidence: `apps/task-manager/src/index.ts`)
- Add task → Input validation: validates input (evidence: `apps/task-manager/src/commands/add.ts`)
- Add task → Task repository: creates task (evidence: `apps/task-manager/src/commands/add.ts`)
- Add task → CLI formatting: formats output (evidence: `apps/task-manager/src/commands/add.ts`)
- List tasks → Task repository: fetches tasks (evidence: `apps/task-manager/src/commands/list.ts`)
- List tasks → CLI formatting: formats output (evidence: `apps/task-manager/src/commands/list.ts`)
- Complete task → Input validation: validates ID (evidence: `apps/task-manager/src/commands/complete.ts`)
- Complete task → Task repository: updates task (evidence: `apps/task-manager/src/commands/complete.ts`)
- Complete task → CLI formatting: formats output (evidence: `apps/task-manager/src/commands/complete.ts`)
- Delete task → Input validation: validates ID (evidence: `apps/task-manager/src/commands/delete.ts`)
- Delete task → Task repository: deletes task (evidence: `apps/task-manager/src/commands/delete.ts`)
- Delete task → CLI formatting: formats output (evidence: `apps/task-manager/src/commands/delete.ts`)
- Task statistics → Task repository: gets statistics (evidence: `apps/task-manager/src/commands/stats.ts`)
- Task statistics → CLI formatting: formats output (evidence: `apps/task-manager/src/commands/stats.ts`)
- Task repository → Database setup: opens connection (evidence: `apps/task-manager/src/db/repository.ts`)
- Database setup → Schema migrations: runs schema (evidence: `apps/task-manager/src/db/database.ts`)
- Task repository → SQLite task store: reads and writes (evidence: `apps/task-manager/src/db/repository.ts`)
- Database setup → SQLite task store: opens database (evidence: `apps/task-manager/src/db/database.ts`)