oracle-family-scan
Oracle Family Registry — the index of all known Oracles (800+ and growing). Use when user says "family scan", "oracle registry", "welcome new oracles", or needs to check Oracle population.
Soul-Brews-Studio · AI review on file
Installation
Read the source and dependencies before running a command. Copying does not install or execute anything.
npx skills add Soul-Brews-Studio/arra-oracle-skills-cli --skill oracle-family-scanAbout this skill
name: oracle-family-scan description: Oracle Family Registry — the index of all known Oracles (800+ and growing). Use when user says "family scan", "oracle registry", "welcome new oracles", or needs to check Oracle population. argument-hint: "[--scan | --query | --welcome | --activity-report | --timeline | --usage | --calibrate]"
/oracle-family-scan — Oracle Family Registry
Scan, query, and welcome the Oracle family. Powered by registry/ in mother-oracle.
Usage
/oracle-family-scan # Quick stats (default)
/oracle-family-scan --unwelcomed # List unwelcomed community Oracles
/oracle-family-scan --mine # Nat's Oracles (registry)
/oracle-family-scan --mine-deep # Fleet status (local repos + activity + sessions)
/oracle-family-scan --recent # Last 10 born
/oracle-family-scan --retired # Show retired Oracles
/oracle-family-scan "Spark" # Search by name
/oracle-family-scan --human "watcharap0ng" # Search by human
/oracle-family-scan sync # Re-sync registry from GitHub
/oracle-family-scan welcome # Deep welcome flow for unwelcomed Oracles
/oracle-family-scan report # Full family report (with Health block — v3.1)
/oracle-family-scan --activity-report # One-shot fleet health dashboard (NEW v3.1)
/oracle-family-scan --timeline # Sorted by last activity, newest first (NEW v3.1)
/oracle-family-scan --zygotes # Born-but-never-awakened (NEW v3.1)
/oracle-family-scan --usage [N] # Time-spent per Oracle, last N days (NEW v3.1)
/oracle-family-scan --calibrate # Propose data-driven thresholds (NEW v3.1)
Net CLI surface: 14 modes + --calibrate subcommand. Status filtering is orthogonal —
--timeline --status=stale,cold,abandoned replaces what --stale / --abandoned would
have been.
Step 0: Locate Registry
The registry's canonical home is laris-co/mother-oracle/registry/ (where sync.ts + oracles.json actually live). The legacy opensource-nat-brain-oracle repo back-symlinks to it for back-compat. Resolve the path:
date "+🕐 %H:%M %Z (%A %d %B %Y)"
# Optional: oracle root (some sub-flows write to ψ/memory/learnings/)
ORACLE_ROOT=$(git rev-parse --show-toplevel 2>/dev/null)
if [ -n "$ORACLE_ROOT" ] && [ -f "$ORACLE_ROOT/CLAUDE.md" ] && { [ -d "$ORACLE_ROOT/ψ" ] || [ -L "$ORACLE_ROOT/ψ" ]; }; then
PSI="$ORACLE_ROOT/ψ"
elif [ -f "$(pwd)/CLAUDE.md" ] && { [ -d "$(pwd)/ψ" ] || [ -L "$(pwd)/ψ" ]; }; then
ORACLE_ROOT="$(pwd)"
PSI="$ORACLE_ROOT/ψ"
fi
# Try laris-co/mother-oracle (canonical home of sync.ts + oracles.json)
MOTHER="$HOME/Code/github.com/laris-co/mother-oracle"
if [ ! -d "$MOTHER/registry" ]; then
MOTHER="$(ghq root)/github.com/laris-co/mother-oracle"
fi
# Fallback: legacy brain repo (back-symlinks to laris-co/mother-oracle)
if [ ! -f "$MOTHER/registry/oracles.json" ]; then
MOTHER="$HOME/Code/github.com/Soul-Brews-Studio/opensource-nat-brain-oracle"
[ ! -d "$MOTHER/registry" ] && MOTHER="$(ghq root)/github.com/Soul-Brews-Studio/opensource-nat-brain-oracle"
fi
if [ ! -f "$MOTHER/registry/oracles.json" ]; then
echo "Registry not found. Run: ghq get -u laris-co/mother-oracle && bun \$MOTHER/registry/sync.ts"
exit 1
fi
Mode 1: Stats (Default)
bun $MOTHER/registry/query.ts --stats
Shows: total Oracles, unique humans, welcomed/unwelcomed counts, births-by-month chart, unwelcomed detail (if any), and recent births.
Mode 2: --unwelcomed
bun $MOTHER/registry/query.ts --unwelcomed
Lists all community Oracles that haven't been welcomed by nazt.
Mode 3: --mine
bun $MOTHER/registry/query.ts --mine
Lists all Oracles created by nazt (Nat's fleet) from the registry.
Mode 3b: --mine-deep (Fleet Status)
Goal: Show status of all local Oracle repos owned by the current user, augmented with timeline + usage data from the activity layer.
SKILL_DIR="$(dirname "$(readlink -f "$HOME/.claude/skills/oracle-family-scan/SKILL.md" 2>/dev/null || echo "$HOME/.claude/skills/oracle-family-scan/SKILL.md")")"
bun "$SKILL_DIR/scripts/fleet-scan.ts"
New columns (sourced from oracles.json activity block + oracles.local.<host>.json):
| Column | Source | Notes |
|---|---|---|
| Last Active | activity.last_commit_at (max with last_session_at) | "2d ago", "—" if unknown |
| Status Dot | computed from days-since + flags | 🟢🟡🟠🔴🪦⚪ + 🔧 modifier |
| 7d Hours | local sessions on this host | partial — see Coverage |
| Decay | days since lastActivity | numeric, sortable |
| Coverage | which hosts have local session data | 📡 m5 / 📡 m5+white / ⚠ no m5 sessions |
Sample output:
Oracle Fleet Status — host: m5 — 2026-05-13
─────────────────────────────────────────────────────────────────────────────
Status Oracle Last Active Decay 7d Hours Coverage
🟢 spark 1d ago 1d 4.2h 📡 m5
🟢 mother 3d ago 3d 2.1h 📡 m5
🟢🔧 budwiser 6d ago 6d 1.1h 📡 m5 [maintenance]
🟡 pulse 12d ago 12d 0.3h 📡 m5
🟠 phaith 47d ago 47d — ⚠ no m5 sessions
🔴 retro-mind 104d ago 104d — ⚠ no m5 sessions
🪦 echo-test — — — repo deleted on GitHub
⚪ test-yeast born 36d ago —
Read the complete source ↗