Skip to main content

openadapt-tray

PyPI version Python 3.10+ License: MIT

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
Blue OpenAdapt icon Amber OpenAdapt icon Red OpenAdapt icon Purple OpenAdapt icon

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_dashboard opens the workflow library in OpenAdapt Desktop.
  • stop_on_triple_ctrl stops a recording when you press Ctrl three times, each within half a second of the last.
  • deployment_lane is cloud or byoc.
  • captures_directory is the folder that Recent Captures lists. It defaults to ~/openadapt/captures.
  • poll_interval_s sets 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/captures and 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

MIT

Metadata

Release files for openadapt-tray 0.3.7

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for openadapt-tray 0.3.7
File Size Uploaded Provenance Actions
openadapt_tray-0.3.7.tar.gz 290.1 kB With provenance Details for openadapt_tray-0.3.7.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for openadapt-tray 0.3.7
File Interpreter ABI Platform Actions
openadapt_tray-0.3.7-py3-none-any.whl Python 3 none any Details for openadapt_tray-0.3.7-py3-none-any.whl

Total release size: 358.8 kB

Release files / openadapt_tray-0.3.7.tar.gz

Download URL openadapt_tray-0.3.7.tar.gz
Size 290.1 kB
Tags Source
SHA-256 checksum
How to use checksums
135d48196f8d36bb3bfb39a77a32a3115e4e3409b0a2535046bac121e86f4b41
BLAKE2b-256 checksum
How to use checksums
3d728e6551490ec69ff1411be512d6826e56dfd75a6962076603cc1ff9d53f3c
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 log

Release files / openadapt_tray-0.3.7-py3-none-any.whl

Download URL openadapt_tray-0.3.7-py3-none-any.whl
Size 68.8 kB
Tags Python 3
SHA-256 checksum
How to use checksums
8213766f1cf5fbac50543c92b265d4f318e729b069c6ec642e67ebd7cf94b6eb
BLAKE2b-256 checksum
How to use checksums
95e00d7c1a353c38352528d0dde3a527ca8fa53f99cfb9f702ea6a0991fd1c80
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 log

Security for openadapt-tray 0.3.7

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.

Select from 2 files

Attestation for openadapt_tray-0.3.7.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 log

A 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.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page