maw fleet adopt — adopt orphan oracles into fleet

maw-fleet-adopt.md

maw fleet adopt — Adopt Orphan Oracles Into Fleet

Ship date: 2026-05-04 | PR #1093 | Issue #1095

The Problem

91 oracle repos on disk. Only 19 had fleet configs. Oracles whose repo name didn't match their identity couldn't be woken:

maw wake homekeeper → ❌ "oracle repo not found"
# But ~/Code/github.com/laris-co/homelab/CLAUDE.md says "# Homekeeper Oracle"

The Solution

# Step 1: See what's out there
maw fleet adopt --scan

  Orphan oracles (91 not in fleet):

    1  homelab                       → Homekeeper Oracle        (laris-co)
    2  clawdacle                     → Clawacle Oracle          (Soul-Brews-Studio)
    3  sea-oracle                    → Sea Oracle               (Soul-Brews-Studio)
    4  fireman-oracle                → FireMan Oracle           (laris-co)
    ...

# Step 2: Adopt the ones you want
maw fleet adopt homelab

  ✅ adopted: homelab → homekeeper (20-homekeeper.json)
     repo: laris-co/homelab
     fleet: ~/.config/maw/fleet/20-homekeeper.json
     next: maw wake homekeeper

# Step 3: Wake it
maw wake homekeeper
  ⚡ 'homekeeper-oracle' running in 20-homekeeper

Usage

maw fleet adopt --scan                     # find all orphan oracles
maw fleet adopt <repo-name>               # adopt one
maw fleet adopt <repo> --as <name>        # override the detected name
maw fleet adopt <repo> --dry-run          # preview without writing
maw fleet adopt repo1 repo2 repo3         # adopt multiple

How It Works

1. Scan: walks all ghq repos, checks for CLAUDE.md + ψ/ directory
2. Extract identity: reads line 1 of CLAUDE.md → strips emoji, "Oracle" suffix, subtitles, parentheticals → produces a clean stem
3. Check duplicates: compares against existing fleet configs
4. Write config: creates ~/.config/maw/fleet/NN-<stem>.json with repo mapping
5. Auto-register: mergeFleetIntoAgents() picks it up on next config load

Name Extraction Examples

CLAUDE.md line 1	Detected stem
# Homekeeper Oracle	homekeeper
# 🔥 FireMan Oracle	fireman
# Sea — ไข่มุกเกิดจากความเจ็บปวด	sea
# SHRIMP Oracle (น้องกุ้ง)	shrimp
# AR01	ar01
# เสี่ยวเอ้อ — Thong Pradit Brewing Oracle	thong-pradit-brewing

Fleet Config Output

{
  "name": "20-homekeeper",
  "windows": [{
    "name": "homekeeper-oracle",
    "repo": "laris-co/homelab"
  }],
  "adopted_at": "2026-05-04T...",
  "adopted_from": "ghq:laris-co/homelab"
}

Flags

Flag	Effect
--scan	List all orphan oracles (read-only)
--dry-run	Show what would be created without writing
--as <name>	Override the auto-detected oracle stem

Exclusions

• Worktrees (.wt- in path) — skipped automatically
• Non-oracle repos (CLAUDE.md says "Project Instructions") — filtered
• Already registered repos — skipped with note

Related Commands

maw fleet ls          # list all fleet configs
maw fleet adopt --scan # find orphans
maw fleet adopt <repo> # register one
maw wake <oracle>     # now works for adopted oracles
maw bud <name>        # creates fleet config automatically (for new oracles)

Implementation

Single file: src/commands/plugins/fleet/fleet-adopt.ts (113 LOC) Wired into fleet plugin index.ts as a subcommand.

Reuses:

• loadFleetEntries() — existing fleet loading
• FLEET_DIR — fleet config directory
• Number computation pattern from maw bud

---

Built because maw wake homekeeper failed and the fix was 113 lines of code that scans what's already on disk.