Devices / Mac app

Mac app.

Sensei runs in a browser on a computer at app.kosuke.ai. On a Mac you can also install the desktop app, which adds a menu-bar menu for your Sensei threads. On other computers, you can install Sensei from the browser so it opens in its own window. iPhone and iPad use the Sensei iOS app. Sensei does not open in a browser on a phone or a tablet.

Install the macOS desktop app

  1. Download the installer from app.kosuke.ai/releases/desktop/stable/download. It is a .dmg file that runs on Apple silicon and Intel Macs.
  2. Open the .dmg file and move Sensei into your Applications folder.
  3. Open Sensei.
  4. Sign in as you do on the web.

The window shows the same app as app.kosuke.ai. Links to pull requests, previews and the docs open in your default browser.

Connecting an integration also opens your default browser. When you finish there, the page says whether it worked and offers Open Sensei, which takes you back to Settings > Integrations in the app.

Go back and forward

The desktop app goes back and forward through the pages you opened, as Safari does:

  • On a trackpad, swipe right with two fingers to go back and left to go forward. Each swipe goes one page, and only the page changes: the title bar and the sidebar stay where they are.
  • Press ⌘[ or ⌘← to go back, and ⌘] or ⌘→ to go forward. In a text field, such as the message box, ⌘← and ⌘→ move the cursor to the start or end of the line instead.

A swipe over content that scrolls sideways, such as the session's tabs, a wide table, a code block or a preview, scrolls it instead. Swipes follow the Swipe between pages setting in System Settings > Trackpad > More Gestures, and a mouse wheel never goes back or forward. While a dialog such as Deck is open, ⌘← and ⌘→ stay with it; swipes, ⌘[ and ⌘] still go back and forward.

Permissions

The first time the desktop app finds a permission off, it opens Set up Sensei on this Mac. The two it counts are Accessibility and Screen Recording, and the footer reads, for example, 1 of 2 on. Microphone, System audio and Automation (System Events) are listed too, marked Optional. Pressing a switch opens System Settings, where you turn Sensei on. If Sensei is not listed there, press + and choose it in Applications. Press Done when both are on, or Not now to close the sheet. It does not open again by itself.

Settings > This Mac > Permissions shows every permission at any time, with Full Disk Access added. To turn one off, do it in System Settings.

PermissionWhat it is for
AccessibilitySensei reads what is on screen in your apps and clicks, types, presses keys and scrolls in them. Snippets expand as you type, and Spotlight pastes for you.
Screen RecordingSensei takes a screenshot of a window on the Mac.
Full Disk AccessSpotlight finds files in every folder, and Sensei reads the files you ask it about in the folders macOS protects.
MicrophoneDictation hears you, and a recorded call keeps your side.
System audioA recorded call keeps what the other people say. Needs macOS 14.2 or later.
Automation (System Events)Sensei opens menu bar icons and their menus. macOS asks the first time.

Without Accessibility or Screen Recording, Sensei cannot use the tools that need them, and it says which permission is missing when it tries. Without Accessibility, snippets do not expand as you type, and Spotlight copies instead and tells you to press ⌘V. Without Full Disk Access, Spotlight's file search and Sensei's file tools skip the folders macOS protects.

Use the menu-bar menu

Closing the window hides it. Sensei keeps running in the menu bar, and clicking its icon opens the menu.

Menu itemWhat it does
Open SpotlightOpens Sensei Spotlight. Shown only while no keyboard shortcut opens it.
Open SenseiBrings the window back. Clicking Sensei in the Dock does the same.
Needs youYour Sensei threads that need you, newest first. The number next to the icon is this count, the same as the Deck button in the app. With more than eight, Show All opens the Threads list.
WorkingYour Sensei threads where Sensei, an agent or one of your own sessions is at work now.
Recent ThreadsYour other Sensei threads, most recent activity first.
ProjectsYour projects in every workspace you belong to.
CallsTurns Record Calls and Always Record Calls on or off, pauses it, tries failed transcripts again, opens your recordings in Finder and opens Calls Settings…. See Record calls.
Check for Updates…Looks for a newer version now.
Quit SenseiCloses the app.

Threads from every workspace you belong to are listed and counted. Pick a thread to open it on the Sensei page, or pick a project to open it in the window.

Open Spotlight with a keyboard shortcut

Sensei Spotlight is a panel that finds your Mac's apps, files and Sensei items, answers questions and starts a thread. Until a shortcut opens it, Open Spotlight is the first item in the menu-bar menu. The shortcut is off until you turn it on in Settings > This Mac > Spotlight, so a launcher such as Raycast or Alfred keeps ⌘Space. See Spotlight for the shortcut and everything the panel does.

Record calls

The desktop app can record your calls on this Mac, on macOS 14.2 or later. Record Calls is off until you turn it on in the menu-bar menu's Calls item or in Settings > This Mac > Calls. The audio stays on the Mac. See Record calls to record, transcribe and set it up.

Update the desktop app

The app downloads new versions in the background and installs one only when the app restarts or quits, so an update never interrupts what the Mac is doing. When one is ready, an Update ready card appears in the sidebar. Press Restart to update, or choose the Restart to Update item in the menu-bar menu, which names the new version. Your tasks keep running while the app restarts. If a newer version comes out before you restart, the app downloads it too and the card names the newest one, so one restart is enough.

A Mac nobody has used for 15 minutes restarts into a waiting update by itself: no one at the keyboard, no Sensei tool running on it or holding it, no call being recorded. A window you closed to the menu bar stays closed after it.

Your Mac as a device

While the desktop app is open and signed in, your Mac is a device Sensei can use. Sensei can:

  • Run commands in a shell, and read, write, move and delete files.
  • Take a screenshot of a window.
  • Read an app's accessibility tree, what the app shows on screen, and click, type, press keys and scroll in it.
  • Open apps and websites.
  • Browse in its own Chrome with your sign-ins. See Chrome sign-ins.
  • Use your Reminders, Notes, Calendar, Contacts and Messages, and read where the Mac is. See Apple apps.

The screen tools need the permissions above. Sensei itself uses your Mac without asking.

A task's agent asks first. A card in the task's chat names the Mac, for example "Use MacBook Pro to test this task?", and Sensei tells you why the agent asks. Once you approve, the agent can use the Mac until that Turn ends: screen, keyboard, mouse, shell and files. A later Turn asks again. A request nobody answers expires after 30 minutes. A task's commands write files only in its own scratch folder under ~/KosukeQA, the temporary folders, Xcode's build folders and the paths the project declares, and a delete moves the item to the Trash.

The menu-bar menu has a This Mac item that says its state, such as This Mac: Connected or This Mac: In use, with what Sensei is using. Disconnect stops Sensei from using the Mac until you press Connect.

Settings > You > Devices lists your Macs with their status: Online, In use by Sensei, In use by a task or Offline. On a Mac, Keep this Mac awake while connected lets Sensei reach it on battery while you leave it idle. The screen still turns off, and closing the lid still sleeps the Mac. See Devices.

Apple apps

Sensei can read and change your Reminders, Notes and Calendar, read your Contacts and your Messages, send a message, and read where your Mac is. Each app is off until you turn it on.

  1. In the desktop app on that Mac, open Settings > You > Integrations.
  2. Switch on Apple Reminders, Apple Notes, Apple Calendar, Apple Contacts, Apple Messages or Apple Location. macOS asks once for each.

Reading Messages also needs Full Disk Access, in Settings > This Mac > Permissions. Sending a message works without it. Location needs Location Services on for the Mac.

  • Only your own Sensei uses your Apple apps. A task's agent cannot, even on a Mac you approved.
  • Sensei sends a message only after you approve it. It shows a card with the recipient and the exact text, and your Approve sends that text once.
  • A new event invites nobody. A change to a note adds text at its end and never replaces what the note holds. Contacts are read only.

The commands and their limits are in the Mac reference.

Workspace devices

A workspace can also have a shared Mac, such as a Mac mini, for work that needs a real computer, such as testing an iPhone app or a desktop app. Every task in the workspace can use it, one at a time, with no approval. Settings > your workspace > Devices lists them under Workspace devices. Every member sees the list; only owners and admins add or remove one.

To add one:

  1. On a Mac that stays on, install the desktop app.
  2. In Settings > your workspace > Devices, press Add workspace device. Sensei shows a code that works once, for 10 minutes. Get a new code makes another.
  3. On the Mac, open the Sensei desktop app, choose Workspace device and enter the code.
  4. When the Mac is in, Settings reads that it is a workspace device. Press Done.

A Mac in use by a member's own Sensei stops working with their Sensei once it is a workspace device. Their own tasks can still use it as a personal Mac, after they approve each request.

Each row shows the Mac's name, whether it is Online, Offline or In use by a task, when it was last seen, and its Sensei version, with who added it and when.

ControlWhat it does
Keep awakeOn by default. Tasks can reach the Mac while it is idle: it does not sleep on its own. The screen still turns off, and closing the lid or the power button still sleep the Mac. On battery it uses more power. Only owners and admins change it, while the Mac is online.
RemoveAsks "Remove" the Mac, then Remove device. The Sensei app on it signs out, and no task can use it any more.

Disconnecting from the Mac itself also takes it out of the workspace, and Activity records it. To add it again, an admin needs a new code.

Chrome sign-ins

The browser Sensei uses on your Mac is Chrome, run in the background with no window, on a copy of each Chrome profile you allow. Each thread has its own copy. Your everyday Chrome stays open and yours: Sensei's tabs do not appear in it. Sensei takes the website sign-ins of a profile into its copy, and picks up a new sign-in from your Chrome by itself when a site signs its copy out. The Mac needs Google Chrome in Applications.

Choose the profiles Sensei may use in Settings > You > Devices, with Chrome sign-ins on the Mac. A profile is Allowed until you turn it Off. Turning it off deletes Sensei's copies of it on that Mac and leaves your Chrome signed in. See Chrome sign-ins.

This is also how Sensei reads LinkedIn and X: you connect each one in a Chrome profile on a Mac, and Sensei reads it in its browser there, so that Mac must be online. See Message watching.

Unlock X Chat

When X Chat asks for its passcode, Sensei stops reading your X messages, and the X row says "X chat asks for your passcode." Press Unlock, in Settings or on the Sensei card. The Sensei app on the Mac opens X Watching's own Chrome window at X Chat. Type your passcode into X there, then close the window. Sensei never sees, keeps or sends the passcode. The window closes by itself after 10 minutes, and Stop closes it sooner. Sensei then checks X Chat again. On a phone, the card says "Unlock from your Mac. It opens X Watching's window there."

This Mac settings

Settings > This Mac is in the desktop app only, after the You group. What its pages hold stays on this Mac.

PageWhat it holds
PermissionsThe macOS permissions above. See Permissions.
SpotlightThe keyboard shortcut that opens Sensei Spotlight. See Spotlight.
QuicklinksSites you open from Spotlight by name. See Quicklinks.
SnippetsKeywords you type anywhere that become their text. See Snippets.
ClipboardWhat you copy, kept so Spotlight can paste it again. See Clipboard.
CallsRecord Calls and its settings. See Record calls.

Limits

  • In the desktop app, a swipe over a preview does not go back or forward, and neither do the keys while you are working in the preview. Click outside the preview, then press ⌘[ or ⌘].
  • Record Calls needs macOS 14.2 or later, and its transcripts need macOS 26 or later.
  • The browser tools need Google Chrome in Applications.

Next steps