Getting Started

Your first session
in under 10 minutes.

Install the Mac companion app, run your AI agent as you normally would, and start watching it from your phone. This guide walks you through every step, no experience with AI agents required to follow along.

macOS 13+ iPhone or Android Claude Code, Codex, Gemini CLI, or Grok ~10 minutes

How it all works

Your AI agent (Claude Code, Codex, Gemini, or Grok) runs in a terminal on your Mac, exactly as it always has. Nothing about that changes.

The Agents At Work macOS companion app watches that terminal session using tmux, a standard terminal tool that lets multiple programs observe the same terminal window at once. The app reads the session output, intercepts tool calls before they execute, and forwards everything to your phone over the internet via Firebase.

When the agent needs a decision, such as whether to run a command, your phone buzzes. You see exactly what it wants to do, then tap Yes or No. The answer goes back to the Mac instantly, and the agent continues.

Your account lives on the Mac. The mobile app has no separate sign-in, it links to the Mac by scanning a QR code once. That single scan both authenticates the phone and sets up end-to-end encryption, so conversation content is encrypted before it leaves your Mac. Firebase never sees your prompts or responses in plaintext.

🖥
Your Mac
agent runs inside tmux · hooks fire on every tool call
hooks → daemon → Firestore
☁
Firebase
real-time sync + push notifications via FCM
live feed + push alert
📱
Your Phone
approve · watch · send messages · step away

Your tap travels back the same path: phone → Firestore → daemon → typed into the agent's terminal.

  1. 1

    Install the macOS companion app

    Download AgentsAtWork.dmg, open it, and drag Agents At Work into your Applications folder.

    On first launch macOS may show a Gatekeeper security dialog. Click Open, the app is notarized by Apple and is safe to run.

    Download AgentsAtWork.dmg →
    Drag AgentsAtWork.app into the Applications folder
  2. 2

    Sign in on your Mac

    The macOS app will ask you to sign in. Two options are available:

    • Sign in with Google: one tap, uses your existing Google account.
    • Email and password: if this is your first time, tap Create account. After signing up, check your inbox for a verification email and click the link before continuing.
    ℹ
    Your account lives on the Mac. The mobile app does not have its own sign-in, it links to your Mac account by scanning a QR code (Step 6). You do not need to create an account on your phone.
    Sign in to Agents At Work on your Mac
  3. 3

    Check that tmux is installed

    Agents At Work uses tmux to observe your agent sessions without interrupting them.

    Think of tmux as a one-way mirror for terminals. Your agent runs on one side and can't see the mirror. The companion app stands on the other side, reading everything the agent does. Without tmux there's no way to watch a terminal session that someone else owns.

    # check if tmux is already installed $ tmux -V tmux 3.4 # any version 3.x or 2.x is fine # if you see "command not found", install it with Homebrew: $ brew install tmux
    ℹ
    You don't need to learn tmux. The companion app handles all tmux interactions automatically. You just need it installed, you'll never type a tmux command yourself.
  4. 4

    Install an AI agent

    You need at least one of the four supported agents installed on your Mac. See the footnotes below for API key and subscription details. Quick install for each:

    terminal Claude Code
    $ npm install -g @anthropic-ai/claude-code
    # or: brew install --cask claude-code
     
    $ claude --version

    Works with a Claude Pro or Max subscription, a direct Anthropic API key, or through AWS Bedrock and Google Vertex AI. Any of these lets you run Claude Code.

    terminal Codex
    $ npm install -g @openai/codex
    # or: brew install codex
     
    $ codex --version

    Requires an OpenAI account with API access. Usage is billed per token, no flat subscription required. An existing ChatGPT Plus account does not include API access; you need to add API credits separately.

    terminal Gemini CLI
    $ npm install -g @google/gemini-cli
    # or: brew install gemini-cli
     
    $ gemini --version

    A Google account is all you need to get started. The free tier includes generous daily limits on Gemini 2.5 Pro. For higher limits or production use, connect a Google AI Studio API key or Google Cloud Vertex AI.

    terminal Grok
    $ curl -fsSL https://x.ai/cli/install.sh | bash
     
    $ grok --version
    # alternative: npm install -g @xai-official/grok

    Requires an xAI account at x.ai. Usage is billed per token based on the Grok model selected. API credits are managed through the xAI console.

    💡
    New to AI agents? Start with Gemini CLI: it has a free tier with no credit card required, just a Google account. Once you're comfortable with the workflow, adding Claude Code, Codex, or Grok is straightforward.
  5. 5

    Start your first session

    There are two equally valid ways to start a session. Pick whichever fits your workflow.

    A From the macOS app
    1. Open Agents At Work on your Mac
    2. Click "Start New Session"
    3. Choose an agent: Claude, Codex, Gemini, or Grok
    4. Select your project folder

    The app opens a terminal, launches the agent inside tmux, and begins monitoring automatically.

    B From the terminal

    Run your agent exactly as you normally would, the app detects it automatically.

    # go to your project $ cd ~/projects/my-app # start any agent $ claude # or: codex # or: gemini # or: grok

    Agents At Work sees the new tmux session within seconds and starts monitoring it, no extra steps needed.

    💡
    For developers Method B is the most natural. You don't change anything about how you work: run claude, codex, gemini, or grok in your project folder exactly as before. The companion app hooks into the session silently.
  6. 6

    Install the mobile app and link your phone

    Download Agents At Work on your phone. You don't need to create an account, your phone links to your Mac by scanning a QR code. This one step also sets up end-to-end encryption.

    iPhone

    • iOS 16 or later
    • Available on the App Store

    Download on the App Store

    Android

    • Android 8.0 (API 26) or later
    • Available on Google Play

    Get it on Google Play

    Link your phone (takes about 30 seconds):

    1. Open the Agents At Work app on your phone and go through the 5 onboarding slides.
    2. On the last slide ("Almost there"), tap Scan QR Code.
    3. On your Mac, click the Agents At Work menu bar icon and choose Link Mobile. macOS will ask for your password or Touch ID first, so a random person at your desk can't generate a pairing code, then a QR code appears.
    4. Point your phone's camera at the Mac's QR code.
    5. You'll see "Linked!" once your phone is connected to your Mac. Your Mac's computer name appears in the app.
    ℹ
    The QR code expires after 1 hour. If you see an "expired" error, just close and reopen Link Mobile from the Mac menu bar to get a fresh code.
    Onboarding: Almost there slide with Scan QR Code button
    Linked! Your Mac appears in the computers list
  7. 7

    Watch it work: your first approval

    With your agent running and your phone linked, ask the agent to do something that involves running a command. For example:

    You: add a unit test for the login function and run it

    When the agent tries to execute the test, your phone will receive a push notification. Tap it, or open the Agents At Work app, to see:

    • The exact command the agent wants to run
    • The conversation context that led to the request
    • Yes and No buttons: one tap is all it takes

    Tap Yes. The approval goes back to the Mac, the command runs, and the conversation continues in real time on your phone.

    Push notification on the lock screen
    Permission prompt with Yes / No buttons
    Live conversation across the projects
    💡
    Not getting notifications? Make sure the app has notification permission on your phone. On iPhone: Settings → Agents At Work → Notifications → Allow Notifications. On Android: Settings → Apps → Agents At Work → Notifications.
    ℹ️
    How notification delivery works Notifications are delivered in real time, typically within 1-3 seconds of an event on your Mac. The service applies automatic rate limiting if a session produces an unusually high volume of events, for example from a misconfigured hook or a runaway loop. Normal agent usage is well within these limits at all times. If you suspect a hook is generating unexpected events, check the session activity in the macOS app or contact support@answersolutions.net.

Tips for getting more out of it

🔄

Run multiple agents at once

Start separate sessions in different project folders simultaneously: Claude on your backend, Gemini on docs, Codex on tests, Grok on another. The mobile app tracks all of them, grouped by Mac.

⚡

Auto-approve mode

Toggle "Allow all for this session" when you trust the agent to work unattended. Every tool call goes through without waiting for your tap. Auto-approve resets automatically when the session ends.

💬

Send a mid-session message

Use the text field at the bottom of any session screen to nudge the running agent: corrections, new context, or a change of direction, without interrupting its flow or restarting the session.

🖥

Connect multiple Macs

Sign in with the same account on other Macs and they appear in the mobile app automatically. Personal plan supports 1 Mac; Pro plan supports up to 5.

📋

Answer from the lock screen

Permission notifications include inline Yes / No action buttons. You can approve or deny without even unlocking your phone, just long-press the notification.

⌚

Approve from your watch

Because Agents At Work uses standard iOS and Android notifications, permission prompts arrive on your Apple Watch or Wear OS watch automatically, no extra setup. Tap Yes or No directly on your wrist and the agent continues, no need to reach for your phone.

🔐

End-to-end encrypted

Prompts and responses live in our database until you reset the session, but we cannot read them. Every conversation is encrypted with a key that is unique to your Mac and generated locally, it never touches our servers. The only time it travels anywhere is when it is embedded in the QR code you scan to link your phone. From that point on, your Mac and phone share a secret that nobody else has, not even us.

🔁

Sessions survive disconnects

If your phone goes offline, the agent keeps running on the Mac. Any missed approvals will queue. Open the app when you reconnect and you'll see everything that happened while you were away.

📱

Unlink or re-link anytime

Got a new phone? Open Settings → Unlink this Phone on your old phone (or skip it, old tokens expire naturally), then scan the QR code from your new phone. The Mac's Link Mobile menu always generates a fresh code.

Updating the macOS app

New versions ship bug fixes and feature updates. Here's how to update safely without losing any running sessions.

Update steps
  1. Download the latest AgentsAtWork.dmg from the download section.
  2. Quit the currently running Agents At Work app: click the menu bar icon and choose Quit. The app can't replace its own files while it's still running.
  3. Open the new .dmg and drag Agents At Work into your Applications folder, overwriting the old version.
  4. Launch the new version. On first launch macOS may show a Gatekeeper dialog, click Open, the app is notarized by Apple.
  5. That's it. The new version automatically reinstalls the latest scripts and hooks, and reconnects to any agent sessions you left running, no need to restart your coding session.
ℹ
Your sessions stay alive. Quitting the app doesn't stop your agent or its terminal session, it only briefly pauses the mobile bridge. The new version reattaches to anything still running within a few seconds of launching, no restart needed on your end.
✓

You're all set.

Your agent is running on the Mac. Your phone is watching.
Step away from the desk.

Download the macOS app FAQ & Support