Microsoft ShadowFrog Viewer
Query and browse .shadow/ content. Prerequisite: .shadow/ exists.
Primary: Python Helper Script
The companion script shadow-viewer.py lives in the same directory as
this SKILL.md file. To find and run it:
# Project install (Copilot CLI):
python3 .github/skills/shadow-frog-viewer/shadow-viewer.py [options]
# Or for Claude Code:
python3 .claude/skills/shadow-frog-viewer/shadow-viewer.py [options]
Available Views
| Command | What it shows |
|---|---|
--summary |
Overview: counts, source/status/label breakdown, per-file table, cross-cutting titles (default) |
--search QUERY |
Universal search — matches file names, symbol names, and discovery text. Includes cross-cutting and preferences |
--prefs |
Project-wide preferences |
--recent [N] |
N most recent discoveries with full content (default: 10) |
--labels LABEL |
Discoveries filtered by label (e.g., bug, security, bug,performance) |
--top FILE |
Top actionable discoveries for FILE — concise output (default: 3 entries, ~600 chars) suitable for the preToolUse hook. Includes both per-file shadow entries and any _cross/ discoveries that reference FILE. Verified discoveries rank first. |
--check-invariants |
Audit structural integrity — bidirectional cross-references, label/source/category enum compliance, heading format, no-orphan-back-pointer. Exits 0 if clean, 1 with one violation per line. Run after dream reconciliation or before commit. |
No arguments defaults to --summary.
Options
| Flag | Effect |
|---|---|
--shadow-dir DIR |
Override .shadow/ location (default: auto-detect from CWD) |
--top-labels LABELS |
Comma-separated label filter for --top (default: bug,security). Empty string disables label filtering. |
--top-limit N |
Max discoveries to show in --top (default: 3) |
--top-max-chars N |
Hard cap on --top total output length (default: 600). Use 0 for no cap. |
Examples
# Quick overview
python3 shadow-viewer.py
# Everything about auth (files, symbols, text, cross-cutting)
python3 shadow-viewer.py --search auth
# Find token-related knowledge
python3 shadow-viewer.py --search "token expiry"
# 5 most recent discoveries
python3 shadow-viewer.py --recent 5
# All known bugs
python3 shadow-viewer.py --labels bug
# Security and performance issues
python3 shadow-viewer.py --labels security,performance
# Top actionable discoveries for a single file (used by the preToolUse hook)
python3 shadow-viewer.py --top src/auth.py
# Same, but broaden label filter and show up to 5 entries
python3 shadow-viewer.py --top src/auth.py --top-labels bug,security,performance --top-limit 5
# Team preferences
python3 shadow-viewer.py --prefs
# Structural audit (run before commits or after dream reconciliation)
python3 shadow-viewer.py --check-invariants
Dream Lineage Visualization
The companion script dream-lineage.py generates an interactive HTML
visualization of the dream experiment tree. It reads _dreams/_index.md
and experiment reports to produce a self-contained HTML file.
# (Claude Code users: replace .github/skills with .claude/skills below)
# Generate dream-lineage.html in the current directory
python3 .github/skills/shadow-frog-viewer/dream-lineage.py
# Custom output path
python3 .github/skills/shadow-frog-viewer/dream-lineage.py -o my-lineage.html
# Explicit shadow directory
python3 .github/skills/shadow-frog-viewer/dream-lineage.py --shadow-dir /path/to/.shadow
The HTML file has three tabs:
- 🌳 Chains — compounding chains as tree cards, sorted by depth
- 📋 Fresh — non-compounding experiments grouped by category
- 🗂️ Full Tree — compact view of the entire lineage in one tree
Each node shows the experiment's category icon, name, verdict, test count, and discovery count. Click "▶ Show report" to expand the full experiment report inline.
Fallback: Shell One-Liners
If the Python script fails to execute (wrong Python version, missing file, permission error, etc.), fall back to these shell commands:
Summary
Note: shell discovery counts are approximate (may include cross-reference links).
echo "Files: $(find .shadow -name '*.md' -not -path '*/_cross/*' -not -path '*/_meta/*' -not -path '*/_dreams/*' -not -name '_index.md' -not -name '_prefs.md' | wc -l | tr -d ' ')"
echo "Discoveries: $(find .shadow -name '*.md' -not -path '*/_cross/*' -not -path '*/_meta/*' -not -path '*/_dreams/*' -not -name '_index.md' -not -name '_prefs.md' -exec grep -c '^\- ' {} \; 2>/dev/null | awk '{s+=$1} END {print s+0}')"
echo "Cross-cutting: $(ls .shadow/_cross/*.md 2>/dev/null | wc -l | tr -d ' ')"
python3 -c "import json; d=json.load(open('.shadow/_meta/state.json')); print(f'Last update: {d[\"last_update_at\"]} ({d[\"last_update_type\"]})')"
Search
grep -rn "QUERY" .shadow/ --include="*.md"
Preferences
cat .shadow/_prefs.md
Recent
# macOS
find .shadow -name '*.md' -not -path '*/_meta/*' -exec stat -f '%m %N' {} \; | sort -rn | head -10 | while read ts f; do echo "$(date -r "$ts" '+%Y-%m-%d %H:%M') $f"; done
# Linux
find .shadow -name '*.md' -not -path '*/_meta/*' -printf '%T@ %p\n' | sort -rn | head -10 | while read ts f; do echo "$(date -d @"${ts%%.*}" '+%Y-%m-%d %H:%M') $f"; done
Responding to the User
After running a view, present the results clearly:
- For
--summary: show the output directly, highlight anything notable - For
--search: summarize key findings, group by relevance - For
--recent: present the discoveries conversationally - For
--top: typically called by the preToolUse hook before a file is edited; output is intentionally short and pre-formatted. If invoked manually, present as-is. - If the shadow is empty or has no discoveries, suggest running
/shadow-frog-dreamto populate it