Ruflo Lifecycle Hooks, Workers, and the Learning Loop

Hooks are the reason you don’t need to learn 313 MCP tools or manually coordinate agents. After npx ruflo init, you just use Claude Code normally. The hooks system intercepts task boundaries, session events, and tool calls — automatically routing work, capturing successful patterns, and triggering background workers — all without requiring any explicit invocation on your part. The 27 hooks that ship with Ruflo cover the full lifecycle of a Claude Code session: from the moment a session starts, through every edit, command, and tool call, to final consolidation when the session ends.

Hooks are installed automatically by npx ruflo init. The .claude/settings.json file controls which hooks are active. Manual setup is only needed if you’re writing custom hooks or selectively disabling built-in ones.

Hook Categories

Task Hooks

Fire at the boundaries of individual tasks — the most important hooks for the learning loop:

Hook	When It Fires	What It Does
`pre-task`	Before any task begins	Searches memory for relevant past patterns; injects context into the agent
`post-task`	After a task completes	Captures the outcome; stores successful patterns to memory
`task-completed`	When a task is explicitly marked done	Triggers pattern training; notifies the team lead in multi-agent mode

Model Routing Hooks

Power the intelligent 3-tier model router:

Hook	When It Fires	What It Does
`hooks_route`	Before any tool call that needs a model	Samples Beta(α, β) priors per tier; picks the cheapest tier that meets quality requirements
`hooks_model-outcome`	After a model call returns	Updates the Beta prior for the chosen tier based on success/failure
`hooks_model-route`	During routing decision	Logs the routing decision and emits `[TASK_MODEL_RECOMMENDATION]` or `[AGENT_BOOSTER_AVAILABLE]` signals

After roughly 50 outcomes the Thompson sampling distribution self-corrects against tier overuse — no manual threshold tuning needed.

Session Hooks

Manage session-level context and state:

Hook	When It Fires	What It Does
`SessionStart`	At the beginning of a Claude Code session	Loads persisted memory; warms the agent pool; restores prior session context
`session-end`	When the session closes	Flushes memory; runs final consolidation; saves the RVF snapshot
`PreCompact`	Before context compaction	Distils the current context window into memory to survive the compaction
`UserPromptSubmit`	When the user submits a prompt	Runs the routing pre-check; injects relevant memory context

Tool Hooks

Intercept MCP tool calls:

Hook	When It Fires	What It Does
`tool:pre-call`	Before any MCP tool executes	Validates the call against the security layer; logs to the audit trail
`tool:post-call`	After an MCP tool returns	Captures tool output patterns; updates performance metrics

Teammate Hooks

Coordinate Claude Code’s experimental multi-agent teams feature:

Hook	When It Fires	What It Does
`hooks/teammate-idle`	A teammate finishes its turn	Auto-assigns the next pending task from the shared task list
`hooks/teammate-*`	Various teammate lifecycle events	Manages mailbox, inter-agent messaging, and shutdown coordination

12 Background Workers

Beyond the event-driven hooks, Ruflo runs 12 background workers on a schedule or triggered by context signals. Workers run automatically — you can also dispatch them manually:

Worker	Auto-Triggers On	Purpose
`ultralearn`	New project, major refactor	Deep knowledge acquisition sweep across the codebase
`audit`	Security-related file changes	Vulnerability scanning and CVE triage
`optimize`	Slow operations detected	Performance suggestions and routing optimisation
`consolidate`	Session end, memory threshold	Memory deduplication, tier promotion, pruning
`map`	New directories, large file changes	Codebase structure mapping
`deepdive`	Complex file edits	Deep code analysis and context extraction
`document`	New functions or classes	Auto-documentation generation
`refactor`	Code smell patterns	Refactoring detection and suggestions
`benchmark`	Performance-critical changes	Latency and throughput benchmarks
`testgaps`	Code changes without tests	Test coverage gap detection
`predict`	Similar task seen before	Preloads likely resources based on pattern match
`preload`	Cache miss on frequently accessed patterns	Resource preloading to warm the cache

# Manually dispatch a worker
npx ruflo@latest worker dispatch --trigger audit --context "./src"

# Check worker status
npx ruflo@latest worker status

How Hooks Power the Learning Loop

The hooks system is the mechanism through which Ruflo gets smarter over time:

pre-task fires

memory_search retrieves patterns from past sessions that match the current task. The agent starts with prior context rather than from scratch.

Task executes

The agent works. The hooks_route and hooks_model-route hooks manage model tier selection in real time, updating priors with each outcome.

post-task fires

If the task succeeded, the pattern is stored to memory with its embedding, tags, and quality score. The post-task hook also triggers the neural_train sweep if enough new patterns have accumulated.

Learning propagates

The stored patterns flow into ReasoningBank and PatternLearner. Next time a similar task arrives, pre-task retrieves a higher-quality match and the routing decision is better informed.

CLI Commands for Hooks

# Bootstrap learning from an existing codebase (run once on a new project)
npx ruflo@latest hooks pretrain

# Manually fire the task-completed hook (useful in CI pipelines)
npx ruflo@latest hooks task-completed --task-id <id> --train-patterns

# List all registered hooks and their current state
npx ruflo@latest hooks list

Additional hooks subcommands:

npx ruflo@latest hooks list      # show all hooks with descriptions
npx ruflo@latest hooks status    # show which hooks are currently active
npx ruflo@latest hooks enable    # enable a specific hook by name
npx ruflo@latest hooks disable   # disable a specific hook by name

MCP Hook Tools

The 33 MCP hook tools mirror the CLI surface, callable from Claude Code or any MCP client:

Tool Group	Tools	Description
`hooks/pre-*`	`hooks/pre-edit`, `hooks/pre-command`, etc.	Fire before write operations
`hooks/post-*`	`hooks/post-edit`, `hooks/post-command`, etc.	Fire after write operations; capture outcomes
`hooks/route`	`hooks_route`, `hooks_model-route`, `hooks_model-outcome`	Model routing and outcome feedback
`hooks/session-*`	`hooks_session-start`, `hooks_session-end`, etc.	Session lifecycle management
`hooks/task-*`	`hooks_task-completed`, `hooks_pretrain`, etc.	Task boundary hooks and training triggers
`hooks/teammate-*`	`hooks_teammate-idle`, etc.	Multi-agent team coordination

Configuration

Hooks are controlled by .claude/settings.json in your project root. This file is created by npx ruflo init and contains the full hook registry:

{
  "hooks": {
    "pre-task": { "enabled": true },
    "post-task": { "enabled": true },
    "SessionStart": { "enabled": true },
    "session-end": { "enabled": true },
    "PreCompact": { "enabled": true },
    "UserPromptSubmit": { "enabled": true },
    "hooks_route": { "enabled": true },
    "hooks_model-outcome": { "enabled": true }
  },
  "workers": {
    "ultralearn": { "enabled": true },
    "audit": { "enabled": true },
    "testgaps": { "enabled": true }
  }
}

To disable a hook project-wide without removing it:

npx ruflo@latest hooks disable --name post-task

To write a custom hook, create a handler in .claude/hooks/ following the plugin hook API and register it in settings.json. Custom hooks receive the same event payload as built-in hooks and can call any MCP tool.

Get Started

Core Concepts

Guides

Configuration

Ruflo Lifecycle Hooks, Workers, and the Learning Loop

Hook Categories

Task Hooks

Model Routing Hooks

Session Hooks

Tool Hooks

Teammate Hooks

12 Background Workers

How Hooks Power the Learning Loop

CLI Commands for Hooks

MCP Hook Tools

Configuration

Build docs developers (and LLMs) love

Get Started

Core Concepts

Guides

Configuration

Documentation Index

​Hook Categories

​Task Hooks

​Model Routing Hooks

​Session Hooks

​Tool Hooks

​Teammate Hooks

​12 Background Workers

​How Hooks Power the Learning Loop

​CLI Commands for Hooks

​MCP Hook Tools

​Configuration

Build docs developers (and LLMs) love

Hook Categories

Task Hooks

Model Routing Hooks

Session Hooks

Tool Hooks

Teammate Hooks

12 Background Workers

How Hooks Power the Learning Loop

CLI Commands for Hooks

MCP Hook Tools

Configuration