AGENT OS / READ-ALOUD WALKTHROUGH

Build your own desktop reactor.
Then bring it to life.

Start with the build: the prompt, the source files and the working install steps. Then scroll down for the visual walkthrough of your finished app.

Open Agent OS ↗Download the read-aloud script

You need a Mac and Apple’s command-line developer tools. Use your coding assistant to build from the brief, or download the exact source below. The usage videos later on this page show automated real app commands; interactive rehearsals are labelled.

PART ONE / BUILD IT

From a prompt to a desktop app.

Follow the AI-assisted build, or download the exact working source. Both paths finish with the same local build command.

BUILD · STEP 1 OF 5

Prepare your Mac and workspace

“First, I create a folder for Reactor and open it in my coding assistant. This is a native Mac app, so I need Apple’s command-line developer tools.”

ON SCREEN

Create ~/Downloads/reactor-build in Finder and open that folder in Codex or Claude Code. In Terminal, check the compiler below.

Check: A Swift version appears. If tools are missing, run xcode-select --install, finish Apple’s installer, then check again.

xcrun swiftc --version

BUILD MAP · ILLUSTRATION

Mac + Swift→Source folder→Desktop app

No model API key is needed for Reactor itself. Your coding assistant uses its own account.

BUILD · STEP 2 OF 5

Give your coding assistant the brief

“Next, I describe the app I want to build. I specify the design, the desktop behaviour, the commands and the checks, so the assistant builds more than a visual mockup.”

ON SCREEN

Copy this brief into the coding assistant with the new folder open. Let it create the files and inspect its changes.

Check: Look for Reactor.swift, build.sh and README.md. Generated code can differ; use the working source below if you want this exact version.

Build a native macOS desktop companion called Agent OS Reactor in this workspace. Use SwiftUI for a futuristic cyan HUD and AppKit for a floating panel and menu-bar icon. Keep it visible across Spaces; minus hides it, and the menu-bar icon brings it back. Add one-command-per-tap speech recognition with a pause timeout, plus a typed command field. Support opening an allowlist of apps, Spotlight filename search, local notes, and optional Accessibility dictation into the last external app. Never press Send or execute arbitrary spoken shell commands. Handle permissions, errors and reduced motion. Create Reactor.swift, build.sh and README.md. The build script must compile, locally sign, install to ~/Applications and run parser checks. Test the typed path first; tell me which microphone and external-app checks still need me.

BUILD · STEP 3 OF 5

See what each piece does

“The interface, speech recognition and command handling live in one Swift file. The build script turns that source into an app I can open on my Mac.”

ON SCREEN

Inspect the files in your editor. To reproduce this exact build, download all three files into ~/Downloads/reactor-build, keeping their filenames.

Check: All three files are in the same folder. These downloads are source files, not a prebuilt installer.

Reactor.swift

ReactorView draws the HUD. ReactorModel handles speech and actions. Intent parses commands. AppDelegate manages the floating panel and menu bar.

Download Swift source ↓

build.sh + README.md

The script compiles, writes the app’s permission descriptions, signs locally and checks the parser. The README documents supported commands and limits.

Download build script ↓
Download README ↓

ARCHITECTURE · ILLUSTRATION

Voice or typed words→Intent.parse→ReactorModel.run→Mac action + status

BUILD · STEP 4 OF 5

Build, install and launch

“Now I run the build script. It compiles the Swift code, packages and signs the app locally, installs it in my Applications folder and checks the command parser.”

ON SCREEN

If Reactor is already running, quit it from its atom menu first. Run these commands in Terminal. If you chose another source folder, change the first line.

Check: The parser prints PASS and Terminal prints the installed app path. Reactor opens after the final command.

cd "$HOME/Downloads/reactor-build"
bash build.sh
open "$HOME/Applications/Agent OS Reactor.app"

ACTUAL BUILD RESULT · VERIFIED 18 SEPTEMBER 2026

PASS: eleven command parsing and unsupported-action checks
Installed: ~/Applications/Agent OS Reactor.app

This result was checked on this Mac. The home path is shortened for presentation. A local signature is not Apple notarisation; rebuilding can require permissions again.

BUILD · STEP 5 OF 5

Test it, then make it your own

“Before testing voice, I type a command. That proves the action works. Then I enable speech, try the same command aloud, and check that hiding and reopening the panel works.”

ON SCREEN

Type Open Finder → Run. Then test Listen with microphone and speech access. Try minus → atom menu → Show Reactor. For a design change, ask your assistant to adjust only the HUD, rebuild and repeat the checks.

Check: Typed actions, microphone recognition and external-app dictation are separate checks. The build’s eleven parser checks do not prove microphone or Accessibility behaviour.

YOUR BUILD CHECKLIST · local page checklist, not an automated test Build finishes with PASS Typed Open Finder opens Finder Voice command works after granting access Hide and Show Reactor both work Optional: Type inserts in a supported field without sending

Agent OS navigation requires its separate local server on port 3737. Opening desktop apps and taking local notes do not.

Continue: use your finished Reactor ↓

PART TWO / USE IT

Your finished app, in action.

Now that the companion is built and installed, follow the original visual walkthrough below.

STEP 1 OF 7

Open your desktop companion

“First, I open Agent OS Reactor. It floats above my other apps, so I can keep working in Finder, Chrome or Obsidian.”

ON SCREEN

Open your home folder → Applications → Agent OS Reactor. Drag the panel background to move it.

Check: The Reactor panel is visible. This Mac already has the local app installed.

Follow these written steps in your own running Agent OS. Owner recordings are not included in the member installer.

STEP 4 OF 7

Find a file without digging

“Next, I ask Reactor to find a filename. It searches my home folder’s Spotlight index and gives me matches I can reveal in Finder.”

ON SCREEN

Say “Find” followed by part of a filename. Click a result to reveal it.

Check: Matching filenames appear. The recording searches for the companion’s source file. Unindexed files may not appear.

Follow these written steps in your own running Agent OS. Owner recordings are not included in the member installer.

STEP 5 OF 7

Capture the idea before it goes

“I say “Note” followed by my idea. Reactor adds it to the brainstorm pad. I can read my notes aloud or export them as a text file.”

ON SCREEN

Say “Note record a tutorial about my workflow”. Then use Read or Export.

Check: The note stays on this Mac after reopening Reactor. Desktop notes do not automatically sync to the browser HUD or Obsidian.

INTERACTIVE REHEARSAL · temporary example, not the desktop appYour example idea

Your sample note will appear here.

This rehearsal does not write to your real notes.

STEP 6 OF 7

Dictate into another app

“I click the text field where I want my words. Then I say “Type” followed by the text. I check the target app before inserting anything.”

ON SCREEN

Enable Accessibility in Controls & permissions. Click an external text field, check Dictation target, then say “Type thanks for your help”.

Check: Text is inserted into a supported field. Reactor never presses Send. This needs a hands-on check in your chosen app.

INTERACTIVE REHEARSAL · no external app is controlledWords after “Type”Example text field

Nothing is sent. Real insertion requires Accessibility and a supported field.

STEP 7 OF 7

Hide it, then bring it back

“When I want a clear workspace, I hide Reactor. To bring it back, I click the atom in the Mac menu bar and choose Show Reactor.”

ON SCREEN

Click minus to hide. Menu-bar atom → Show Reactor. Or reopen Agent OS Reactor from Applications.

Check: The panel returns. Hide stops the microphone; Quit Reactor fully exits the companion.

ILLUSTRATED REOPEN PATH

− Hide panel→⚛ Mac menu bar→Show Reactor

Can’t find the menu-bar icon? Open Agent OS Reactor from your home Applications folder.

Full setup, command reference & troubleshooting

First flight

Three steps. Then speak.

01 / LAUNCH

Open Reactor

In Finder, open your home folder → Applications → Agent OS Reactor. On this Mac, the companion is already installed. Drag its background to move it.

02 / ALLOW

Enable your voice

Press Listen for a command. Allow Microphone and Speech Recognition when macOS asks. If denied, find both in System Settings → Privacy & Security.

03 / TRY IT

Open Obsidian

Say “Can you open up Obsidian for me?” Then pause for around two seconds. Reactor stops listening and opens the app if it is installed.

Heard the words, but still waiting? Press Run what I said to execute the displayed phrase immediately. Or type the same command and press Run.

This is a locally installed Mac companion, not an app you can install just by visiting this guide. Other Macs need a build of the companion. This build is locally signed, not a notarized public release.

Your command vocabulary

Small phrases. Useful actions.

Tap Listen before each command. These are supported commands—not a general-purpose AI conversation. Copy buttons copy text; they do not execute actions.

“Can you open up Obsidian for me?”

Opens Obsidian. “Please launch Obsidian” works too.

“Open Finder”

Also: Chrome, Safari, Notes, TextEdit, Calendar, Downloads, Documents.

“Find invoice”

Searches indexed filenames in your home folder. Click a result to reveal it in Finder.

“Note make a video about this”

Appends your words to the saved brainstorm pad.

“Type thanks for your help”

Inserts words into a supported text field in the last active external app.

“Open SEO”

Opens Agent OS’s SEO page. The local Agent OS server must be running.

More Agent OS destinations: Agent OS, Sales, Hermes, Codex, Video, Memory, Higgsfield and Design OS. Other commands: “Read notes”, “Stop listening”, “Hide reactor”. Opening a destination does not submit work to its agent.

Dictation / step by step

Put words into another app.

Expand Controls & permissions → Enable Accessibility for dictation.
Enable Agent OS Reactor in macOS Accessibility settings. Restart it if macOS requests it.
Click the intended text field in your other app. Check Reactor’s Dictation target label.
Press Listen and say “Type” followed by your words.
Review the inserted text. Reactor does not press Send or Return.

Selected text may be replaced. Password fields are excluded. Some apps do not expose editable text through Accessibility; Reactor reports this instead of pretending insertion succeeded.

A two-minute workflow

Capture an idea before it goes.

“Open Obsidian.” Get your workspace in front of you.
“Note record a short tutorial about my workflow.” Capture the thought in Reactor.
“Read notes.” Hear your brainstorm aloud.
Click Export to save a text file wherever you choose.

Desktop notes are stored on this Mac. They are separate from the browser HUD’s notes and are not automatically written to Obsidian.

Make it yours

A companion that stays out of the way.

Hide & reopen

The minus button hides Reactor and stops the mic. Click the atom in the Mac menu bar → Show Reactor to bring it back. Reopening the app also restores its window.

Color & motion

Under Controls & permissions, turn on Solar amber or stay with cyan. Turn animation off for a quieter workspace. macOS Reduce Motion is respected.

Stop everything

The menu-bar atom offers Stop microphone & speech and Quit Reactor. Listening ends after one command, or times out after 45 seconds.

Troubleshooting

When something feels stuck.

It heard me, but didn’t do anything.

Check the recognised phrase. Use a supported command above, pause briefly, or press Run what I said. Natural phrasing is supported for opening apps, including “Can you open up Obsidian for me?” Other actions still use their command words: Find, Note, Type or Read notes. Unrecognised requests display help.

I minimised it and it disappeared.

Click the atom in the Mac menu bar → Show Reactor. If the menu bar is crowded, reopen Agent OS Reactor from your home Applications folder. Hiding the window does not quit the app.

The microphone won’t start.

Check Microphone and Speech Recognition permissions in System Settings → Privacy & Security. Make sure a microphone is connected and selected in Sound settings. Restart Reactor after changing permissions if required. The typed command field remains available.

Dictation doesn’t insert text.

Enable Accessibility for Agent OS Reactor. Click an editable field in the target app and check the target label. Password fields and apps without writable selected-text accessibility support are excluded. In that case use the retained transcript/command text manually. Permission prompts can recur after rebuilding this local app.

File search returns nothing.

Search matches Spotlight-indexed filenames within your home folder, not every file’s contents. Try a distinctive part of a known filename. Unindexed folders and macOS access restrictions affect results.

An Agent OS page doesn’t load.

The desktop companion can run independently, but its Agent OS shortcuts open http://127.0.0.1:3737. Start the local Agent OS server before using those shortcuts.

Can it see my screen or connect to my glasses?

Not in this build. No screen capture or Even Realities connection is enabled. This is a floating command panel with a defined set of actions, not unrestricted computer control or an always-listening assistant.

Know what’s running

Clear boundaries. Honest checks.

Capability	Current behaviour
Desktop overlay	Native floating panel; configured for desktop Spaces and full-screen auxiliary windows. macOS controls protected and system surfaces.
Speech processing	Apple Speech. On-device recognition when supported; otherwise Apple may process audio and require internet. English commands; one command per tap.
Notes	Local app preferences. Manual text-file export. No automatic browser or vault sync.
Verified in development	Compilation, 11 command parser checks, real Obsidian launch from the conversational phrase, Finder/file-search check, window configuration and visual inspection.
Still needs your check	Live microphone recognition and insertion into your chosen third-party text fields after granting permissions.

Version 1.0 · Guide updated 18 September 2026. Built with native macOS frameworks. No additional model API key is required for these commands.