hooks

hooks captures lifecycle events from local AI agent sessions and job execution tools. It serves as a connector between agent activities, the filesystem, and the grove ecosystem.

Core Mechanisms

Execution Model: Tools like Claude Code and OpenCode can be configured to execute the hooks binary at specific lifecycle events, passing JSON payloads via standard input. The process parses the event, updates the local SQLite database at ~/.local/state/grove/hooks/sessions.db, and exits.

Session Discovery: The tool aggregates session data from three sources:

• Active Processes: Scans filesystem PIDs and lock files to determine liveness for interactive agents.
• Grove flow Jobs: Scans workspace directories for Markdown files containing YAML frontmatter.
• OpenCode: Reads session history from ~/.local/share/opencode/storage/.

State Management: Session states (running, idle, completed, failed) are derived from process liveness checks (PID existence) and metadata updates. For flow jobs, status is determined by validating the existence of a corresponding .lock file and the active process it references.

Features

Terminal Interface (TUI)

The tui command renders a hierarchical view of active and historical sessions.

• Structure: Groups sessions by ecosystem, project, and worktree.
• Navigation: Supports filtering by status or type and provides shortcuts to attach to associated tmux sessions.
• Visual Indicators: Displays session age, status icons, and job types.

Repository Hooks

Projects can define custom lifecycle actions via the hooks section in grove.yml.

• On Stop: Executes shell commands when a session ends (e.g., linting, cleanup).
• Conditions: Commands can be conditional (e.g., run_if: changes checks for git modifications).

Plan Preservation

The tool automatically synchronizes plans generated by Claude Code's "Plan Mode" with flow's Plan.

• Capture: Listens for ExitPlanMode and Edit tool events.
• Sync: Extracts plan content and saves it as a flow compatible Markdown job file.
• Configuration: Controlled via grove.yml or environment variables (e.g., GROVE_HOOKS_ENABLE_PLAN_PRESERVATION).

Integrations

Claude Code

The install command configures Claude Code to call grove hooks commands at lifecycle events. It can install hooks in two locations:

• Local (default): Modifies .claude/settings.local.json in the target directory.
• Global: With --global flag, modifies ~/.claude/settings.json for system-wide hooks.

The install process is non-disruptive: it merges Grove hooks into existing configuration, preserving any custom hooks already defined. It registers the following events:

• PreToolUse: Runs before any tool execution
• PostToolUse: Runs after Edit, Write, MultiEdit, Bash, or Read tools
• Notification: Runs on Claude Code notifications
• Stop: Runs when the conversation stops
• SubagentStop: Runs when a subagent completes

OpenCode

The opencode install command writes a TypeScript plugin (grove-integration.ts) to ~/.config/opencode/plugin/. This plugin utilizes the OpenCode API to report lifecycle events to the hooks database.

System Notifications

The tool can send desktop notifications for specific events, such as when a background job pauses for user input or a long-running task completes. Configuration is handled via the central grove configuration.

See the documentation for detailed usage instructions:

• Overview
• Examples
• Configuration
• Command Reference