Documentation Index
Fetch the complete documentation index at: https://mintlify.com/ruvnet/ruflo/llms.txt
Use this file to discover all available pages before exploring further.
ruflo hooks is the command surface for Ruflo’s self-learning lifecycle system. Hooks fire before and after every tool use, session boundary, and task lifecycle event in Claude Code, feeding outcomes back into the ReasoningBank and SONA router. Over time the system learns which agents perform best for each task type, which file patterns carry risk, and which command sequences tend to fail — all without any manual tuning.
Synopsis
Subcommands
| Subcommand | Description |
|---|---|
pretrain | Bootstrap the ReasoningBank from existing codebase patterns |
list | List all registered hooks and their enabled/disabled state |
metrics | Show the learning metrics dashboard |
route | Route a task description to the optimal agent using learned patterns |
explain | Show transparent reasoning behind a routing decision |
pre-edit | Get context and agent suggestions before editing a file |
post-edit | Record an editing outcome to the learning pipeline |
pre-command | Assess risk before executing a shell command |
post-command | Record a command execution outcome |
pre-task | Record task start and request agent suggestions |
post-task | Record task completion for pattern learning |
session-end | End the current session and persist state |
session-restore | Restore a previous session snapshot |
task-completed | Signal task completion and optionally train patterns (Agent Teams) |
teammate-idle | Auto-assign pending tasks to an idle teammate (Agent Teams) |
model-route | Preview which LLM tier (Haiku/Sonnet/Opus) would handle a task |
model-outcome | Record a model routing outcome to update Beta priors |
model-stats | View Thompson sampling model routing statistics |
notify | Log a notification message to the session store |
worker | Manage background workers (12 available) |
build-agents | Generate optimized agent configurations from learned patterns |
intelligence | Manage the RuVector intelligence subsystem |
statusline | Generate the dynamic shell statusline display |
coverage-route | Route tasks based on test coverage gaps |
coverage-suggest | Suggest coverage improvements for a file |
coverage-gaps | List all coverage gaps with recommended agents |
token-optimize | Apply the agentic-flow token optimization pipeline |
Hook events
The following hooks are wired into Claude Code’ssettings.json by ruflo init:
| Hook name | Claude Code event | Purpose |
|---|---|---|
PreToolUse | Before any tool call | Risk assessment, agent context lookup |
PostToolUse | After successful tool call | Pattern learning from outcomes |
UserPromptSubmit | On prompt submission | Task routing via hooks_route |
SessionStart | Session initialization | Warm up ReasoningBank, restore state |
Stop | Task completion | Evaluation, quality scoring |
Notification | Claude Code notification | Log to session memory |
PermissionRequest | Tool permission prompt | Auto-allow Ruflo tools |
PreCompact | Before context compression | Save session snapshot |
tool:pre-call | Before MCP tool call | Logging and validation |
tool:post-call | After MCP tool call | Outcome recording |
.claude/helpers/hook-handler.cjs, which is written by ruflo init and ruflo init hooks.
pretrain
Scan the current repository and bootstrap the ReasoningBank with patterns extracted from existing code, tests, and documentation. This is the recommended step afterinit to give the routing system immediate context rather than starting from scratch.
hooks metrics will show a non-zero pattern count and the hooks route command will produce grounded recommendations.
list
Show all hooks registered in the current project along with their enabled/disabled state, last run time, and run count.metrics
Display the full learning metrics dashboard including pattern counts, routing accuracy, model routing statistics, and Flash Attention performance.Show the extended V3 dashboard with Flash Attention benchmarks, AgentDB integration metrics, and token reduction stats.
route
Ask the routing system which agent type should handle a given task, using learned patterns from the ReasoningBank.Natural language task description. Can also be passed as the first positional argument.
Additional context (e.g. file path, language, domain) to improve routing accuracy.
Number of alternative agent suggestions to return alongside the primary recommendation.
explain
Get a transparent, step-by-step explanation of how the routing system would decide on an agent for a given task.Task description.
Explain why (or why not) a specific agent type would be chosen.
Include the full list of matched patterns with examples.
pre-edit
Retrieve context — related files, learned patterns, potential risks, and agent suggestions — before editing a file.File path about to be edited.
Type of edit:
create, update, delete, or refactor.Free-text context about the intent of the edit.
post-edit
Record the outcome of a file edit. The result feeds back into the pattern learner and adjusts confidence scores for the patterns that were matched in the precedingpre-edit call.
File that was edited.
Whether the edit produced the desired outcome. Defaults to
true to match PostToolUse semantics.Description of what happened (e.g.
"Type error on line 42").Comma-separated key:value performance metrics (e.g.
"time:500ms,quality:0.95").pre-command
Assess the risk of a shell command before it executes. Returns a risk level (low/medium/high/critical), a list of identified risks, and safe alternative suggestions.
The shell command to analyze.
post-command
Record the outcome of a command execution to update command-pattern risk models.The command that was executed.
Whether the command exited successfully.
The numeric exit code.
Execution duration in milliseconds.
task-completed
Signal that a task is done, optionally train patterns from it, and notify the team lead (Agent Teams integration).ID of the completed task.
Train the neural pattern store from this task’s trajectory.
Notify the team lead agent of the completion.
Whether the task completed successfully.
Optional quality score between 0 and 1.
ID of the teammate that completed the task.
notify
Log a notification message to the session memory store at a given severity level.Notification text.
Severity:
info, warn, or error.Examples
The Thompson sampling model router (
model-route / model-outcome) uses cost-adjusted multi-armed bandit logic. After approximately 50 outcome events, the router self-corrects against tier overuse without any manual threshold tuning. Each route call costs ~45 µs.