# Shadow Frog Viewer

> >-

- **Type:** Skill
- **Install:** `agentstack add skill-microsoft-shadowfrog-shadow-frog-viewer`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [microsoft](https://agentstack.voostack.com/s/microsoft)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [microsoft](https://github.com/microsoft)
- **Source:** https://github.com/microsoft/ShadowFrog/tree/main/skills/shadow-frog-viewer

## Install

```sh
agentstack add skill-microsoft-shadowfrog-shadow-frog-viewer
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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:

```bash
# 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

```bash
# 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.

```bash
# (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).

```bash
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

```bash
grep -rn "QUERY" .shadow/ --include="*.md"
```

### Preferences

```bash
cat .shadow/_prefs.md
```

### Recent

```bash
# 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-dream` to populate it

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [microsoft](https://github.com/microsoft)
- **Source:** [microsoft/ShadowFrog](https://github.com/microsoft/ShadowFrog)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-microsoft-shadowfrog-shadow-frog-viewer
- Seller: https://agentstack.voostack.com/s/microsoft
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.