--- name: wireup description: "Give Claude hands inside a program on this computer that it cannot currently reach: a desktop app, a creative tool, a streaming tool, a game utility, a device's companion software. Researches the program and its hardware first, finds and tests every way in, builds a safe read-first bridge, proves every change, widens it to full control, and leaves notes so the next session never starts cold. Trigger on /wireup, \"wire up \", \"hook up \", \"can you control \", \"can you drive \", \"connect Claude to \", \"make work with you\", \"build a bridge to \", or any request to let Claude operate a piece of software it cannot reach today." argument-hint: the program, e.g. "/wireup OBS" or "/wireup Krita, batch export" --- # Wire Up a Program The method for giving Claude hands inside a program on this computer. It was written from real wireups of streaming software, a video editor, a macro deck, a stream bot, gaming peripherals and their companion apps, and every rule below cost somebody time before it was written down. Say what a thing does, in plain words, never what it is made of. The person asking may not write code. Name the one action only they can take, and take everything else off their plate. ## The finish line **A wireup is not done when one slice works. It is done when the user can ask for anything that program can do and get it.** The first slice is how you start, not where you stop. Step 10 is the step that gets skipped, and it is the step that makes the difference. --- ## Rule 0: do not ask the user what they want yet. Steps 1 to 3 come first. The order is fixed: 1. **Step 1**: know the software and the hardware, to mastery. 2. **Step 2**: find every door in. 3. **Step 3**: walk through them and find out which ones are real. 4. **Only then**, at Step 3b, report what is reachable and start building. **Why this order.** A menu written before the research is a menu of guesses. Half the options will be things the program cannot be driven to do from outside, and the one thing the user actually wants may not be on the list at all, because you did not yet know the program could do it. Asking first also quietly hands the user the research: they have to know what is possible in order to answer, and working that out was your job. **They asked for the program to be wired up. That is already the instruction. Go and do the reading.** Do not ask a single question about scope, priority or "which of these first" until Step 3 is done and you can name real, tested capabilities. Being blocked on something only the user can do (a password, a switch, a file they have to pick, a cable) is different, and is always allowed: ask, at any step. --- ## Step 1: know what you are working with, BEFORE you touch anything Poking at the inside of a program before you know what it is costs time and can cost hardware. Read first. A session once went straight for a private channel inside a peripheral's software and only afterwards read the maker's own documentation, which described a supported, official way in that would have been missed. **a. Pin down exactly what is in front of you, software AND hardware.** The version of the app actually installed, and the precise model of every device it drives: keypad, mouse, keyboard, camera, light, deck. Hardware has its own documentation, its own firmware and its own limits, and half the traps live there. Get the model number and the firmware version, not the family name. **b. Read what this machine already knows.** Search your memory, the project folders and any session logs for the program and for every device by name before you research anything. What you find there outranks anything on the web, because it was measured here. **c. Read the current official documentation, the software's AND the hardware's, until you could answer any question about either.** The bar is mastery, not a feature list. Before you touch anything you should be able to answer, without looking anything up again: - What every feature of the software does, and what each one is called on screen. - **How the hardware behaves when nobody is touching it**: does it sleep, how long until it does, what wakes it, what it looks like to the software while asleep, how it reports its battery, what happens when the battery dies, on a reboot, when its receiver is unplugged and plugged back in, whether it pairs to one receiver or many. - What lives **on the device** versus on the computer, and what a firmware update, a software update or a factory reset does to each. - Every physical control on it, its real name, and what it can and cannot be set to. - The limits: value ranges, step sizes, counts, and what the software refuses. A session once researched everything a peripheral app could configure, then told the user their wireless mouse was switched off and asked them to flip its power switch. It was asleep. It woke the instant they moved it, which is how every wireless mouse behaves. The research covered the software's features and skipped how the hardware lives. **Half the "it is broken" moments are the hardware doing exactly what it was designed to do.** If you cannot say what the device does when it is left alone for five minutes, you have not finished this step. Read the maker's own support pages and manuals, for the versions actually installed and the devices actually on the desk. Not memory, not a forum first. Look specifically for: - Everything the software can configure or do: the whole surface, so the door you find later can be judged against what you should be able to reach. - **Any supported import, export, backup, restore, template or sharing format.** These are gold: the maker built them on purpose, they survive updates, and they usually need one click from the user instead of a fight. Look for this before anything clever. - Any command line, scripting hook, plugin system, SDK or developer program, and whether it is real or a dead page. - Anything the maker says does **not** work, does not persist, or does not carry over. **d. Say plainly what is official and what is not.** A maker's page, GitHub or manual is one thing. A forum post, a Reddit thread or somebody's reverse-engineering project is another. Label them. Never let a community claim get written down as a fact. **e. Write it down in the project folder as you go.** This research is the first artefact of the wireup, not a scratch note. It goes into the program's own notes file (see Step 11) with its sources, so no future session pays for it twice. **f. If you send a subagent to do the reading, the brief decides what comes back.** Ask it for the software's features and that is all you will get. Name the hardware questions in the brief, in words: sleep and wake, battery, reconnection, what lives on the device, what an update destroys, the value ranges the software refuses. **g. A claim off the web is a HYPOTHESIS. The device is the authority.** A research pass once came back saying a gaming mouse "has no wired mode and no Bluetooth." That went straight into a reply to the user, who answered that it worked wired or wireless and they were holding it. The device had been awake and answering the whole time and was never asked. The flag the researcher had read meant *the software offers no separate setting for that connection*, nothing about what the hardware can do. So, every time: - **Before a researched fact goes into a document or in front of the user, ask the device.** If you cannot check it, write it down as *unverified*, with that word next to it, and never say it to the user as fact. - **Never state anything about a device that is switched off.** If it has not been connected while you were watching, you know its name and nothing else. Say that. - **A flag named after the software is about the software.** `hasWiredReportRate: false` means the app shows no wired setting. It does not mean there is no wire. - **The user is the other authority, and they outrank the web.** They are holding the thing. When what they say and what you read disagree, they are right and the reading is wrong. Only when that notes file exists do you go looking for a way in. --- ## Step 2: find the door Every program already has a way in. Search in this order, because the order is cost: 1. **A supported import/export format the maker documents.** Cheapest of all, survives updates, and the user imports it with one click. Found in Step 1c. 2. **A live remote-control connection it already offers.** Many streaming and media apps ship a local websocket or HTTP control port. Best when the job is live: switch, mute, move something mid-stream. 3. **A plugin or extension that runs inside the app.** The app must be running, and a plugin loaded this way often **dies on app restart**. Expect to reload it every session and say so up front. 4. **Its own background or batch mode.** GIMP's batch mode, Blender's background mode, LibreOffice's headless conversion. Best for file work. 5. **The private channel the app's own window uses to talk to its background service.** A local pipe or socket, found by reading the app's own code. Closed, obfuscated software usually has one and it works while the app is running. 6. **Its saved files on disk, edited with the app CLOSED.** Button layouts, action lists, scene files, profiles. Proven and cheap, but see Step 7: the app must re-read them. 7. **Driving the app's own window**: its Import dialog, its buttons, through the operating system's accessibility layer (UI Automation on Windows, the Accessibility API on macOS), or through its developer port if it is an Electron app. Slower, but it makes the app do the writing. 8. **A local network API.** Devices count: many smart lights and controllers take plain HTTP on the local network. 9. **Keystrokes into the window.** Last resort only. **"There is no way in" is almost never true.** It has been said about keypads and peripheral settings that turned out to be fully reachable. If the documented routes are dead, read the app's own code. It has to reach its own service somehow, and whatever it does, Claude can do. **Never read the screen to learn the truth.** A screenshot once had Claude call a looping video a webcam and invent a name for the person in it. Ask the program, or read its files. Report every door you found, not just the first: what each can and can't do, and what it costs the user (a program that must be open, a plugin reloaded each session, an app that must be quit to edit). --- ## Step 3: test the doors before you build on one **A door you have not walked through is a guess.** Send each candidate its smallest, most harmless message and see what comes back. A port that accepts a connection and never answers is not a door. A format that imports without error and changes nothing is not a door. Do this before designing anything on top, and write the result (working, dead, or conditional) into the project notes. A door that only works while the app is open, or only before it saves, is a fact the next session needs. --- ## Step 3b: report what is reachable, then build **Asking for the wireup IS the user's permission for all of it.** This step is a report, not a question. Say what is reachable, then do every job on the list yourself, in a sensible order, through Step 10. Stop to ask only for something physical, a password or login only the user has, or anything destructive or irreversible. Before you report, you must be able to say all of this without looking anything up: - What the program can do, all of it. - Which way in actually works, tested, and what it costs the user: a window that has to be open, a setting that has to be switched on, an app that has to be quit. - What can and cannot be driven from outside. Then, in one short message: 1. **Say what is now reachable**, in plain words, in a line or two. The shape of what they can now have, not a feature dump. 2. **Name anything the research ruled out**, in one line, so they do not ask for it. 3. **Name the first slice you are proving**: the smallest useful job, end to end, before widening. Never start with "expose everything." 4. If one of the doors needs the user to do something first (flip a setting, close the app, plug something in), put it in the same message so they do it once instead of twice. If the user steers you toward a particular job, that narrows what gets proven FIRST. It never narrows the wireup. Step 10 is still the finish line. --- ## Step 4: build the "what's there right now" reader before anything else The first thing that gets built is always a read-only snapshot: list the scenes, the buttons, the tracks, the settings, the devices. It pays for itself immediately and it cannot break anything. Three traps this walks into every time: - **A file snapshot is the program's last save, not what's on screen now.** Fine for orientation; before changing anything, ask the live program. - **Some apps hold their real state in memory and only write on exit.** A saved profile can show nothing while the buttons plainly exist. - **A database beside the app is often a cache and goes stale.** Work out which source is the truth for this program and write it down. --- ## Step 5: writing changes - **The real program does the real work.** Never rebuild what the program does in your own code. A home-made version diverges silently and can't handle real files. Build the program's own file correctly, then let the program render, export or apply it. - **One command per action**, plus "show me" commands so Claude can look before it touches. - **Every command can answer in a machine-clean form** (JSON) so any session or any other agent can use it. - **Safe to run twice.** Same command, same result. - **Back up the user's current settings before the first write**, and say where the backup is. - **The undo goes out with the change, in the same breath.** If a move needs a return trip (spin a camera, then spin it back), send both in one batch. A dropped connection between them leaves the user's live stream sideways. - **Write scripts to a file with your file-writing tool, then run them.** Building a script inside a shell heredoc is how Windows paths lose their backslashes. - **First live run goes to a scratch copy**, never to the user's real project. Never install anything while they are live. --- ## Step 6: prove it, don't trust it **A command that reports success proves nothing.** Some editor scripting calls return "true" and do absolutely nothing; one writes a file only on its first call per session and claims success forever after. Hours were lost to each. Proof means one of these: - Read the live state back out of the program and see the change. - Open the file it produced and check it really is what it claims: a PDF that starts like a PDF, a video whose frame actually got darker. - Count the program's or the device's own acknowledgements: every write sent, every write answered. - A/B at **one fixed point**: the same timestamp, the same frame, effect on versus off. Comparing two different spots measures the material, not your change. If the real program isn't installed or isn't running, **fail loudly**. Never let a check quietly skip and report green. **On hardware, nothing is proven until it survives a reboot and a full working day.** A keyboard dial was once declared fixed on eighteen minutes of good behaviour, and three wrong conclusions went into permanent notes inside the hour. --- ## Step 7: when does it re-read? Most "it didn't work" reports are this. Before blaming the change, find out what makes the program pick it up: - Some apps must be **fully quit**. Closing the window only hides them to the system tray, and they never re-read their files. Seven correct buttons once looked like a failed edit for a day. - Many apps read their scene, action or profile files **only at launch**. - A device profile edited on the computer may then have to be pushed onto the device again. - A plugin loaded into a running app is gone after that app restarts. Write the answer into the project notes. It is the single most expensive thing to rediscover. --- ## Step 8: who else is using this thing? Before editing any object, ask what else points at it: - A filter put on a camera source can be shared by **every** scene that uses that camera. - A shared row of buttons (a nav bar) can appear on ten pages; editing it means editing ten files. - One settings store can hold **every** device at once. Restoring it to fix a mouse also rolls back the keyboard and the camera. - A mask image is stretched to whatever it sits on, so the same look may need building twice for a tall layout and a wide one. --- ## Step 9: an update can wipe the hardware A companion-software update once wiped every profile stored on a gaming keypad. The computer's copies survived; the device's did not, and rebuilding them took an afternoon. The same update flashed new firmware and changed how the lights behaved. So, for anything with hardware in it: **back up before any update, know what lives on the device rather than on the computer, and check the device after.** Never let an update run during a session that is mid-build. --- ## Step 10: widen it to full control **This is the step that gets skipped, and it is the whole point.** One proven slice is a bridge with one lane. Keep going until the user can ask for anything the program does: 1. **Map the program's whole vocabulary**: every action type, every trigger, every setting it can hold. Read it out of the program's own files, schema or binary if the docs don't list it. A full vocabulary is what turns a single working import into "build me anything." 2. **Cover the surface you listed in Step 1c.** Work down that list and note which parts are reachable, which are not, and why. 3. **One command per real job**, named the way the user would say it, not the way the software names it. 4. **Write down what cannot be done from outside** and what it would take, so nobody rediscovers it. --- ## Step 11: leave it usable by the next session Not optional, and never offered as a question. **Every wired-up program gets all of these. A wireup missing one is not finished.** | # | What | Why | |---|---|---| | 1 | **A project folder with a notes file** (`CLAUDE.md` or `README.md`) | What this is; the software and hardware versions; the Step 1 documentation findings with their sources; every door and whether it was tested; what is proven versus assumed; how to run it; what is left undone | | 2 | **The snapshot script from Step 4**, in that folder | The first thing the next session runs | | 3 | **A dated work log** (`WORKLOG.md`) | What was done, what was verified versus assumed, what was left unfinished and why. Write it for a reader who has only the file system: another agent, or you in a month | | 4 | **A memory note** | The traps that cost time, in the user's own words | | 5 | **A short skill for the program** (`/`) | A doorway pointing at the folder, not a copy of it: the 30-second commands and the traps. Its description names the program and the words the user would use, so it fires on its own | | 6 | **A line in any index of tools you keep** | So a future session asked "this program is acting up" knows the hands already exist, instead of redoing the research | | 7 | **If a session once said this could not be done, write down that it can** | In whatever file every session reads at start. A capability built and not written down is a capability the next session does not have | **If the program reports on the computer's state** (temperatures, devices, health), every time a session opens it should leave a dated snapshot in the project folder and offer a compare against the oldest one, so a change can be spotted when it happens. --- ## Borrow before building - **Check whether someone has already published a command set or integration for this program,** especially for free and open-source apps. Read it before installing anything, pin the version, and skip any installer that reports usage home or pulls code you have not reviewed. - **Your own earlier wireups are your best templates.** Match the pattern you already have rather than inventing a new shape each time. --- ## Two standing habits - **The user's read of their own setup beats a tidy inference.** They are looking at the screen and holding the device. Ask what they saw or heard before running probes. - **When blocked, say so and ask.** Then wait. Don't quietly drop or narrow what they asked for.