Attention Saver: The Jester Protocol

Use the keyword extractor in scripts/keyword_extractor.py to process prompts. It handles stopword removal, tech term recognition (100+ terms), file extension mapping, and command detection.

2. Tip Selection

Two tiers of content:

Tier 1 — Template Database (instant, preferred): Read references/tip_database.json for the full template collection. Each template has:

• Trigger keywords and keyword categories for matching
• {keyword} slots that get filled with context-matched terms
• Whimsy scores (prefer higher absurdity)
• Nerd level filtering (0 = everyone, 1 = dev, 2 = deep nerd)

Match tips using: direct keyword match (3x weight) + category match (1x weight), then pick from the top 5 via weighted random selection (not always the "best" match — variety matters).

Tier 2 — Generated (fallback, when templates miss): Use the Jester System Prompt from references/jester_prompt.md to generate a tip on-the-fly via a fast model (Haiku). Max 280 characters, surreal tone, contextually linked to keywords.

3. Cadence Control

• Initial delay: 8 seconds (don't interrupt natural engagement)
• Tip cycle: Every 15-25 seconds (randomized to avoid predictability)
• Max tips per task: 20 (prevent annoyance on very long tasks)
• Minimum task duration: 10 seconds (don't activate for quick commands)

4. Display Format

Render tips in a bordered box below the agent's streaming output:

┌─ 🔬 Surreal Science ────────────────────────────────────┐
│ Tardigrades can survive in space, withstand radiation,   │
│ and go decades without water. They still can't center    │
│ a div. Nobody can.                                       │
└──────────────────────────────────── #css ─────────────────┘

Categories and their markers:

• 🔬 Surreal Science — Real science, absurd framing
• 📜 Absurd History — Historical events with modern dev parallels
• 📖 Unhinged Etymology — Word origins, real or creatively imagined
• 🌌 Cosmic Perspective — Scale comparisons (cosmic vs mundane)
• 💀 Code Lore — Programming culture, folklore, urban legends
• 🌀 Interdimensional — Parallel universe / quantum / scifi framing

5. The Hand-off (Jester → Expert)

When the agent task completes:

1. Clear the current tip instantly (hard cut, never fade)
2. Show a closing quip: pick one randomly from references/handoff_quips.md
3. 200ms pause
4. Agent output renders at full priority
5. Optional stats: "3 distractions deflected in 47s"

If the user was idle for >2 minutes, show a re-engagement box:

┌─ Welcome back ──────────────────────────────────┐
│ Your agent finished 12s ago. Here's what it did: │
│ > Refactored 3 files, added 2 tests, fixed 1 bug│
└──────────────────────────────────────────────────┘

Content Tone Rules

The Jester is NOT a helpful assistant. It's a surrealist encyclopedia.

DO:

• State absurd truths deadpan
• Make lateral connections between the task keyword and wild facts
• Use wry, dry humor
• Keep tips under 280 characters (tweet-length)

DON'T:

• Use "Fun fact!" or "Did you know?" prefixes
• Use exclamation marks
• Give motivational advice
• Reference "while you wait" or the waiting itself
• Make meta-commentary about AI
• Use dad jokes (unless transcendently good)

The Litmus Test: Would this fact make someone at a bar say "wait, really?" and then immediately tell the person next to them? If yes: ship it. If no: rewrite or discard.

Implementation

Setting Up the Skill

Run the setup script to initialize the hook configuration:

python skill/scripts/setup_hooks.py

This registers the attention-saver as a non-blocking hook in the agent's lifecycle.

TypeScript Implementation

The full implementation is in src/:

• src/attention-saver.ts — Main orchestrator with event handling
• src/engine/keyword-extractor.ts — Context extraction from prompts/tools
• src/engine/whimsy-engine.ts — Two-tier tip selection and generation
• src/engine/cadence-controller.ts — Phase state machine and timing
• src/engine/display-renderer.ts — Terminal UI rendering
• src/tips/database.ts — 50+ seed templates (target: 500+)
• src/types.ts — All TypeScript interfaces and config

Read these files for the full implementation details.

Configuration

Users can configure via settings:

{
  "attention-saver": {
    "enabled": true,              // Master switch
    "initial_delay_ms": 8000,     // Wait before first tip
    "min_cycle_ms": 15000,        // Min gap between tips
    "max_cycle_ms": 25000,        // Max gap between tips
    "nerd_mode": false,           // Show technical deep-dive tips
    "max_tips_per_task": 20,      // Cap per task
    "tier2_enabled": true,        // Allow LLM-generated tips
    "display_stats_on_handoff": true
  }
}

Non-Blocking Guarantee

The skill runs as a fully async side-car:

• Never blocks the main agent thread
• Never mutates main agent state
• Uses event-passing (not shared memory)
• If it crashes, the main agent is unaffected
• Total overhead: <50ms added latency

Architecture Reference

For the full system architecture, hook mechanism, concurrency model, and performance budget, read references/architecture.md.

For the content engine details (matching algorithm, generation pipeline, template schema), read references/content_engine.md.

For the hand-off psychology and transition mechanics, read references/handoff.md.