Hooks and Workers

Hooks and Workers

Ruflo's self-learning system is powered by 17 hooks and 12 background workers.

---

17 Hooks

Core Lifecycle

Hook	Fires	Input	Purpose
pre-task	Before task starts	description	Get routing recommendation, store task context
post-task	After task completes	task-id, success, quality	Record outcome, train patterns
pre-edit	Before file edit	file path	Get context, check AST for conflicts
post-edit	After edit completes	file path, success	Record edit, train neural patterns
pre-command	Before shell command	command	Risk assessment, safety check
post-command	After command finishes	command, exit-code	Record execution, update metrics

Session Management

Hook	Fires	Purpose
session-start	Session begins	Restore previous state, load patterns
session-end	Session ends	Persist state, trigger consolidation
session-restore	Restore requested	Load saved session (cross-session learning)
notify	Event notification	Broadcast to team (agents, humans)

Intelligence & Routing

Hook	Fires	Purpose
route	Task needs routing	Recommend agent type and model (Haiku/Sonnet/Opus)
explain	Routing requested	Explain why this agent was chosen
pretrain	Init or re-learning	Analyze codebase, build initial patterns
build-agents	Config generation	Create optimized agent configs from analysis
transfer	Pattern sharing	Transfer patterns to/from other projects (IPFS)

Learning Pipeline

Hook	Fires	Purpose
intelligence	Learning phase	Trajectory tracking, SONA adaptation, consolidation

---

12 Background Workers

Workers run independently in the daemon. Dispatch with:

npx ruflo@latest hooks worker dispatch --trigger <worker-name>

Core Workers

Worker	Priority	Purpose	Time
optimize	high	Performance bottleneck detection and optimization	30–120s
audit	critical	Security scanning (dependencies, CVEs, PII)	60–300s
consolidate	low	Memory maintenance, pattern cleanup	30–90s

Learning Workers

Worker	Priority	Purpose	Time
ultralearn	normal	Deep knowledge acquisition from codebase	60–300s
predict	normal	Predictive preloading and cache warmup	10–30s
refactor	normal	Suggest refactoring opportunities	30–120s

Analysis Workers

Worker	Priority	Purpose	Time
deepdive	normal	Deep code analysis and metrics	60–180s
map	normal	Update codebase structure map	30–90s
testgaps	normal	Find missing test coverage	60–180s

Utility Workers

Worker	Priority	Purpose	Time
document	normal	Auto-generate documentation	30–120s
benchmark	normal	Run performance benchmarks	60–600s
preload	low	Resource preloading for next task	5–15s

---

Hook Usage Examples

Record Task Completion

npx ruflo@latest hooks post-task \
  --task-id "task-123" \
  --success true \
  --quality 0.95 \
  --store-results true

This trains the neural router: next similar task will prefer the agent that succeeded here.

Route a Task

npx ruflo@latest hooks route \
  --task "Refactor authentication module across 3 files"

Output:

Recommended model: sonnet
Recommended agent: security-architect
Complexity: 0.78 (medium-high)
Confidence: 0.89
Reasoning: "Large refactor across multiple modules. Security-sensitive. Sonnet recommended over Haiku."

Start Intelligence Trajectory

npx ruflo@latest hooks intelligence trajectory-start \
  --task "Add OAuth2 flow"

# [agent works]

npx ruflo@latest hooks intelligence trajectory-step \
  --trajectory-id "traj-123" \
  --action "designed JWT architecture" \
  --quality 0.95

# [agent continues]

npx ruflo@latest hooks intelligence trajectory-end \
  --trajectory-id "traj-123" \
  --success true

Dispatch a Worker

# Run security audit
npx ruflo@latest hooks worker dispatch \
  --trigger audit \
  --priority critical

# Run optimization pass
npx ruflo@latest hooks worker dispatch \
  --trigger optimize \
  --context "src/auth/" \
  --priority high

# Check status
npx ruflo@latest hooks worker status

Transfer Patterns to Another Project

npx ruflo@latest hooks transfer \
  --source-path ../sibling-project \
  --min-confidence 0.80

Copies patterns from another project that:

• Have confidence score ≥ 0.80
• Are relevant to current codebase

---

Worker Dispatch Rules

Workers respect:

• Priority queuing: critical > high > normal > low
• Resource limits: Max 2 workers running simultaneously
• Timeout: 10 minutes per worker (configurable)
• Backoff: Exponential backoff on failure (up to 5 retries)

---

Automatic Hook Triggers

These hooks fire automatically (no manual invocation):

Trigger	Hook	When
Task completion	post-task	After every Task in Claude Code
File edit	post-edit	After every Edit/Write/MultiEdit
Session start	session-start	First turn of a new session
Session end	session-end	User ends session (explicitly or implicitly)

---

Hook Configuration

Configure which hooks are enabled:

npx ruflo@latest config set hooks.enabled.audit true
npx ruflo@latest config set hooks.enabled.testgaps false
npx ruflo@latest config list --prefix hooks

---

Worker Status

Check running workers:

npx ruflo@latest hooks worker list

Output:

Running Workers:
  - optimize (elapsed 45s, remaining 75s)
  - preload (elapsed 2s, remaining 13s)

Completed (last 24h):
  - audit (52 runs, 0 failures)
  - consolidate (24 runs, 0 failures)
  - testgaps (18 runs, 2 failures — retrying)

Failed (needs investigation):
  - benchmark (1 failure — GPU unavailable)

---

Learning Loop Integration

The complete learning cycle:

1. User starts task
   ↓
2. pre-task hook: get routing recommendation
   ↓
3. Agent spawned with recommended config
   ↓
4. Agent runs (memory search, action, decision)
   ↓
5. Agent completes
   ↓
6. post-task hook: record outcome, quality score
   ↓
7. Neural trainer: update LoRA weights (DISTILL)
   ↓
8. EWC++ consolidation: prevent forgetting (CONSOLIDATE)
   ↓
9. Background workers: analyze, optimize, test gaps
   ↓
10. Next task benefits from learned patterns

---

Performance Impact

Hook/Worker	Latency	When to disable
post-task	<50ms	Never (core learning)
post-edit	<20ms	High-frequency editing (toggle later)
audit worker	60–300s	Not in development
optimize worker	30–120s	Real-time constraint
testgaps worker	60–180s	Baseline testing phase
consolidate worker	30–90s	Can be disabled (nightly schedule exists)

---

Ruflo v3.10.1 · GitHub