Part 0: For Remy (5-minute read)
What this is
Claude Code on its own can edit files and run commands. That covers code, but most of life happens in websites and apps you're signed in to. Give Claude three more things and it can do most of what you can do at a computer:
- Its own always-on computer that it fully controls: admin rights, never sleeps, nobody else using it.
- A real, signed-in web browser that it drives like a person would. This means your actual Chrome with your logins, not a "bot browser" that sites can detect and block.
- OS-level control of that computer: screenshots, mouse, keyboard, GUI apps, system settings.
What it unlocks (real examples from Xavier's setup)
- Services with no API, or a paid-only API. Suno: Claude writes the lyrics, generates songs in the Suno web app, picks takes and downloads them, all on Xavier's normal subscription. The same goes for most AI image and video tools, Canva, and anything else behind a login.
- Life admin: paying bills through online banking, filling in applications and forms, booking things, checking orders, comparing prices on sites that block scrapers.
- Sign-in codes: reading emailed codes (Gmail over IMAP) and SMS codes (Google Messages for web), so it can sign in without stopping to ask you.
- Research behind logins: LinkedIn, paywalled news you subscribe to, internal dashboards.
- Heavy jobs off your laptop: video renders, builds and downloads run on the box overnight, with a big external drive for storage.
- GUI apps and system settings that have no command line.
The decision to make first: Mac box or Windows box
Your own computer's OS doesn't matter. Claude Code runs on your Windows PC and controls the box over SSH. The question is only what the box runs.
| Mac mini as the box | Windows mini PC as the box | |
|---|---|---|
| Browser layer | Understudy already exists (Xavier's tool: real Chrome on a hidden display, MCP server, password vault, audit log). Install takes about an afternoon. | You have to build it. Part 4 is the spec for your Claude to build from, roughly a few days of back-and-forth. Or start with Anthropic's Claude in Chrome extension (Part 4A). |
| OS control | Well-trodden: AppleScript, cliclick, screencapture, Accessibility APIs. |
Workable, but SSH sessions can't see the desktop (Part 3, "the Session 0 problem"). UAC prompts can't be clicked by software. |
| Cost | Base Mac mini | A cheap mini PC or a spare Windows machine |
Recommendation: if you're buying hardware anyway, a base Mac mini is the shortest path to everything working, even with a Windows main PC. If you'd rather use a spare Windows machine, it's very doable. Just expect the browser layer to be a project rather than an install. The fundamentals below are the same either way.
What you'll have to do by hand
Your Claude can do almost all of this itself. You'll be needed for:
- Initial OS setup and creating the user account.
- Permission dialogs the OS deliberately won't let software click (macOS privacy toggles, Windows UAC).
- Signing in to your accounts once in Claude's browser. After that the sessions persist.
- Saving passwords into the password vault (Claude never sees them; see Part 5).
- Deciding what Claude may do without asking. Part 6 has our rules as a starting point.
Part 1: The architecture (for Claude)
Remy's PC (Windows) The box (always on, dedicated to Claude)
┌─────────────────────┐ SSH (key auth) ┌──────────────────────────────────────────┐
│ Claude Code │ ──────────────────▶ │ shell: builds, scripts, long jobs │
│ - global CLAUDE.md │ │ │
│ - MCP: browser │ ── SSH tunnel ────▶ │ browser service (localhost only) │
│ │ (or Tailscale) │ └─ real Chrome, own profile, signed in │
└─────────────────────┘ │ desktop agent (in the logged-in session) │
│ └─ screenshots, mouse, keys, GUI apps │
│ big disk for outputs │
└──────────────────────────────────────────┘
Five layers, in order of importance:
- A dedicated box with full access. Claude is an admin there. Its password goes in Claude's instructions so it can use sudo or elevation without asking. That's only acceptable because the box holds nothing but Claude's work and the browser profile. Don't do this on a shared family machine.
- Non-interactive SSH from the main PC to the box, with key auth, so Claude can run anything there in one command.
- A browser service that exposes a real, signed-in Chrome to Claude as MCP tools (
navigate,read_page,click,type_text,screenshot,type_password, …). - A way to run things inside the logged-in desktop session. An SSH shell is not the desktop on either OS: it can't see the screen or drive apps.
- A global
CLAUDE.mdthat tells every future Claude session that all of this exists, how to use it, and the rules. Without it, each session rediscovers everything or doesn't know it can.
Part 2: The box
If it's a Mac mini
- Create a user, enable automatic login (System Settings → Users & Groups).
- Never sleep:
sudo pmset -a sleep 0 displaysleep 0 disksleep 0. Screen lock and screensaver off, because a locked screen blocks GUI input. - Remote Login (SSH) on. Put the PC's public key in
~/.ssh/authorized_keys. Test from the PC withssh box 'echo ok', which must work with no prompt. Add aHost boxentry to the PC's~/.ssh/config. - Passwordless sudo for that user (
/etc/sudoers.d/claude:<user> ALL=(ALL) NOPASSWD: ALL). - Screen Sharing on, so Remy can watch (only the System Settings switch actually enables it, not
launchctl). - Install Homebrew, Bun, git,
cliclick, Google Chrome (or Chrome Beta, see Part 4). - Grant Accessibility and Screen Recording to
bun(and tosshd-keygen-wrapperif you want plainssh box screencaptureto work). macOS needs a human to flip these toggles. Have Claude open the right settings pane, then ask Remy for the click. - Then install Understudy (Part 4B).
If it's Windows
- Create a local admin account for Claude's work. Turn off "only allow Windows Hello sign-in" so a password login exists.
- Automatic login: Sysinternals Autologon (stores the password encrypted). After any reboot, including Windows Update ones, the desktop session comes back on its own.
- Never sleep:
powercfg /change standby-timeout-ac 0,powercfg /change monitor-timeout-ac 0,powercfg /change hibernate-timeout-ac 0. Screensaver off, and no lock on wake. A locked session means no screenshots and no input. - Headless? Plug in an HDMI dummy plug (a few dollars). Without a monitor, Windows may drop to a tiny resolution or stop rendering properly.
- OpenSSH Server (PowerShell as admin):
Gotcha: for an admin user, Windows ignoresAdd-WindowsCapability -Online -Name OpenSSH.Server~~~~0.0.1.0 Start-Service sshd; Set-Service sshd -StartupType Automatic # Make PowerShell 7 the SSH shell (install pwsh first) New-ItemProperty -Path "HKLM:\SOFTWARE\OpenSSH" -Name DefaultShell -Value "C:\Program Files\PowerShell\7\pwsh.exe" -PropertyType String -Force~/.ssh/authorized_keys. The key goes inC:\ProgramData\ssh\administrators_authorized_keyswith locked-down permissions:icacls C:\ProgramData\ssh\administrators_authorized_keys /inheritance:r /grant "Administrators:F" /grant "SYSTEM:F". - UAC: elevation prompts appear on the "secure desktop", which software can't click. That's deliberate, so
no automation can approve itself. On this dedicated box only, set admin elevation to not prompt
(
HKLM\SOFTWARE\Microsoft\Windows\CurrentVersion\Policies\System,ConsentPromptBehaviorAdmin = 0), and run the desktop agent elevated (see below). Also: a non-elevated process can't send input to an elevated window (UIPI), which is another reason to run the agent elevated. - Windows Update: set active hours, and turn on the "no auto-restart with logged-on users" policy so it doesn't reboot mid-job. Autologon covers the reboots that do happen.
- Watching it / remote access: use VNC, Chrome Remote Desktop or Parsec, which show the real console session.
Avoid RDP: when an RDP session disconnects, the console stays locked and GUI automation breaks (black
screenshots, input ignored) until someone logs in at the machine. If you must use RDP, disconnect with
tscon <session id> /dest:console(from an elevated prompt) instead of closing the window. - Display scaling: set it to 100%, or make every tool DPI-aware. Otherwise screenshot pixels and click coordinates disagree, and every click lands off-target.
- Install Git, Bun, Node, Chrome, PowerShell 7, Tailscale (optional).
Reaching it from elsewhere
On the home network, plain SSH to box.local (or its IP) works. For use from anywhere, install Tailscale on
both machines and SSH to the tailnet name. Never expose the browser service port to a network in plain HTTP;
tunnel it over SSH or Tailscale.
Part 3: OS-level control (the "desktop session" problem)
This tripped us up more than anything else. An SSH shell is not the logged-in desktop.
- macOS: an SSH shell has no window server access, so GUI apps and AppleScript UI scripting don't work, and privacy permissions apply differently.
- Windows:
sshdis a service, so everything it spawns runs in Session 0, which has no desktop. GUI apps you launch there are invisible, and screenshots are black.
So you need a way to run a command inside the logged-in session and get its output back.
On the Mac, Understudy ships scripts/gui-run.sh <cmd>. It hands the command to a LaunchAgent that lives in
the GUI session and returns the output. With that:
- Clicks and keys:
cliclick(wrapped inbun, which holds the Accessibility grant). - Screenshots:
screencapture -x a.png b.png(one file per display). Downscale before reading (sips -Z 1200). osascriptfor app automation.
On Windows, two ways:
- Quick: a scheduled task with
/IT(interactive only), triggered on demand:schtasks /create /tn guirun /tr "<cmd>" /sc once /st 00:00 /it /rl highest /fthenschtasks /run /tn guirun. It's awkward for getting output back (write it to a file). - Better (build this): a small desktop agent, a Bun script started at logon by Task Scheduler ("run only
when user is logged on", "run with highest privileges"). It listens on
127.0.0.1with a token and offersrun(command in the desktop session, returns stdout),screenshot(all monitors, PNG, downscaled),click x y,type text,key combo(Win32SendInput), andwindows(list with titles and rects). Then expose those as MCP tools too. The browser service in Part 4 can run inside this same process.
Things that can't be automated on either OS, by design: macOS password dialogs (SecurityAgent ignores
synthetic input; use sudo -n, security unlock-keychain -p, etc.), Windows UAC secure-desktop prompts, and
privacy permission toggles. Route around them with command-line equivalents, or ask the human for that single click.
Part 4: The browser (the part that matters most)
Why not just Playwright/Puppeteer?
Claude's first instinct will be Playwright with a persistent profile. Don't use that for the signed-in browser.
- Google refuses sign-in to any Chrome started with
--remote-debugging-portor automation flags ("This browser or app may not be secure"), and Google sign-in is the key to half the internet. - Bot detection (Cloudflare, hCaptcha, Clerk and others) fingerprints CDP/WebDriver sessions. Suno, banks and ticketing sites will block you or keep challenging you.
- Recent Chrome versions block remote debugging on the default profile, and the branded build ignores
--load-extension.
Playwright with its own bundled Chromium is still great for throwaway jobs: rendering pages, scraping public sites, testing your own web apps. Just keep it away from the signed-in profile, and never have scripts launch the real Chrome app (it fights the real one for the profile, steals the Dock/taskbar icon, and leaks processes).
The design that works (what Understudy does)
- Real Chrome, started normally, with its own
--user-data-dir, which is a separate profile that Remy signs in to once. No debugging port, no automation switches. To every site it looks like a person's Chrome. - A companion Chrome extension (loaded unpacked once via
chrome://extensions→ Developer mode) that talks to a local service over a WebSocket on 127.0.0.1. The extension handles:- Seeing:
chrome.tabs.captureVisibleTabgives a real screenshot of the tab. - Reading:
chrome.scripting.executeScriptin the page's isolated world (pages can't see or tamper with it) returns the page text plus every visible link, button and field with its click coordinates. Thisread_pagetool is what Claude should use 90% of the time, because it's far cheaper and more reliable than reading pixels. - Scripting:
run_js(viachrome.userScripts) for the fiddly widgets.
- Seeing:
- Acting with real OS input, not synthetic DOM events. Many sites ignore
element.click()because those events haveisTrusted: false. Understudy sends real keyboard and Accessibility events to Chrome's process. On Windows, useSendInputat screen coordinates. Convert from page coordinates using the window's position, the browser chrome height anddevicePixelRatio. - Typing at human pace, newlines as Shift+Enter, optional submit with Enter.
- Safety checks before each action: refuse if the URL changed since the screenshot the coordinates came from
(
stale_observation), or if the screen is locked. - Sessions with their own tabs, so several subagents can work at once. Each passes an
agentname on every call, gets its own tab, and actions are serialized through one lock. - Per-client API keys with scopes (read / navigate / input / script) and optional allowed-site lists.
- An audit log of every action (JSONL per day). It lets you prove afterwards that, for example, nothing was posted to LinkedIn.
- A password vault +
type_password(Part 5). - An MCP server so Claude Code gets all of the above as tools. Use a small stdio relay
(
claude mcp add … -- bun …/main.ts mcp) rather than direct HTTP, because the relay survives service restarts and dropped tunnels.
Understudy's Mac-specific extras: the Chrome window lives on an invisible virtual display and input goes to the
Chrome process without moving the real cursor. That lets someone use the Mac while Claude browses. On a
dedicated Windows box you can skip that. Put Chrome on the real screen and let SendInput move the actual mouse.
Nobody else is using that machine, and it's nice to watch Claude work over VNC anyway.
4A. Quickest start on Windows: Claude in Chrome
Anthropic's Claude in Chrome extension acts in a real Chrome with real sign-ins, and Claude Code can drive it
(check the current docs for claude --chrome and how it connects). Run Claude Code on the box in that case,
since the extension talks to a local Claude Code. That's the fastest way to see the value on day one. Build the
Part 4 service when you want the vault, multi-agent tabs, audit log and access from Remy's PC.
4B. Mac box: install Understudy
Understudy is Xavier's private repo (X4vier/understudy); ask him for access. The README covers everything; in short:
git clone git@github.com:X4vier/understudy.git ~/understudy && cd ~/understudy
bun install && bun link
understudy setup # then grant Accessibility to the bun path it prints
understudy service install # runs at login, auto-restarts, auto-updates from main
understudy browser setup-extension
understudy browser use-app "/Applications/Google Chrome Beta.app" # recommended: separate app + Dock icon
understudy browser signin # Remy signs in to his sites, then presses Enter
understudy doctor
Then on Remy's PC: understudy tunnel add box <user>@box.local, create a key on the box with
understudy connect remy-pc, and add the MCP relay as the README shows. The repo's CLAUDE.md and
docs/ explain the internals for Claude.
4C. Windows box: build it
Use Part 4's design as the spec and Understudy's docs/architecture.md, docs/api.md and docs/security.md as
the reference, if Xavier shares them. Suggested order, with a check at each step:
- Chrome launcher with its own profile dir; Remy signs in to Google once. Check: Google sign-in works (proves no automation fingerprint).
- Extension + local WebSocket bridge (accept only the extension's
chrome-extension://origin plus a shared secret). Check: screenshot andread_pageon a test page. - OS input via
SendInputwith coordinate mapping. Check: click a button and type into a field on three different sites, including one React app. - HTTP API + API keys + audit log, then the MCP relay. Check: Claude Code on Remy's PC drives it through an SSH tunnel.
- Sessions/tabs per
agentname, password vault,type_password. - Run it at logon from Task Scheduler with highest privileges, plus a watchdog that restarts it.
Part 5: Sign-ins, passwords and 2FA codes
- Sessions persist in Claude's Chrome profile, so most sites need signing in only once. Treat that profile like a password: the box needs full-disk encryption (FileVault / BitLocker).
- Password vault with
type_password: a localhost-only page where Remy pastes a site's password. Claude then callstype_passwordand the service types the saved password only if the tab is on that site over https, into a focused password field. Claude never sees the password, and a phishing page or prompt injection can't extract it. If no password is saved, the tool returns the vault link for Claude to pass on. Rule: Claude never asks for passwords in chat. - Emailed codes: a Gmail app password (Google Account → Security → App passwords, needs 2FA on) stored in
the OS keychain / Windows Credential Manager, read over IMAP (
imap.gmail.com:993, search withX-GM-RAW). That's much more reliable than clicking through Gmail's web UI. Claude checks the sender matches the site and enters the code only there. - SMS codes (Android): pair Google Messages for web (messages.google.com/web) in Claude's Chrome, and Claude reads codes there. Some banks' codes never reach it. For those, Claude should ask Remy for the code early, before it expires.
- CAPTCHAs: not solved. The real-browser approach makes them rare. When one appears, a human clicks it over VNC.
Part 6: Teaching Claude: the global CLAUDE.md
This is what turns the plumbing into a capability. Put it in Remy's ~/.claude/CLAUDE.md (on Windows:
%USERPROFILE%\.claude\CLAUDE.md) so every session in every folder knows about it. Write it as reasoned
guidance (why, not just what), so Claude can use judgment in cases it doesn't cover. A starting template:
## My machines
Claude Code usually runs on my PC. **box** is a <Mac mini / Windows mini PC> that is purely for Claude:
you have full control there, so do whatever's needed. `ssh box` works non-interactively.
Admin password on box: <…> (box only, never anywhere else). Prefer box for builds, long jobs,
GUI apps and all browser work.
### Browser
The `browser-box` MCP server is a real Chrome on box, signed in to my accounts. You act as me there:
anything you post, send or buy really happens under my name.
- Prefer read_page over screenshots. Subagents pass their own `agent` name on every call.
- Signing in is fine when a task needs it: type the username, then type_password. If none is saved,
send me the vault link. Never ask for a password in chat.
- Emailed codes: Gmail over IMAP (app password in the keychain under <name>). SMS: Google Messages
web in the browser. Bank codes: ask me early.
- Scripts must never launch the real Chrome app or use its profile; use Playwright's bundled
Chromium for throwaway work.
### Desktop control on box
SSH shells can't see the desktop. Run GUI things through <gui-run / the desktop agent>.
Screenshots: <how>. Things only I can click: <UAC / privacy toggles>. Open the right pane, then ask me.
## Rules for acting as me
- Draft any message to a human (email, support ticket, chat) and get my OK before sending.
- Research through the browser is read-only on social sites: never post, comment, like, connect or follow.
- Before moving money, look up the provider's procedure and our past records; don't skip steps.
Show me the payment before confirming it.
- Purchases or anything irreversible or public that I didn't clearly ask for: ask first.
- Forms and questionnaires read by systems: answer as I would if I thought it through carefully, no
need to ask.
Also turn on Claude Code's auto memory, and tell Claude to save site-specific lessons (see Part 8) to memory as it learns them. Each site's quirks get learned once.
Permissions: to let Claude really run things, use bypass-permissions mode (or a broad allowlist) for this
setup. Even then, Claude Code prompts for commands it can't fully parse, such as long heredocs or nested
ssh '…' quoting. Tell Claude to write scripts to files and run them rather than inlining them. A
PermissionRequest hook can auto-approve the rest (Xavier's approves everything except rm).
Part 7: Useful extras (add later)
- A long-job runner: a wrapper that starts a job in the background, tracks progress (
done total messagewritten to a file), and lets Claude poll it with widening intervals. It also flags stalls and overruns. Without one, Claude either blocks for ages on a foreground command or writessleeploops that leak shells. Have Claude state an expected time before running anything, and send anything over a minute through the runner. - A big external drive on the box plus a
stash put/getscript that moves big things off the main PC and verifies the copy. - A
hoststool that reports which machines are reachable and whether someone is using them. - Watching it work: you may enjoy leaving Claude's Chrome window visible on the box's screen and peeking over VNC. Xavier does.
Part 8: Lessons we learned the hard way
- Phantom displays (Mac): Understudy's virtual display used its process ID as the display serial, so every restart registered a "new monitor". After weeks there were ~1,300, and macOS's ColorSync daemon pegged the CPU, lagging the whole machine. Fixed now (fixed serial plus an hourly cleanup job). The general lesson: anything that creates OS-level devices must reuse a stable identity.
- Keep the agent's browser off shared machines. We first ran it on the living-room Mac connected to the TV. The side effects disturbed the family, so it now runs only on the dedicated box.
- System dialogs can open where you can't see them (e.g. on the virtual display, or off-screen). When a screenshot shows nothing but something is clearly waiting, capture every display.
- Native Save dialogs in the agent's Chrome are separate OS windows that the browser tools can't reach. Use OS-level clicks, or avoid downloads through the UI (see Suno below).
- Some custom widgets ignore background clicks. Pattern: focus the element with
run_js, then press Enter; or call.click()fromrun_jsfor plain buttons; or use the link's URL directly. - Rich text editors (Lexical, ProseMirror, Draft.js) ignore programmatic value setting and
execCommand. Click into them and use real typing. Plain<input>/<textarea>in React apps need the native value setter plus aninputevent. - Gmail's web UI is hard to drive. Use IMAP for reading mail.
- Self-grading: Claude tends to call its own work "done" and grade it generously. Ask it to compare against the goal and state the gaps bluntly first.
Site notes: Suno (the example you asked about)
- Sign in once with Google in Claude's Chrome. Suno blocks automated browsers, so this only works with the real-browser setup.
- Lyrics box is a Lexical editor: clear the form (trash → Confirm), click the empty box, then
type_text(newlines OK). The style field is a textarea: native value setter +inputevent. - Downloads never reach disk from the agent's tab. What works: unlock the song (More options → Download →
"Unlock & Download", which uses one of your monthly downloads). Then, from inside the page,
fetchhttps://studio-api-prod.suno.com/api/download/clip/<id>?format=m4awith headerAuthorization: Bearer <value of the __session cookie>. It returns a signed URL;curlthat. Space requests out to avoid rate limits. - The playback stream URLs are encrypted, so don't bother with those.
- Bracketed cues within sections (e.g.
[soft, whispered]) and style wording like "sung, melodic" improve takes a lot.
Suggested first session
Remy, once the box exists, open Claude Code on your PC and paste:
Read this guide (attached). We're setting up <Mac / Windows> box at
. Work through Part 2 for that OS, then Part 3, then Part 4 (<4B / 4A then 4C>), then write my global CLAUDE.md from Part 6. Before each step, say what you're about to do; when you need me to click something or sign in, tell me exactly what and where. Verify each layer works before moving on. Finish by having the browser generate one song on Suno end to end.