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.
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 tap travels back the same path: phone → Firestore → daemon → typed into the agent's terminal.
-
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 →
-
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.
-
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 tmuxYou 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
Install an AI agent
You need at least one supported agent installed on your Mac. You have five options: four cloud-based CLI agents and Ollama for running models locally. Quick install for each:
$ npm install -g @anthropic-ai/claude-code# or: brew install --cask claude-code$ claude --versionWorks 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.
$ npm install -g @openai/codex# or: brew install codex$ codex --versionRequires 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.
$ npm install -g @google/gemini-cli# or: brew install gemini-cli$ gemini --versionA 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.
$ curl -fsSL https://x.ai/cli/install.sh | bash$ grok --version# alternative: npm install -g @xai-official/grokRequires 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.
# install Ollama (official installer)$ curl -fsSL https://ollama.com/install.sh | sh# recommended: agentic model (reads/writes files, runs commands)$ ollama pull qwen2.5# or larger for better results# ollama pull qwen2.5-coder:14b# chat-only models (conversation, writing, Q&A)# ollama pull llama3.2# ollama pull mistralFree and open source. No account or API key needed. Ollama runs as a background service on your Mac. Once it is running, Agents At Work detects it automatically and shows an Ollama tab in the session picker. You choose the model from inside the app.
Two modes: chat and agentic. Any model works for conversation, writing, and Q&A. For agentic tasks — reading files, writing code, running shell commands — use a model from the qwen2.5 or qwen2.5-coder family. These reliably support the tool-calling protocol that lets the agent act on your project files. Other models (mistral, llama3.2, etc.) fall back to chat-only mode automatically.Not a developer? Ollama is a good starting point. There is no API subscription or terminal agent to configure beyond running the two commands above. If you can install a Mac app, you can run a local AI model.Session won't start or Ollama stops responding? Ollama occasionally gets into a stuck state while still appearing to run. Restart it:pkill ollama && ollama servein your terminal, or quit and relaunch the Ollama desktop app. Agents At Work picks it back up within 30 seconds.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
Start your first session
There are two equally valid ways to start a session. Pick whichever fits your workflow.
A From the macOS app- Open Agents At Work on your Mac
- Click "Start New Session"
- Choose an agent: Claude, Codex, Gemini, Grok, or Ollama
- Select your project folder
For CLI agents (Claude, Codex, Gemini, Grok), the app opens a terminal and launches the agent inside tmux automatically. For Ollama, no terminal window opens. The session runs silently in the background and you control it entirely from the app or your phone.
B From the terminalRun 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: grokAgents 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: runclaude,codex,gemini, orgrokin your project folder exactly as before. The companion app hooks into the session silently. -
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.
Link your phone (takes about 30 seconds):
- Open the Agents At Work app on your phone and go through the 5 onboarding slides.
- On the last slide ("Almost there"), tap Scan QR Code.
- 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.
- Point your phone's camera at the Mac's QR code.
- 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.
-
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 itWhen 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.
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.
Using Ollama: Chat mode and Agentic mode
Ollama sessions work differently from the cloud CLI agents. There's no terminal involved; you talk to the model entirely through the Agents At Work app or your phone. What the model can do depends on which model you chose.
Works with any Ollama model, including mistral, llama3.2, phi3, gemma2, and more.
The model responds to your messages in natural language. It doesn't access files, run commands, or interact with your Mac in any way. Think of it as a private, local alternative to ChatGPT that runs entirely on your hardware.
Good for:
- Writing, editing, and proofreading
- Brainstorming and planning
- Summarising documents you paste in
- Q&A on any topic
- Anything where you don't need the model to touch your files
Requires a tool-capable model: qwen2.5, qwen2.5-coder, or qwen3. Detected automatically, no setting to toggle.
The model can take actions on your Mac: read and write files, list directories, and run shell commands. You give it a goal; it works through the steps, shows you what it's doing, and asks for approval before anything potentially destructive.
Good for:
- Summarising a folder of documents into a single file
- Editing, refactoring, or generating code in your project
- Running scripts and reviewing their output
- Multi-step tasks you'd normally do in a terminal
Choosing a model
If you just want to chat, any model works; pick based on how much RAM you want to use. For agentic tasks, the qwen2.5 family is the most reliable choice. A 7 B model runs comfortably on a Mac with 8 GB of RAM; larger models (14 B, 32 B) give noticeably better results if your Mac has 16 GB or more.
qwen2.5:7b
Fast, runs on 8 GB RAM. Good for quick agentic tasks and everyday chat. Best starting point if you're not sure.
qwen2.5-coder:14b
Tuned for code. Better tool-use reliability than the base model. Needs 16 GB RAM. Recommended for code-heavy tasks.
qwen2.5:32b / qwen3
Best reasoning and multi-step accuracy. Requires 32 GB RAM. Worth it on an M-series Mac with unified memory.
How approval works in Agentic mode
Before the model deletes a file, overwrites an existing one, or runs a shell command, it pauses and asks you. You'll see the exact action it wants to take, then choose:
- Yes, approve this one action and continue.
- Yes for this session, approve all future actions of the same type for the rest of this session, no more prompts until you close the session or tap the revoke button in the session window.
- No, cancel the action. The model sees a "cancelled by user" message and decides what to do next.
If you're working from your phone, the prompt arrives as a tap-to-approve card in the Agents At Work app, the same experience as approving a Claude Code or Codex tool call. If you're at your Mac, the prompt appears inline in the session window.
Tips for getting more out of it
Run multiple agents at once
Start separate sessions in different project folders at the same time: Claude on your backend, Gemini on docs, Codex on tests, Ollama on a writing project. 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.
- Download the latest AgentsAtWork.dmg from the download section.
- 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.
- Open the new
.dmgand drag Agents At Work into your Applications folder, overwriting the old version. - Launch the new version. On first launch macOS may show a Gatekeeper dialog, click Open, the app is notarized by Apple.
- 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.
You're all set.
Your agent is running on the Mac. Your phone is watching.
Step away from the desk.