Soul-Brews-Studio/warp

/warp — Teleport to Remote Node

When one round-trip isn't enough. Step through the door.

SSH into a remote oracle node and attach to their tmux session. You become the remote oracle temporarily — full interactive access for multi-step work. The complement to /wormhole (fire-and-forget queries).

When to Use

| Need | Use | |------|-----| | Specific question, one answer | /wormhole | | Exploratory work, debugging, multi-step | /warp | | "I need more than 2 round-trips" | /warp |

Usage

/warp <node>:<agent>           # SSH + attach to existing tmux session
/warp <node>:<agent> --new     # SSH + create new tmux session
/warp <node>:<agent> --attach  # Attach only (already SSH'd)
/warp <node>:<agent> --list    # List active tmux sessions on node
/warp back                     # Return to local oracle

Examples

/warp white:mawjs              # Teleport to white node, mawjs oracle
/warp boonkeeper --list        # Check what's running on boonkeeper
/warp oracle-world:mawjs-oracle --new  # New session on oracle-world
/warp back                     # Come home

---

Step 0: Resolve Target

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 & Resolve

if [ ! -f "$PSI/contacts.json" ]; then
  echo "❌ No contacts.json. Run /contacts first."
  exit 1
fi

Parse target to find the node's SSH address. Look for node configuration in contacts or known hosts:

python3 -c "
import json, sys
data = json.load(open('$PSI/contacts.json'))
contacts = data.get('contacts', {})
target = '$TARGET'

# Find the contact
for name, info in contacts.items():
    maw = info.get('maw', name)
    if target == name or target == maw or target.split(':')[0] in [name, maw.split(':')[0]]:
        print(f'NAME={name}')
        print(f'MAW={maw}')
        print(f'REPO={info.get(\"repo\", \"\")}')
        print(f'NOTES={info.get(\"notes\", \"\")}')
        sys.exit(0)
print('NOT_FOUND')
sys.exit(1)
"

---

Step 1: Determine SSH Target

Map node names to SSH hosts. Check these sources in order:

1. ~/.ssh/config — look for Host entries matching the node name
2. WireGuard peers — wg show for known endpoints
3. maw registry — maw nodes if available
4. /etc/hosts — direct hostname resolution

# Try SSH config first
SSH_HOST=$(ssh -G "$NODE" 2>/dev/null | grep "^hostname " | awk '{print $2}')

if [ -z "$SSH_HOST" ]; then
  echo "❌ No SSH config for node '$NODE'"
  echo "💡 Add to ~/.ssh/config:"
  echo "  Host $NODE"
  echo "    HostName <ip-or-hostname>"
  echo "    User neo"
  exit 1
fi

echo "🌀 Resolved: $NODE → $SSH_HOST"

---

Step 2: Check Remote tmux

echo "🔍 Checking tmux sessions on $NODE..."

SESSIONS=$(ssh "$NODE" "tmux list-sessions 2>/dev/null" 2>/dev/null)

if [ -z "$SESSIONS" ]; then
  echo "  No active tmux sessions."
  if [ "$MODE" != "--new" ]; then
    echo "  💡 Use /warp $TARGET --new to create one"
  fi
fi

--list Mode

Show sessions and exit:

🌀 tmux sessions on $NODE:

  Session       Windows  Created      Status
  ─────────────  ──────── ──────────── ──────
  oracle         3        2h ago       attached
  dev            1        5h ago       detached

  💡 /warp $NODE --attach <session-name>

---

Step 3: Connect

Attach to existing session (default)

echo "🌀 Warping to $NODE..."
echo "  📡 SSH: $SSH_HOST"
echo "  🖥  tmux: attaching to default session"
echo ""
echo "  ⚠️ You are now REMOTE. Local context is paused."
echo "  💡 Ctrl+B D to detach (keeps session alive)"
echo "  💡 /warp back to return"
echo ""

ssh -t "$NODE" "tmux attach-session || tmux new-session -s oracle"

Create new session (--new)

SESSION_NAME="${AGENT:-oracle}-$(date +%H%M)"
ssh -t "$NODE" "tmux new-session -s '$SESSION_NAME'"

---

Step 4: Return (/warp back)

When the user says /warp back or detaches from tmux:

🌀 Returned to local oracle

  📍 Back at: $(hostname) / $ORACLE_ROOT
  ⏱  Remote session: still alive (detached)
  
  💡 /warp $LAST_TARGET — reconnect
  💡 /wormhole $LAST_TARGET "status" — quick check

---

Safety

1. SSH keys required — never prompt for passwords (use ssh-agent)
2. tmux isolation — always use tmux (never raw SSH), so sessions survive disconnects
3. No port forwarding — warp is for oracle work, not tunneling
4. Log warps — record in ψ/memory/logs/warp.jsonl for audit trail
5. Return signal — always remind how to come back (Ctrl+B D or /warp back)

---

Warp Log

LOG_FILE="$PSI/memory/logs/warp.jsonl"
mkdir -p "$(dirname "$LOG_FILE")"
TIMESTAMP=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
echo "{\"ts\":\"$TIMESTAMP\",\"target\":\"$TARGET\",\"node\":\"$NODE\",\"action\":\"warp\"}" >> "$LOG_FILE"

---

Rules

1. Interactive only — warp is for multi-step work, not queries (use /wormhole for that)
2. SSH config required — never guess hostnames or IPs
3. tmux always — raw SSH is dangerous (disconnects kill work)
4. Log everything — warp activity tracked for audit
5. Return path — always show how to come back
6. No secrets transit — never pipe .env or credentials through warp

---

ARGUMENTS: $ARGUMENTS