The macOS accessibility API is single-tenant, and your second agent is the one who finds out

Why the AX surface is single-tenant in the first place

The accessibility tree itself is a perfectly fine multi-reader surface. AXUIElementCreateApplication followed by a BFS walk over kAXChildrenAttribute is read-only and process-safe. Two agents can walk two trees at the same time and neither blocks the other. Tree reads are not where contention lives.

Contention lives in the act of acting. The set of resources that AX automation actually drives is global by OS design:

None of these resources have a notion of multi-tenancy. macOS does not say "this CGEvent click belongs to agent A and that one to agent B." It says: here is the cursor, here is the foreground, here is the event tail, good luck.

What actually breaks when two agents share one Mac

The failure modes are not theoretical. They are what happened the first time we tried to run a Reddit agent and a Twitter agent concurrently from the same Claude Code workspace, both driving real Chrome via the same MCP layer.

The naive setup, and the 30-line mutex that fixes it

Most people who hit this for the first time try to fix it in agent code: they add an internal queue, they add a Swift actor, they add retry logic. None of that helps when the second offender is a completely different process. The mutex has to live OUTSIDE the agents, in a place every agent has to pass through to act. Hooks are that place.

#!/bin/bash
# What "running multiple agents" looks like before any contention thinking.
# Each agent independently decides it owns the foreground.

# Agent A
osascript -e 'tell application "Google Chrome" to activate'
# 50ms later, agent B fires its own activate against Slack.
osascript -e 'tell application "Slack" to activate'
# Agent A's CGEventCreateMouseEvent click now lands in Slack.
# Whatever the user was doing also got shoved into the background.
# Nobody logs anything. Nobody notices for 4 hours.

#!/bin/bash
# ~/.claude/hooks/playwright-lock.sh (excerpt)
# PreToolUse hook. Acquired before any mcp__playwright.* tool call.

LOCK_FILE="$HOME/.claude/playwright-lock.json"
MUTEX_DIR="$HOME/.claude/playwright-mutex.d"
LOCK_EXPIRY=30      # seconds before a held lock is stale
MUTEX_EXPIRY=5      # seconds before the fs mutex is stale
MAX_WAIT=120        # max seconds to wait for the lock
POLL_INTERVAL=2     # seconds between retries

# Save the user's frontmost app BEFORE we steal focus.
source "$HOME/.claude/hooks/focus-save.sh"

# Atomic acquire via mkdir (only one caller wins per directory).
acquire_mutex() {
  if mkdir "$MUTEX_DIR" 2>/dev/null; then return 0; fi
  # Stale mutex? Check directory mtime against MUTEX_EXPIRY.
  local age=$(( $(date +%s) - $(stat -f %m "$MUTEX_DIR") ))
  if [ "$age" -gt "$MUTEX_EXPIRY" ]; then
    rm -rf "$MUTEX_DIR" && mkdir "$MUTEX_DIR" && return 0
  fi
  return 1
}

# Lock holder is identified by SESSION_ID.
# Same session: refresh. Different session: poll.
# Held by a session that died without releasing: TTL expires after LOCK_EXPIRY.

# PostToolUse hook (playwright-unlock.sh) refreshes the timestamp,
# session-end hook releases the lock.

Three details matter and each one came from getting it wrong first. The atomic acquisition has to be mkdir, not a lockfile-then-write pair, because mkdir is the only POSIX-portable atomic create primitive. The lock JSON has to carry a timestamp so a crashed holder eventually expires (otherwise one OOM-killed agent deadlocks every other agent on the machine forever). And the mutex itself needs its own short TTL (5 seconds in our case) so a process crashed between mkdir and JSON write does not orphan the directory.

The four hook positions, in order

Once you accept that this lives in hooks, the shape of the solution is just four positions in the agent lifecycle. Each one does one thing.

The focus-save / focus-restore pair, in 20 lines

Even with the mutex in place, a single-agent run still leaves the user's frontmost app behind. The user clicked into VS Code, said "run that thing" out loud, the agent grabbed Chrome, ran its chain, and then left the user staring at Chrome instead of their editor. The fix is not in the agent; it is in two short hooks that run before and after every tool call.

#!/bin/bash
# ~/.claude/hooks/focus-save.sh
# Save the user's frontmost app so we can restore it after the
# agent's browser steals focus.

FOCUS_FILE="$HOME/.claude/saved-focus-app.txt"
FRONT_APP=$(osascript -e \
  'tell application "System Events" to get name of first process whose frontmost is true' \
  2>/dev/null)

# Important: do NOT save the agent's own browser as "the user's app"
# or we will restore the agent on top of itself.
if [ -n "$FRONT_APP" ] && [ "$FRONT_APP" != "Google Chrome" ] && [ "$FRONT_APP" != "Chromium" ]; then
  echo "$FRONT_APP" > "$FOCUS_FILE"
fi

#!/bin/bash
# ~/.claude/hooks/focus-restore.sh
# Restore frontmost to whatever the user had before the tool call.

FOCUS_FILE="$HOME/.claude/saved-focus-app.txt"
if [ -f "$FOCUS_FILE" ]; then
  FRONT_APP=$(cat "$FOCUS_FILE")
  if [ -n "$FRONT_APP" ]; then
    # 200ms delay lets the agent's last action settle before we
    # rotate the foreground out from under it.
    (sleep 0.2; osascript -e "tell application \"$FRONT_APP\" to activate" 2>/dev/null) &
  fi
fi

Two non-obvious things. The save script refuses to record the agent's own browser as "the user's app," because otherwise a chain of browser actions would each re-save Chrome and the restore at the end would just leave Chrome up. The restore uses a 200ms delay because the agent's last AX call may not have fully resolved yet; activating a different app inside that window can race the action and lose state.

The case the mutex cannot fix: cron and launchd agents

A serial mutex is the right answer when both agents are users of the same machine and a queue is acceptable. It is the wrong answer when one of the agents is a cron job firing while the user is on a video call. The mutex would let the cron agent acquire, post a click into the user's call, then politely release. Correct behaviour at the AX layer; catastrophic behaviour at the human layer.

The honest fix for this case is a different hook that refuses the tool family entirely when the session has no interactive markers.

#!/bin/bash
# ~/.claude/hooks/block-macos-use.sh
# PreToolUse hook. Blocks mcp__macos-use__* tools in non-interactive
# (cron / launchd) sessions only. Interactive sessions still work.

cat > /dev/null  # consume hook stdin

# Interactive markers: any of these means a user is at the keyboard.
if [ -n "${ITERM_SESSION_ID:-}" ] || [ -n "${TERM_SESSION_ID:-}" ] \
   || [ -n "${TMUX:-}" ] || [ -n "${CLAUDE_CODE_ENTRYPOINT:-}" ]; then
  exit 0
fi

# No interactive markers. Refuse the tool call entirely so a cron
# agent does not steal focus from whoever is using the Mac right now.
echo '{"decision":"block","reason":"macos-use is not allowed in automated pipelines. The agent loop should switch to a sandboxed surface or wait for an interactive session."}'
exit 0

The decision is binary by environment. Interactive terminals (iTerm, Apple Terminal, tmux, the Claude Code CLI itself) all set one of ITERM_SESSION_ID, TERM_SESSION_ID, TMUX, or CLAUDE_CODE_ENTRYPOINT. If none are present, the agent is running in a context with no human at the keyboard, and the only safe answer for an AX-driving tool is to refuse and surface the refusal as a structured {decision: block} to the agent so it can route around to a sandboxed surface or wait.

The same lesson, one layer up: single-instance app enforcement

The hook-level mutex coordinates between agents that already accept they have to share a machine. The same pattern shows up one layer up, inside a desktop AI agent process itself: macOS will happily let a user double-click two copies of the same .app bundle (the one in /Applications and a copy in ~/Downloads), and LSMultipleInstancesProhibited in Info.plist is unreliable across paths. Two prod copies of the same agent then both try to drive the AX API. Inside Fazm, the fix is the same shape, written in Swift instead of bash, and run as the first thing the app does.

// /Users/matthewdi/fazm/Desktop/Sources/InstanceLock.swift
// Called from applicationWillFinishLaunching, before ANY heavy init.
//
// Why: two prod Fazm instances would stomp on the same SQLite db,
// the same ACP bridge, the same Stripe device id, the same global
// hotkey, AND they would both try to drive the AX API.

@discardableResult
static func acquireOrHandoff() -> Bool {
    guard Bundle.main.bundleIdentifier == "com.fazm.app" else {
        return true   // dev build, multiple instances are fine
    }

    if let data = try? Data(contentsOf: lockFileURL!),
       let raw  = String(data: data, encoding: .utf8),
       let peerPid = Int32(raw.trimmingCharacters(in: .whitespacesAndNewlines)),
       peerPid != getpid(),
       kill(peerPid, 0) == 0 || errno == EPERM {

        // Confirm the peer is actually Fazm (not a recycled PID).
        if let peer = NSRunningApplication(processIdentifier: peerPid),
           peer.bundleIdentifier == "com.fazm.app" {
            peer.activate(options: [.activateAllWindows])
            Thread.sleep(forTimeInterval: 0.2)  // let activation deliver
            exit(0)                              // never returns
        }
    }

    // No live peer. Write our PID; SIGTERM/SIGINT/SIGHUP unlink it.
    try? "\(getpid())\n".data(using: .utf8)?.write(to: lockFileURL!, options: .atomic)
    installSignalCleanup()
    return true
}

Three details that took two debugging passes to get right. We use kill(peerPid, 0) for liveness, not flock or any unlink-on-exit hook, because flock does not survive SIGKILL and an unlink hook does not run after a kernel panic; the next-launch staleness check is the only path that works for hard kills. We confirm the peer is actually Fazm via NSRunningApplication.bundleIdentifier before activating, because PIDs get recycled and a recycled PID could belong to anything. And the 200ms Thread.sleep before exit gives AppKit a tick to actually deliver the activation before we tear ourselves down; without it, the user double-clicks the icon, sees the second copy launch, sees nothing happen, and double-clicks again.

Why Swift actors do not save you here

A common reflex on hearing "two agents racing on AX" is to reach for a serial Swift actor or a single GCD queue. It works inside one process. It does nothing across processes. The OS-level focus state is shared by every process on the machine; an actor guarantees serialised access to the AX call inside agent A's codebase, and agent B (a completely different binary, possibly a completely different language runtime) walks in and posts a CGEvent against the same shared event tail without asking.

The right mental model: in-process serialisation handles the case where one agent might race itself (concurrent tool calls inside one session). Cross-process serialisation handles the case where two agents race each other. They are independent problems. You need both. Inside Fazm we serialise per process at the ACPBridge layer. For multi-agent setups outside the app we wire the hook-level mutex described above.

Frequently asked questions