Navigator Session Statistics Skill

Show real-time efficiency reporting with baseline comparisons, making Navigator's value quantifiable and shareable.

When to Invoke

Invoke this skill when the user:

• Says "show my stats", "show session stats", "show metrics"
• Asks "how efficient am I?", "how much did I save?"
• Says "show my Navigator report", "efficiency report"
• Wants to see token savings or session performance
• Says "show impact", "prove Navigator works"

DO NOT invoke if:

• User just started session (< 5 messages)
• Navigator not initialized in project
• User asking about specific metrics only (answer directly)

Execution Steps

Step 1: Check Navigator Initialized

Verify Navigator is set up:

if [ ! -f ".agent/DEVELOPMENT-README.md" ]; then
  echo "❌ Navigator not initialized in this project"
  echo "Run 'Initialize Navigator' first"
  exit 1
fi

Step 2: Run Enhanced Session Stats

Execute the enhanced session statistics script:

# Check if enhanced script exists
if [ ! -f "scripts/session-stats.sh" ]; then
  echo "❌ Session stats script not found"
  echo "This feature requires Navigator v3.5.0+"
  exit 1
fi

# Run stats script
bash scripts/session-stats.sh

This script outputs shell-parseable variables:

• BASELINE_TOKENS - Total size of all .agent/ docs
• LOADED_TOKENS - Actually loaded in session (estimated)
• TOKENS_SAVED - Difference
• SAVINGS_PERCENT - Percentage saved
• EFFICIENCY_SCORE - 0-100 score
• CACHE_EFFICIENCY - From OpenTelemetry
• CONTEXT_USAGE_PERCENT - Estimated context fill
• TIME_SAVED_MINUTES - Estimated time saved

Step 3: Calculate Efficiency Score

Use predefined function to calculate score:

# Extract metrics from session-stats.sh
source <(bash scripts/session-stats.sh)

# Calculate efficiency score using predefined function
EFFICIENCY_SCORE=$(python3 skills/nav-stats/functions/efficiency_scorer.py \
  --tokens-saved-percent ${SAVINGS_PERCENT} \
  --cache-efficiency ${CACHE_EFFICIENCY} \
  --context-usage ${CONTEXT_USAGE_PERCENT})

Step 4: Format and Display Report

Use predefined function to format visual report:

# Generate formatted report
python3 skills/nav-stats/functions/report_formatter.py \
  --baseline ${BASELINE_TOKENS} \
  --loaded ${LOADED_TOKENS} \
  --saved ${TOKENS_SAVED} \
  --savings-percent ${SAVINGS_PERCENT} \
  --cache-efficiency ${CACHE_EFFICIENCY} \
  --context-usage ${CONTEXT_USAGE_PERCENT} \
  --efficiency-score ${EFFICIENCY_SCORE} \
  --time-saved ${TIME_SAVED_MINUTES}

Output Format:

╔══════════════════════════════════════════════════════╗
║          NAVIGATOR EFFICIENCY REPORT                 ║
╚══════════════════════════════════════════════════════╝

📊 TOKEN USAGE
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Documentation loaded:        12,000 tokens
Baseline (all docs):        150,000 tokens
Tokens saved:               138,000 tokens (92% ↓)

💾 CACHE PERFORMANCE
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Cache efficiency:              100.0% (perfect)

📈 SESSION METRICS
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Context usage:                      35% (excellent)
Efficiency score:                94/100 (excellent)

⏱️  TIME SAVED
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Estimated time saved:          ~42 minutes

💡 WHAT THIS MEANS
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Navigator loaded 92% fewer tokens than loading all docs.
Your context window is 65% available for actual work.

🎯 RECOMMENDATIONS
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
✅ Excellent efficiency - keep using lazy-loading strategy
✅ Context usage healthy - plenty of room for work

Share your efficiency: Take a screenshot! #ContextEfficiency

Step 5: Add Context-Specific Recommendations

Based on efficiency score, provide actionable advice:

If efficiency_score < 70:

⚠️  RECOMMENDATIONS
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
⚠️  Token savings below target (70%+)
→ Check: Are you loading more docs than needed?
→ Tip: Use navigator to find docs, don't load all upfront

Read more: .agent/philosophy/CONTEXT-EFFICIENCY.md

If context_usage > 80%:

⚠️  RECOMMENDATIONS
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
⚠️  Context usage high (80%+)
→ Consider: Create context marker and compact
→ Tip: Compact after completing sub-tasks

Read more: .agent/philosophy/ANTI-PATTERNS.md

If cache_efficiency < 80%:

⚠️  RECOMMENDATIONS
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
⚠️  Cache efficiency low (<80%)
→ Check: CLAUDE.md properly configured?
→ Tip: Ensure prompt caching enabled

Read more: .agent/philosophy/PATTERNS.md (Caching pattern)

Predefined Functions

efficiency_scorer.py

Calculate Navigator efficiency score (0-100) based on:

• Token savings (40 points)
• Cache efficiency (30 points)
• Context usage (30 points)

Usage:

pyt

...