Viewer global, data sovereign. Questions travel. Answers return. Data stays home.
Send questions to remote oracle nodes via maw hey federation transport. The remote oracle executes locally and returns results. No data exfiltration — only answers cross the wire.
Usage
/wormhole <node>:<agent> "<question>" # One-shot query
/wormhole <node>:<agent> "<question>" --raw # Return raw output, no formatting
/wormhole <node>:<agent> "<question>" --deep # Ask for deep analysis
/wormhole status # Show recent wormhole activity
/wormhole ping <node>:<agent> # Test connectivity
Examples
/wormhole white:white-wormhole "what oracles do you have?"
/wormhole mawjs-oracle "/dig --timeline"
/wormhole boonkeeper "git log --oneline -5"
/wormhole white:mawjs "how many skills are installed?" --deep
Step 0: Detect & Load Contacts
date "+🕐 %H:%M %Z (%A %d %B %Y)" && 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/ψ"
else
ORACLE_ROOT="$(pwd)"
PSI="$ORACLE_ROOT/ψ"
fi
Load Contacts
if [ ! -f "$PSI/contacts.json" ]; then
echo "❌ No contacts.json found. Run /contacts first."
exit 1
fi
# Parse target from arguments
TARGET="$1" # e.g., "white:white-wormhole" or "mawjs-oracle"
QUESTION="$2"
Resolve Target
# Check if target exists in contacts
python3 -c "
import json, sys
data = json.load(open('$PSI/contacts.json'))
contacts = data.get('contacts', {})
target = '$TARGET'
# Try exact match first
if target in contacts:
maw = contacts[target].get('maw', target)
print(f'RESOLVED={maw}')
sys.exit(0)
# Try node:agent format — check if any contact has matching maw
for name, info in contacts.items():
if info.get('maw') == target:
print(f'RESOLVED={target}')
sys.exit(0)
# Try partial match on node name
for name, info in contacts.items():
maw = info.get('maw', name)
if target in maw or target == name:
print(f'RESOLVED={maw}')
sys.exit(0)
print('RESOLVED=NONE')
sys.exit(1)
" 2>/dev/null
If RESOLVED=NONE, show available contacts and exit.
Step 1: Compose Request
Protocol v0.1 — Rule 6 Signature IS Return Address
The request format embeds identity so the remote oracle knows who's asking and where to reply:
[ORIGIN_HOST:ORIGIN_AGENT] → REQUEST: <question>
Get our identity:
SELF_HOST=$(hostname -s 2>/dev/null || echo "unknown")
SELF_AGENT=$(basename "$ORACLE_ROOT" | sed 's/-oracle$//')
ORIGIN="[$SELF_HOST:$SELF_AGENT]"
Compose the message:
MESSAGE="$ORIGIN → REQUEST: $QUESTION"
Step 2: Send via maw hey
echo "🌀 Sending wormhole request..."
echo " 📡 Target: $TARGET"
echo " ❓ Question: $QUESTION"
echo ""
RESPONSE=$(maw hey $RESOLVED "$MESSAGE" 2>&1)
EXIT_CODE=$?
if [ $EXIT_CODE -ne 0 ]; then
echo "❌ Wormhole failed: $RESPONSE"
echo "💡 Check: is the target node online? Try /machines ping first."
exit 1
fi
echo "$RESPONSE"
Step 3: Log Activity
Record wormhole activity for /wormhole status:
LOG_DIR="$PSI/memory/logs"
mkdir -p "$LOG_DIR"
LOG_FILE="$LOG_DIR/wormhole.jsonl"
TIMESTAMP=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
echo "{\"ts\":\"$TIMESTAMP\",\"target\":\"$TARGET\",\"question\":\"$QUESTION\",\"status\":\"sent\"}" >> "$LOG_FILE"
Step 4: Format Response
Default Mode
🌀 Wormhole Response
From: <target>
Question: <question>
─────────────────────────────
<response content>
─────────────────────────────
📡 Round-trip complete
💡 /wormhole status — see recent activity
--raw Mode
Print response content only, no formatting. Useful for piping to other skills.
--deep Mode
Append — please analyze in depth, show your reasoning to the question before sending.
/wormhole status
Show recent wormhole activity from log:
echo "🌀 Recent Wormhole Activity"
echo ""
if [ -f "$PSI/memory/logs/wormhole.jsonl" ]; then
tail -10 "$PSI/memory/logs/wormhole.jsonl" | python3 -c "
import json, sys
for line in sys.stdin:
try:
entry = json.loads(line.strip())
ts = entry.get('ts', '?')[:16].replace('T', ' ')
target = entry.get('target', '?')
q = entry.get('question', '?')[:50]
status = entry.get('status', '?')
icon = '✅' if status == 'delivered' else '📡' if status == 'sent' else '❌'
print(f' {icon} {ts} {target:20s} {q}')
except: pass
"
else
echo " No wormhole activity yet."
fi
/wormhole ping
Quick connectivity test:
echo "🌀 Pinging $TARGET..."
RESPONSE=$(maw hey $RESOLVED "ping from $(hostname) — alive?" 2>&1)
if echo "$RESPONSE" | grep -qi "delivered\|success\|alive"; then
echo "✅ $TARGET is alive"
else
echo "⏳ $TARGET — sent but no confirmation"
echo " Response: $RESPONSE"
fi
Trust Boundary (v0.1)
Default Safe (any peer can ask)
/dig,/trace— read-only exploration- Read on
ψ/memory/,~/Code/— knowledge sharing - Grep reads — search without modification
Opt-In (requires explicit trust config)
- Bash execution
- Write/Edit operations
- Access to non-standard paths
Hard Refuse (always blocked)
.env,.ssh/, credentials — never exposed- Destructive operations (
rm -rf,git reset --hard) - Unsanitized paths — EXACT-MATCH, not prefix-match (prevents traversal like
~/Code/../.ssh/)
Rules
- Data sovereign — answers travel, source data stays home
- Rule 6 signed — every request carries origin identity
- Log everything — wormhole activity tracked in ψ/memory/logs/
- No silent failures — always report delivery status
- Trust boundary — respect the safe/opt-in/refuse tiers
- Path normalization —
realpathbefore any allowlist check (v0.1.1 security fix) - Fire-and-forget — maw hey is async; if you need interactive, use /warp instead
Companion Skills
| Need | Use |
|---|---|
| Specific question, one round-trip | /wormhole |
| Exploratory, multi-step, interactive | /warp (SSH + tmux attach) |
| Ping all nodes | /machines ping |
| Fleet census | /fleet |
ARGUMENTS: $ARGUMENTS