The short answer
Long Codex runs can take ten minutes, thirty, sometimes more. Once you step away from your desk you really only want to know three things: is it still working, is it stuck on something, and is it done. BotBus handles this with a menu bar app on your Mac that reads your local Codex session data (read-only) and syncs task status, the latest output, and the full conversation on demand to your iPhone and Apple Watch. You don't change how you start Codex. Sessions you open in the terminal or in the Codex desktop app both show up on your phone.
This post is about Codex running on your own computer. Below: how it works, what you can see, when you get notified, and where the limits are.
Why "just watching" is worth solving on its own
It's tempting to think what you want is full remote control. In practice, most of the time you don't need to touch anything. The agent is editing files and running tests according to plan, and you only want to confirm two things: that it isn't sitting on an approval nobody has seen, and that it hasn't wandered off in the wrong direction. If every check means walking back to your desk, you either keep it in the back of your mind all afternoon or come back to find it waited thirty minutes for you.
So a useful progress view has to get three things right:
- Accurate state. Running, waiting for approval, waiting for a reply, completed and failed need to be clearly different.
- Enough detail. "Running" alone tells you nothing. You want to see what it said last and which files it touched.
- Few interruptions. Notify only when it actually needs you, not on every step.
How BotBus reads Codex progress
Read-only watching of local Codex data
Codex stores its session threads in SQLite databases under ~/.codex on your machine. BotBus reads them roughly every two seconds and builds a task list from them: a title (the thread name, or the first 80 characters of your first message), the first 500 characters of the agent's latest message, and the current status. It never writes to ~/.codex and never injects anything into Codex, so it can't get in the way of the session you're running. If you keep Codex data somewhere else, you can point BotBus at that folder in settings.
Syncing to your phone
Tasks are grouped by computer and project and synced to your phone through a relay server. The phone long-polls for updates, so opening the app shows the current state. You can pair several Macs with one phone, and each computer's tasks stay in their own list.
The full conversation, on demand
The list only carries summaries. When you want the whole story, open the task and the phone fetches the conversation: BotBus reads it from Codex's history database, encrypts it, and hands it over. This only happens when you tap in, so your conversations aren't all uploaded in the background. Images you sent and images Codex generated show up in the conversation too. Tool screenshots, such as from a browser or simulator, appear as a one-line text summary.
Seeing what changed in the code
If the task's project is a git repository, the task screen can also show the uncommitted changes in that project: a file list with added and removed line counts, and a side-by-side diff for each file. The entry point only appears when there actually are changes. For deciding whether the agent has gone off track, a diff beats a prose summary every time.
When you get notified
BotBus sends four kinds of notifications: a task needs your approval, a task is waiting for your reply, a task finished, and a task failed. Everything else stays quiet until you open the app.
A few details worth knowing. You have to allow notifications on the phone. No banner appears while the app is in the foreground, since you're already looking at it. On Apple Watch the notification first shows a fixed line of text, and the details are decrypted and shown once you open the watch app. Tapping a notification takes you straight to that task.
There's also a glanceable signal on the Mac itself. The menu bar icon changes with state: its eyes scan left and right while a task runs, its headlights flash in turn when something waits for approval, it briefly smiles when a task finishes, and a number shows how many tasks need you.
What you can do after looking
Watching is where it starts. When the conditions are right, you can also act from your phone:
- Approve or deny. When Codex wants to run a command, edit files or request permissions, an approval card appears. When Codex asks you to choose between options, those show up too.
- Follow up. Add a line to the session, like "tests failed, don't commit yet". You can also switch the model and reasoning effort for that follow-up.
- Interrupt. If it's heading the wrong way, stop the current turn.
All of these need the Mac to be online and the connector to support the action. Claude Code approvals work a bit differently; see how to approve Claude Code from your phone.
Sessions opened in the Codex desktop app
The Codex desktop app runs its own process to manage sessions. To let your phone and the desktop app work on the same session, the first time you set it up finish the current desktop task and quit Codex, then click "Launch Codex" on the Codex row under Local Agents in the BotBus menu. A desktop app launched this way shares one channel with BotBus. For approvals, whichever side answers first wins, and your phone and Mac see the same session.
If the desktop app was already opened on its own, say from the Dock, BotBus shows an exclamation mark button in the same spot. It explains the follow-up limits and offers to restart Codex. Restarting interrupts any task in progress, so it warns you first.
Limits worth knowing
- Viewing works offline; acting doesn't. Tasks already synced stay on your phone after the Mac goes offline, marked as offline. Approving, following up, starting and interrupting all require that Mac to be online.
- Some tasks are view-only. If another Codex process holds the session, a follow-up from the phone reports
already has an active writer. Finish the task on the computer, quit that Codex instance, launch it again from the BotBus menu, then reopen the original task on your phone. No need to start a new session. - It's not a live stream. The list refreshes about every two seconds, and titles and latest output are truncated summaries. Open the conversation for the full picture.
- Notifications depend on the system. Whether pushes arrive also depends on your phone's notification permission and settings.
- Content is end-to-end encrypted, but not everything is hidden. Task titles, conversations, code changes and notification text are encrypted on your devices before they leave, and the key only reaches your phone through the pairing QR code on your Mac's screen. The server can still see device IDs, online status, update times and data sizes, and a task ID's prefix reveals that it came from Codex. Details are in the end-to-end encryption overview.
Can you use it today?
On the computer side there's a Mac app (a menu bar app, macOS 26 or later) and a Linux version (a command-line program for x86_64 and aarch64; see the install guide). You can download both from the website; the menu bar icon and "Launch Codex" described above are part of the Mac app. The iPhone and Apple Watch app is available on the App Store. Windows and Android versions are planned. Besides Codex, BotBus also connects to Claude Code, Hermes, Pi, OpenClaw and DeepSeek Harness, so tasks from different agents show up in one phone app.
FAQ
Does BotBus modify my Codex data?
No. It only reads the databases in ~/.codex to build the task list and never writes to them. Actions you take from your phone go through Codex's own codex app-server interface, not through the database.
Will a codex session I started in the terminal show up?
Yes. As long as the session is recorded in your local Codex data folder, it appears in the list, whether you started it from the terminal or the desktop app.
What does my phone show if my Mac goes to sleep?
The last state synced before sleep, with the computer marked offline. Codex itself doesn't keep working while the Mac sleeps, and syncing picks up again when it wakes.
Can I check Codex progress on Apple Watch?
Yes. The watch gets its pairing from your iPhone and then connects on its own. You can browse tasks, approve and reply without pulling out your phone.
Could my tasks show up on someone else's phone?
No. Only devices you paired with the QR code have the key, and tasks sync only within your own set of computers, phones and watches.