openadapt-tray
openadapt-tray puts OpenAdapt in the macOS menu bar or the Windows and Linux system tray. You can start and stop recordings from its menu or with a hotkey, see whether OpenAdapt Desktop is recording or compiling a recording into a workflow, and see how many of your automations in OpenAdapt Cloud stopped and need a person.
It's for people who use OpenAdapt Desktop and want those controls without opening the app window. The tray doesn't record or run anything itself. OpenAdapt Desktop records, and openadapt-flow compiles and replays workflows. The tray sends them commands and shows what they report.
Quick start
pip install openadapt-tray
openadapt-tray
The OpenAdapt icon appears in the menu bar or system tray. When you select Start Recording, the tray asks for a capture name, starts the installed OpenAdapt Desktop app if it isn't running, and asks it to record.
Without the desktop app, the tray runs, but recording can't start. OpenAdapt
Desktop has no trusted signed build to download yet
(its README explains),
and the openadapt-desktop command that pip installs doesn't open the socket
the tray connects to.
On macOS, the global hotkeys need permission to read the keyboard. Allow the app that starts the tray, such as Terminal, in System Settings > Privacy & Security under Accessibility and Input Monitoring. The menu works without them.
Once OpenAdapt Desktop is signed in to OpenAdapt Cloud, the tray checks for
automations that need attention. It reads the same token from the OS keychain,
or from the OPENADAPT_INGEST_TOKEN environment variable.
The menu
Start Recording (⌃⇧R) Ctrl+Shift+R on Windows and Linux
Recent Captures View opens a capture's folder
⚠ 2 automations need attention shown only when the count is above zero
Open Desktop App
Open Cloud Dashboard
Account: connected · 30 days left or "Account: sign in" when signed out
Pause Sync "Resume Sync" while paused,
"Sync (offline)" when signed out or offline
Settings... opens tray.json
Quit
While OpenAdapt Desktop works, the recording item changes to Starting..., Stop Recording, Stopping..., or Compiling..., and the icon changes color:
| Idle | Starting or stopping | Recording, or an error | Compiling |
|---|---|---|---|
A red dot on the icon means automations need attention. Selecting the
needs-attention item opens the cloud dashboard. If deployment_lane is byoc,
the setting for keeping recordings on this machine, the item opens Teach in
OpenAdapt Desktop instead and never opens the cloud dashboard. Either
tray.json or OpenAdapt Desktop can set it.
PROTOCOL.md describes the local socket, the one cloud request, and how the tray handles the token.
Configuration
Settings... opens tray.json in a text editor and creates it with the
defaults if it doesn't exist. Changes take effect the next time the tray starts.
The file is at:
- macOS:
~/Library/Application Support/openadapt/tray.json - Windows:
%APPDATA%\openadapt\tray.json - Linux:
${XDG_CONFIG_HOME:-~/.config}/openadapt/tray.json
The settings you're most likely to change:
{
"hotkeys": {
"toggle_recording": "<ctrl>+<shift>+r",
"open_dashboard": "<ctrl>+<shift>+d"
},
"stop_on_triple_ctrl": true,
"hosted_url": "https://app.openadapt.ai",
"deployment_lane": "cloud",
"poll_interval_s": 60,
"show_notifications": true
}
- Hotkeys use pynput syntax.
open_dashboardopens the workflow library in OpenAdapt Desktop. stop_on_triple_ctrlstops a recording when you press Ctrl three times, each within half a second of the last.deployment_laneiscloudorbyoc.captures_directoryis the folder that Recent Captures lists. It defaults to~/openadapt/captures.poll_interval_ssets how often, in seconds, the tray checks OpenAdapt Cloud. The minimum is 30.
The token never goes in this file. The file that Settings... creates also
has keys the tray doesn't use: dashboard_port, auto_launch_dashboard,
auto_start_on_login, minimize_to_tray, default_record_audio,
default_transcribe, and hotkeys.stop_recording.
Development
git clone https://github.com/OpenAdaptAI/openadapt-tray.git
cd openadapt-tray
uv sync --extra dev
uv run pytest tests -q
uv run ruff check .
uv run openadapt-tray
src/openadapt_tray/
app.py tray lifecycle, desktop delegation, and click routing
ipc.py client for OpenAdapt Desktop's loopback socket
hosted.py needs-attention poller and lane routing
state.py recording, sync, and badge state
menu.py the menu
icons.py per-state icon tinting
shortcuts.py global hotkeys
keychain.py ingest-token lookup
config.py tray.json
desktop.py finds and starts the installed OpenAdapt Desktop app
notifications.py desktop notifications
platform/ per-OS dialogs and opening tray.json
To try OpenAdapt itself from the command line, start with the OpenAdapt launcher.
Limits
- The tray doesn't record, compile, replay, or check workflow results. It shows what OpenAdapt Desktop and OpenAdapt Cloud report.
- OpenAdapt Desktop's CI tests this tray's socket client against the desktop's server. The two apps haven't been run together end to end from packaged installs.
- The quick start was checked by hand on macOS 15: the tray starts and shows this menu. Recording through OpenAdapt Desktop and the global hotkeys weren't tried. On Windows and Linux, only the unit tests run in CI.
- On macOS, a tray installed with pip sends notifications through AppleScript, so clicking a needs-attention notification doesn't open the dashboard. Notification clicks haven't been tried on Windows or Linux.
- The cloud poller is tested against mocked responses, not a live account.
- There's no installer, and the tray doesn't start at login.
- OpenAdapt Desktop saves its captures in
~/.openadapt/capturesand manages them itself, so they don't appear under Recent Captures by default. Open them from the desktop app. - Account: sign in opens the token page of the cloud dashboard. The tray has no sign-in flow of its own.
License
Metadata
Release files for openadapt-tray 0.3.6
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| openadapt_tray-0.3.6.tar.gz | 289.6 kB | With provenance | Details for openadapt_tray-0.3.6.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| openadapt_tray-0.3.6-py3-none-any.whl | Python 3 | none | any | Details for openadapt_tray-0.3.6-py3-none-any.whl |
Total release size: 358.3 kB
Release files / openadapt_tray-0.3.6.tar.gz
| Download URL | openadapt_tray-0.3.6.tar.gz |
|---|---|
| Size | 289.6 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
48136709bd6289305fa9d2feea32706bfb001114b8b9ac12a3aefeb18b5a12a7
|
|
BLAKE2b-256 checksum How to use checksums |
b47c04819a609c11b5864a97505767bdf6bd6651a4ad0d6334f970850ac57a2f
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 14, 2026.
Transparency logRelease files / openadapt_tray-0.3.6-py3-none-any.whl
| Download URL | openadapt_tray-0.3.6-py3-none-any.whl |
|---|---|
| Size | 68.8 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
cbdafd7b579354301c744a094ff63240b606d19fab0537d1411de1f07d756858
|
|
BLAKE2b-256 checksum How to use checksums |
e1e8c05dd20ce1c6cb54e9116dce4d93b720e1827d5177d0be79459422f3d5f6
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 14, 2026.
Transparency logSecurity for openadapt-tray 0.3.6
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for openadapt_tray-0.3.6.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 14, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.