# Hooks Reference

This repository uses `hook` in two different ways:

1. runtime/agent hook ingestion commands
2. browser-side React hooks under `flow/web/src/hooks/`

## Runtime Hook Commands

Main implementation:

- `flow/runtime/src/commands/hooks.ts`

Current CLI-facing hook surfaces:

- `hooks ingest`
- `hooks notify`
- `hooks gemini-hook`
- `hooks codex-hook`
- `hooks codex-wrapper`

Related docs:

- [CLI reference](cli.md)
- [Runtime API reference](runtime-api.md)

## Runtime Hook Event Adapters

- Codex hook event mapping: `flow/runtime/src/commands/hook-events/codex-hook-events.ts`
- Kiro hook normalization: `flow/runtime/src/commands/hook-events/kiro-hook-events.ts`
- Droid review metadata enrichment: `flow/runtime/src/commands/hook-events/droid-hook-events.ts`
- Hook runtime context: `flow/runtime/src/terminal/hook-runtime-context.ts`

The runtime normalizes metadata such as source, tool name, hook event name, notification type,
final message, and activity text before sending it to `trpcClient.hooks.ingest`.

## Runtime Hook Event Purposes

- `activity`: report ongoing work or tool usage
- `to_in_progress`: mark a task/session as active
- `to_review`: move the task toward review-ready state

## React Hooks Index

Main folder:

- `flow/web/src/hooks/`

Important groups:

- App/shell: `use-app-hotkeys`, `use-debug-tools`, `use-detail-task-navigation`,
  `use-document-visibility`, `use-is-mobile`, `use-project-navigation`, `use-project-ui-state`,
  `use-workspace-sync`
- Board/task lifecycle: `use-board-interactions`, `use-task-editor`, `use-task-sessions`,
  `use-task-start-actions`, `use-linked-backlog-task-actions`, `use-programmatic-card-moves`,
  `use-review-auto-actions`, `use-review-ready-notifications`, `use-task-branch-options`
- Cline/chat/session UI: `use-cline-chat-panel-controller`, `use-cline-chat-runtime-actions`,
  `use-cline-chat-session`, `use-home-agent-session`, `use-home-sidebar-agent-panel`
- Git/shortcuts/runtime settings: `use-git-actions`, `use-shortcut-actions`,
  `use-runtime-settings-cline-controller`, `use-runtime-settings-cline-mcp-controller`
- UI/platform helpers: `use-featurebase-feedback-widget`, `use-open-workspace`,
  `use-startup-onboarding`, `use-terminal-panels`, `use-theme`, `use-update-notification`,
  `use-kanban-access-gate`

## Research-Related UI Hooks

Outside `flow/web/src/hooks/`, the Research plugin also uses hook-style modules under:

- `flow/web/src/research/use-deep-research-runtime-actions.ts`
- `flow/web/src/components/plugins/use-matrix-research-session-list.ts`
- `flow/web/src/components/plugins/use-android-research-runtime.ts`

For the actual current file list, inspect `flow/web/src/hooks/` directly.
