Overview
Wysebee Agent for Mac is a small app in the macOS menu bar. You pair it with Wysebee, which creates a new agent for this Mac. That agent, and only that agent, can then:
- run the programs you set up in Wysebee, once you allow each one on the Mac;
- run the scripts your skills declare, once you allow each skill on the Mac;
- find, read and, where you allow it, write files in the folders you pick on the Mac;
- and, only if you switch them on, run any program, control the screen, work as a developer, or use Android phones, iPhones and simulators.
The app runs no AI model. Your AI app (Claude, ChatGPT, or the Wysebee website) does the thinking; Wysebee Agent carries out only what you allowed here. See the product page for a shorter tour.
Requirements
- Mac
- Apple silicon (M1 or later)
- macOS
- 11 Big Sur or later
- Account
- A free Wysebee account, at app.wysebee.com
- Download
- wysebee-agent-osx-v0.2.0.dmg
- Distribution
- Signed with a Developer ID and notarized by Apple, outside the Mac App Store
Install
- Download wysebee-agent-osx-v0.2.0.dmg.
- Open it and drag Wysebee Agent onto the Applications folder beside it.
- Eject the disk image, then open Wysebee Agent from Applications, Launchpad or Spotlight.
- A bee appears in the menu bar and the Wysebee Agent window opens. There is no Dock icon: the bee is how you find the app again.
The bee's menu has Open, Pause / Resume and Quit. Closing the window only hides it. To have the app running after a restart, turn on Start at login under Settings.
To update, download the new disk image, quit Wysebee Agent from the bee's menu and drag the new copy over the old one in Applications. Your pairing, approvals and folders are kept.
Pair your Mac
- In the Wysebee Agent window, type a name for the new agent (1 to 60 characters, such as Studio Mac) and click Pair. The window shows a code like
XXXX-XXXX; the copy button copies it. - Sign in at app.wysebee.com, open Devices, choose Pair a device → Pair a Mac and type the code.
- Wysebee creates the agent under that name, and the Mac's window shows it as connected, with the tabs Programs, Folders and Settings.
Pairing always creates a new agent. If the name already belongs to one of your Mac agents that has no Mac now (after an unpair, or a new Mac), Wysebee offers to Reconnect to it instead. The agent keeps its tools, but nothing runs on this Mac until you allow it here again.
The agent itself runs in Wysebee Cloud, so this Mac needs nothing but Wysebee Agent. Talk to it from the Wysebee website, or from Claude or ChatGPT through the Wysebee Assistant connector.
Programs
A program tool is something you define once in Wysebee: which program runs, with which fixed arguments, and which blanks the AI fills in.
- In Wysebee, open the Mac's agent, go to its Tools tab and add Run local program from the Tool library.
- Give it a Tool name (like
make_report) and say What it does: the AI reads this to know when to use it. - Set the Program: a full path, or a program's name (like
gitorpython3). - Add Arguments, each one either Fixed text or a blank Wysebee fills in, with a name and what should go there.
- On the Mac, the program appears under Programs, waiting, with its whole command line. Read it and click Allow.
For example, a convert_document tool with the program pandoc and three arguments: a blank input, the fixed text -o and a blank output. The Mac shows, and runs, exactly:
/opt/homebrew/bin/pandoc {input} -o {output}The rules a program runs by
- The AI sends only the tool's name and the blanks' values. What runs is the copy you allowed on this Mac, with the program's full path as found when you clicked Allow.
- Never a shell: each value is passed as one argument, whatever it holds.
a b; rm -rf ~is just that text. - No input, run in your home folder, stopped after 60 seconds; output and errors each cut at 20,000 characters.
- Change the program, its arguments or a blank's name in Wysebee and it waits for Allow again; the description alone does not count. Remove it in Wysebee and its approval goes too.
- A bare name is looked up on the app's PATH plus
/opt/homebrew/binand/usr/local/bin. If the file is gone later, the program is reported asmissing-programuntil you allow it again.
Skills
A skill is a folder of instructions (SKILL.md) and files you give an agent in Wysebee. Its scripts run only here, on the Mac paired with the agent.
- Give the Mac's agent a skill in Wysebee (its Skills tab).
- Wysebee Agent downloads the skill's files at once and checks each one against its SHA-256. It shows under Skills, waiting, with the scripts its
SKILL.mddeclares (each command line) and its files. Nothing of it runs yet. - Click Allow. The files go into the skill's folder on this Mac and each script's program is found.
A skill declares its scripts in the front matter of its SKILL.md:
---
name: weekly-report
description: Builds the weekly sales report from the CSV exports.
scripts:
- name: build
command: python3 scripts/build_report.py
description: Builds the report; pass the week, like 2026-W46.
---
Instructions for the agent go here.- Only declared scripts run: the script's command, then the call's arguments (at most 30), each one argument, in the skill's folder. Same 60 seconds, no input, output cut.
- A script inside the skill must stay inside its folder; a link or .. that leads out is refused, at Allow and again at every run.
- Change any file in Wysebee and the new version is downloaded at once and waits for Allow. Until then the copy you allowed stays exactly as it was.
- Show in Finder opens the skill's folder. Files you put there yourself (a
.envthe scripts read, say) stay on this Mac, are never sent and are kept when you allow a new version.
Folders
Folders are picked on the Mac, never typed in Wysebee: under Folders, click Add a folder… and choose one in the Mac's own folder picker. Give it a name (the folder's own by default), choose Read only or Read and write, and say what it holds if you like: the AI reads that to know which folder to use.
The agent sees it at once and can find, list, read and (in a read-and-write folder) write files there. There is nothing to approve: you chose each folder yourself. Allow writing / Make read only, Edit and Remove… change it later.
- Text, Word (.docx), Excel (.xlsx, .xlsm, .xls, .ods) and PDF are read as text.
- A picture (.png, .jpg, .gif, .webp) is shown to you in Wysebee and never to the AI.
- Paths are relative to the folder; absolute paths, .. and links that lead out are refused. Writing needs a read-and-write folder, whatever the call says.
- Up to 20 folders. Files read up to 50 MB (a picture 10 MB); a search looks at up to 50,000 entries and skips .git, node_modules, .Trash and __pycache__; every answer is cut at 50,000 characters.
Optional abilities
Under Settings, “What Wysebee may do on this Mac” has five more switches. Each is off until you turn it on and confirm, is forgotten when you unpair, and also needs the matching tool on the agent's Tools tab in Wysebee.
- Run any programTool in Wysebee: Run any program
The agent names a program and its arguments itself, still as an argument list, in your home folder, with the same time limit. A safeguard refuses disk, boot and backup tools, shells and script hosts, anything that runs another program (sudo, env, xargs, launchctl…), system settings, accounts and software tools (brew too), shutdown, rm, inline interpreter code, and git or rsync with arguments that destroy data. It is a safeguard, not a sandbox.
- See and control the screenTool in Wysebee: Screen control
Screenshots of the main display, the mouse and the keyboard, with a red ring drawn where it clicks. macOS asks you to allow Screen Recording and Accessibility for Wysebee Agent the first time.
- Work as a developerTool in Wysebee: Developer access
zsh (the default, as a login shell), bash or sh commands, and reading and writing files anywhere on this Mac, as you. A command runs up to 220 seconds, or as a background job (up to 8 at once) for builds and tests. The safeguard above does not apply here: turn it on only for an agent you trust with your account.
- Use Android phonesTool in Wysebee: Android Development Toolkit
The phones and emulators adb sees: install and launch apps, screenshots, logs and more. adb comes with Android Studio's SDK, or brew install android-platform-tools.
- Use iPhones and simulatorsTool in Wysebee: iPhone Development Toolkit
Through Xcode: boot simulators, take their screenshots, read their logs, open links, switch light and dark; install, launch and remove apps on a simulator or on an iPhone paired with this Mac (Xcode 15 or later for an iPhone). To tap in a simulator, the agent uses screen control on the Simulator window.
How it works
Claude / ChatGPT / Wysebee website
│ asks the agent to use a tool
▼
Wysebee Cloud ── runs the agent, queues the call
▲
│ the Mac asks for work (HTTPS, outbound only)
▼
Wysebee Agent on your Mac ── checks the call against what you allowed,
runs it, sends the result back- The Mac makes the connection, over HTTPS to Wysebee Cloud. It opens no port to the internet, so it works behind any home or office network.
- It keeps one long request open and tells Wysebee its status: paused or not, the programs and skills you allowed, and your folders. A change you make in the window reaches Wysebee at once.
- When a call arrives, the app checks it against its own approvals, runs it, and sends back the answer. A call cancelled in Wysebee is stopped on the Mac.
- If the connection drops, it tries again after 2, 5, 15, then every 30 seconds.
Security and privacy
- Approval lives on the Mac, in the app's own state, and is never taken from Wysebee Cloud. The cloud can ask; only the Mac decides.
- The link's secret is made on the Mac and kept in the macOS Keychain. Wysebee Cloud keeps only a hash of it, and the secret is never sent anywhere else.
- Wysebee Cloud sees the program definitions and skill files (they are the agent's settings), each call's values and the output, kept until read and an hour at most; and your folders' names, paths, permissions and descriptions. What a folder tool reads or writes passes through it like any answer. Nothing else is uploaded from the Mac.
- Blank values and program output are never written to the app's log.
- The app is not sandboxed, so that it can run the programs you allow. It runs as you, with your permissions, and nothing more.
See the Privacy Policy for the full picture.
Pause, unpair, uninstall
- Pause: turn off “Run programs on this Mac” in Settings, or choose Pause from the bee's menu. What is running stops and every call is refused until you resume.
- Unpair: Settings → Pairing → Unpair…. The link ends and the Mac forgets the programs, approvals, folders, skill copies and switches. The agent stays in Wysebee; pair again and reconnect to use it.
- Uninstall: unpair, quit from the bee's menu and move Wysebee Agent from Applications to the Bin. Its data is in the folder below, which you can delete too.
~/Library/Application Support/Wysebee Agent/
state.json pairing, approvals, folders, switches
skills/ the allowed copy of each skill
skill-cache/ downloaded, checked skill files (never run)
agent.log the log, cleared at each launch
Keychain the link's secret (service com.wysebee.agent.osx)Troubleshooting
- macOS says the app cannot be opened.
- Make sure you downloaded it from this site and dragged it to Applications before opening it. The release is notarized by Apple; if macOS still refuses, open System Settings → Privacy & Security and choose Open Anyway, then tell us on Discord.
- I closed the window and the app is gone.
- Closing the window only hides it; the app keeps running in the menu bar. Click the bee in the menu bar, or open Wysebee Agent again from Applications, and the window comes back. Quit is in the bee's menu.
- The code expired, or Wysebee says the name is taken.
- Press Cancel and pair again for a fresh code. If the name belongs to an earlier Mac agent that has no Mac now, Wysebee offers to reconnect to it instead; nothing is allowed on this Mac until you click Allow again.
- A program says missing-program, or cannot be found.
- Wysebee Agent looks for the program when you click Allow: a full path, or a name on the PATH plus /opt/homebrew/bin and /usr/local/bin. Install it or use its full path in Wysebee, then click Allow again.
- A program or skill keeps waiting after I changed it.
- That is on purpose: any change to the program, its arguments or a skill's files needs a new Allow on the Mac. Put it back exactly as it was and it is allowed again.
- Screen control or the iPhone toolkit does nothing.
- Check System Settings → Privacy & Security → Screen Recording and Accessibility both list Wysebee Agent, switched on. For iPhones, Xcode must be installed and selected (xcode-select).
- The agent says the Mac is offline.
- Wysebee Agent has to be running and connected, and not paused. Turn on Start at login in Settings so it is there after a restart.
Support
Email support@wysebee.com or ask in the Wysebee Discord, where questions get answered and bugs get reported. The log at ~/Library/Application Support/Wysebee Agent/agent.log helps; it never holds your secret, blank values or output.
