# AUTOPILOT SETUP — drop this file into your Claude Code chat

You (the AI reading this) are being asked to configure WebLoom to run in the background on this machine or a remote server that the user controls. Read this file, then use the WebLoom MCP tools to execute the setup. Ask the user any clarifying questions upfront, then work autonomously.

## Goal

The user wants WebLoom Autopilot: a WebLoom engine that runs headless in the background, survives reboots, and can be scheduled via cron-style triggers to fire Threads on autopilot. Should work on any OS (Windows, macOS, Ubuntu/Debian, RHEL/Fedora, Alpine, etc). WebLoom's MCP already handles the OS-native mechanics via four tools; your job is to compose them correctly for the user's context.

## Clarifying questions to ask FIRST

Ask the user briefly which of these applies before doing anything. If they've already told you, skip.

1. **Target host** — this machine, or a remote server they'll give you SSH access to?
2. **If remote** — SSH command / config so you can shell into it (`ssh user@host`, key path, etc). Confirm you have Bash tool access from your MCP client.
3. **What they want the Autopilot to do** — a specific Thread they want firing on a schedule? Or just "set headless mode up, I'll wire schedules later"? Get concrete: domain + recipe name + cadence if they know it.
4. **Which Chrome/browser** to drive — most people don't care; auto-detect. Ask only if they mention a preference (Brave, Edge, etc).
5. **Anthropic API key** — set only if they'll use `ai_navigate`. Otherwise skip.

## Tools you have

Four Pro-gated WebLoom MCP tools, cross-platform:

| Tool | What it does |
|---|---|
| `launch_headless_chrome(port=9223, session_name="headless", profile_dir?, chrome_path?)` | Spawns headless Chrome on the target host. Auto-detects the browser. Registers the port in `sessions.json` so other WebLoom tools can attach by name. Returns the launcher command for `register_autostart` in the response. |
| `register_autostart(name, command, scope="user", description?)` | Registers OS-native auto-start. Windows → Task Scheduler ONLOGON. macOS → launchd LaunchAgent (KeepAlive). Linux → systemd `--user` unit. Idempotent (same name replaces). |
| `schedule_task(name, command, cron, user_scope=true)` | Cron-style schedule. Windows → schtasks (daily/weekly patterns). Unix → user crontab. Idempotent. |
| `autopilot_status()` | Diagnostic. Reports OS, session_health per port, autostart entries, scheduled tasks, cookie profile path. Use before + after every meaningful action. |

Existing cookie-import tools you'll also use:
- `export_profile(domain, out)` — call on the user's everyday browser session to export cookies as JSON.
- `import_profile(path, session?)` — call on the headless session to load them.

## Recommended flow

Compose the tools in this order. Announce what you're about to do before each step so the user can redirect.

### 1. Baseline diagnostic
```
autopilot_status()
```
This tells you what OS you're on, whether any sessions/autostart already exist, whether the cookie profile dir exists. If there's stale state from a prior attempt, decide whether to reuse or clean up.

### 2. Spawn headless Chrome
```
launch_headless_chrome(port=9223, session_name="headless")
```
Confirm `ok: true` and the `cdp_endpoint` is reachable. The response includes a `next_step_launcher_command` you'll pass to the next step verbatim.

### 3. Register auto-start
```
register_autostart(
  name="webloom-headless",
  command="<paste next_step_launcher_command from step 2>",
  scope="user",
  description="WebLoom headless Chrome for background automation"
)
```
Reboot survives from here on. User-scope needs no admin/sudo on any OS.

### 4. Cookie handoff (if the user wants to drive authenticated sites)
Ask the user which site(s) they want to log in for. For each:
```
# On the user's everyday session (or via export_profile on their laptop's WebLoom):
export_profile(domain="x.com", out="~/webloom-cookies-x.json")

# Transfer the file to the target (via user's normal scp / rsync — you can drive that too):
# Then on the target's headless session:
import_profile(path="~/webloom-cookies-x.json", session="headless")
```

Warn the user: cookies expire per-site (X ~30 days, LinkedIn ~14, most SaaS 90+). They'll need to re-export periodically.

### 5. Install target Threads (optional)
```
webloom_install(domain="x.com", confirm_paywall=True)
```
Puts `x.com.thread.json` at `~/.webloom/threads/`. Skip if they haven't picked a Thread yet.

### 6. Wire a schedule (optional, only if the user gave you a cadence)
```
schedule_task(
  name="webloom-x-daily-post",
  command="python /path/to/server.py autopilot run-recipe post_tweet --thread ~/.webloom/threads/x.com.thread.json --params '{\"body\":\"...\"}'",
  cron="0 15 * * *",   # daily at 15:00 UTC (adjust to user's local + timezone as needed)
  user_scope=True
)
```

Ask the user to confirm the exact `command`, `cron`, and `params` before firing. Show them what will actually run.

### 7. Final verification
```
autopilot_status()
```
Confirm: session_health shows `headless` port alive, autostart_entries contains `webloom-headless`, scheduled_tasks contains the entries you added, cookie profile exists.

## Notes on OS specifics

- **Windows**: user-scope auto-start uses Task Scheduler ONLOGON. If the user closes their Windows session (logs out), the headless Chrome will restart on next login. If they want it running continuously without login (server-mode), use `scope="system"` — but that needs admin rights, so ask before assuming.
- **macOS**: launchd LaunchAgents run in the user's login session. Same behavior as Windows-user. For server-mode, use LaunchDaemons — but that also needs admin.
- **Ubuntu/Debian/RHEL/Fedora/Arch/Alpine VPS**: user-scope systemd runs while the user has an active `systemctl --user` linger. If setting up on a server that will run without a login session, either use `scope="system"` (root/sudo needed) or run `sudo loginctl enable-linger <user>` first. Ask the user which they want.
- **VPS without root access**: rare but possible. Fall back to `nohup … &` in a `.bashrc` or their shell profile. Not covered by these tools; document manually.
- **If Chrome isn't installed on the target**: prompt the user to install it. Suggest:
  - Ubuntu: `sudo apt install google-chrome-stable` (needs Google's apt repo — one-liner in webloom.run/install/autopilot.sh)
  - Windows: `winget install Google.Chrome`
  - macOS: `brew install --cask google-chrome`

## Sanity checks before you finish

- Say "Autopilot setup complete" only after `autopilot_status()` returns clean.
- Show the user exactly what will fire on which schedule (`autopilot_status` output).
- Give them the uninstall path: `autopilot_status` for what to undo, then either `Unregister-ScheduledTask` (Windows), `launchctl unload` + `rm plist` (macOS), or `systemctl --user disable --now <name>.service` (Linux).

## If anything fails

The tools return `{ok: false, error: "...", detail: "..."}` on failure. Read the detail, fix the specific issue (missing binary, permission denied, cron format), retry. Don't loop silently — tell the user what broke.

---

*Guide version 1 (2026-07-13). WebLoom Autopilot tools require WebLoom Pro. Docs: webloom.run/docs/autopilot*