Getting Started
Your first session
in under 10 minutes.
Install the companion on your Mac or Linux machine, a laptop or a headless server, 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, Grok, or Cursor) runs in a terminal on your computer, a Mac or a Linux machine, exactly as it always has. Nothing about that changes.
The Agents At Work companion, the macOS app or the aaw service
on Linux, 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 your computer instantly, and the agent continues.
Your account lives on your computer. The mobile app has no separate sign-in, it links to the computer 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 computer. 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
On Linux? There is no app to download. Steps 1, 2, and 5A are Mac-specific; everything else applies to both. Jump to the Linux section → for the one-line install, the browser sign-in, and theaawcommand.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 # 3.2 or newer # if you see "command not found": $ brew install tmux # macOS $ sudo apt install tmux # Ubuntu, Debian, Pop!_OS $ sudo dnf install tmux # Fedora, RHELYou don't need to learn tmux. The companion handles all tmux interactions automatically. You just need it installed, you'll never type a tmux command yourself. One exception: RHEL 10 and its rebuilds ship a broken tmux snapshot, see the Linux section. -
4
Install an AI agent
You need at least one supported agent installed on your computer. You have six options: five cloud-based CLI agents and Ollama for running models locally. Quick install for each; the
npmandcurlinstallers work the same on Linux, thebrewalternatives are Mac-only:$ 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.
$ curl https://cursor.com/install -fsS | bash$ cursor-agent --versionRequires a Cursor account at cursor.com. A free tier is available.
# 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. On Linux:
aaw start ~/proj --agent ollama --model qwen2.5, andaaw statuslists the models you have pulled.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, Grok, or Cursor 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, Cursor, or Ollama
- Select your project folder
For CLI agents (Claude, Codex, Gemini, Grok, Cursor), 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, Mac or Linux $ claude # or: codex # or: gemini # or: grok # or: cursor-agent # Linux only: the explicit form $ aaw start ~/projects/my-app --agent codexAgents At Work sees the new tmux session within seconds and starts monitoring it, no extra steps needed. On Linux this is the main way to start sessions, since there is no app.
For developers Method B is the most natural. You don't change anything about how you work: runclaude,codex,gemini,grok, orcursor-agentin your project folder exactly as before, on a Mac or on Linux. The companion 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 computer 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.
On Linux,
aaw loginalready printed the QR code in the terminal;aaw linkprints a fresh one. - Point your phone's camera at the QR code.
- You'll see "Linked!" once your phone is connected to your computer. The computer's 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, or runaaw linkon Linux, 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 your computer, 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 computer. 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, oraaw feedon Linux, or contact support@answersolutions.net.
Linux: the same flow from the command line
There is no app on Linux. A small background service does what the Mac app does,
and one command, aaw, covers sign-in, pairing, and sessions.
It runs headless: close the SSH window or log out, and your sessions stay bridged
to your phone. Steps 3, 4, 6, and 7 above apply unchanged; this section replaces
steps 1, 2, and 5A.
1. Install
One command. It installs into ~/.local/share/agentsatwork with its own
Python environment, puts aaw in ~/.local/bin, and starts a
systemd user service. Nothing goes under /usr, no sudo.
$ curl -fsSL https://agentsatwork.app/install-linux.sh | bash
# it lists anything missing, with the line to fix it, e.g.
Missing prerequisites: tmux python3-venv
sudo apt install -y tmux python3-venv
The installer also makes plain claude, codex,
gemini, grok, and cursor-agent start a
bridged session, the same shell integration the Mac app sets up. Open a new
terminal after installing so your shell picks it up.
2. Sign in and pair
A headless machine has no browser, so sign-in works with a code: the sign-in page runs on any device you like, and the code ties it to the Linux box.
$ aaw login
Open https://agentsatwork.app/link-linux/ and sign in, then enter the code:
Code: ABCD-EFGH
Signed in as you@example.com
Registered this machine as 'my-laptop'.
# ... a QR code, scan it with the phone app ...
- Open agentsatwork.app/link-linux on your laptop, the Linux desktop, or your phone, and sign in with Google or email. It shows a one-time code, valid for five minutes, with a copy button.
- Type the code into
aaw login. The machine is registered under its hostname;aaw login --name build-boxpicks another name, andaaw register --namerenames it later. - Scan the QR code printed in the terminal with the phone app (Computers list, QR icon at the top right). Same as on the Mac, this one scan links the phone and sets up end-to-end encryption.
aaw login: a Linux monitor, or the laptop window you are SSHed
in from. It is over a hundred characters wide, so if it wraps, widen the terminal or
zoom out (Ctrl and minus) and run aaw link for a fresh one. The sign-in
page never shows a QR code, so opening it on the phone itself is fine.
3. Start a session
$ cd ~/projects/my-app && claude # exactly as on a Mac
# or the explicit form: picks the agent, attaches to its tmux session
$ aaw start ~/projects/my-app # the only installed agent, or Claude
$ aaw start ~/projects/my-app --agent cursor # Cursor
$ aaw start ~/projects/my-app --agent codex # Codex alongside, as my-app-codex
$ aaw start ~/projects/my-app --agent ollama --model qwen2.5 # local model, no terminal
# day to day
$ aaw status # sessions, daemons, service
$ aaw feed my-app -f # follow a session's feed in the terminal
$ aaw mobile-mode on # route permission prompts to the phone
$ aaw stop my-app-codex # stop one session, the others keep running
$ aaw --help # every command, with examples
Your terminal is attached to the agent's tmux session. Detach with
Ctrl-b then d; the session keeps running, and
tmux attach -t =cb-my-app brings it back. From here on it is Step 7:
ask the agent to do something, and answer the prompt on your phone.
4. Keep it running
The service starts at login and restarts itself if it dies. On a server you rarely log into, tell systemd to keep your user session alive across logouts and reboots:
$ loginctl enable-linger $USER
$ systemctl --user status agentsatwork-supervisor
$ journalctl --user -u agentsatwork-supervisor -f # its log
$ aaw update # newer builds
tmux on RHEL 10
RHEL 10 and its rebuilds ship a 2023 snapshot of tmux that crashes the moment
anything reads a terminal pane, which the bridge does constantly. The installer
detects it and prints how to build tmux 3.5 into /usr/local/bin.
Ubuntu, Debian, and Fedora packages are fine.
Called "localhost" on the phone?
The machine registers under its hostname. Rename it any time with
aaw register --name my-box; the phone updates within a minute.
Sessions from the phone
A stopped project can be restarted from the phone, and /restart
works in the feed. The service picks the request up and brings the session
back under the same name, headless.
Mac and Linux side by side
Sign in with the same account on both. The phone shows each computer with its
own sessions; Personal covers one computer, Pro up to five, in any mix.
Ollama works on both: the Mac app's Ollama tab, or aaw start --agent ollama.
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 computer 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 computer: 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 machine with 8 GB of RAM; larger models (14 B, 32 B) give noticeably better results with 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 or a Linux box with a large GPU.
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.
aaw on Linux, or from your phone.
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 computer.
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 computers
Sign in with the same account on other computers, Mac or Linux, and they appear in the mobile app automatically. Personal plan supports 1 computer; 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 computer 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 computer 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 your computer. 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. Link Mobile on the
Mac, or aaw link on Linux, always generates a fresh code.
Updating Agents At Work
New versions ship bug fixes and feature updates. Here's how to update safely without losing any running sessions, on a Mac and on Linux.
- 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.
- Run
aaw update. It checks the release manifest, downloads the new build, verifies its checksum, reinstalls, and restarts the background service. - Running sessions are untouched: the service reattaches to them within seconds, exactly like the Mac app.
You're all set.
Your agent is running on your laptop, your home server, or a cloud VM.
Your phone is watching.
Step away from the desk.