Help · Agents

Setting your agent up

Step 1 — Open the agent setup

Either place shows the same thing:

• the setup assistant on first launch: the tile “An AI agent should hold it awake”;
• Settings ▸ Agents: the first card, Setup — its rows Shortcuts and Your agent.

Step 2 — Add the shortcuts (once per Mac)

“Install 5 Shortcuts…” (assistant) or “Add to Shortcuts…” (Settings). Shortcuts opens and asks Add Shortcut five times. Keep the names. If an older copy of any of them exists, delete it in Shortcuts first — two shortcuts with the same name can send a command to the old one.

The five: AtControl Begin Session · AtControl End Session · AtControl End Session and Sleep · AtControl End Session and Shutdown · AtControl Agent Status.

Step 2½ — Choose the ways in, and the protection

Two switches in the Access card:

Leave Shortcuts on and the URL scheme off unless something of yours needs it. Shortcuts needs no token: only a program already running as you can call it, and such a program could read any token file anyway.

Protection — in the same Access card, shown only while deeplinks are on. A refused link is refused silently (a URL gets no answer); AtControl’s journal records it.

• “Refuse links opened by apps” — recommended, and the default. AtControl checks which program opened the link, which a web page cannot fake, and refuses any app with a window: a browser, Mail, Messages, chat apps, Shortcuts’ “Open URL”. open from Terminal, a script, an agent or a hook passes. Nothing to set up, no secret. What remains: a program already running as you can still run open — the same as with Shortcuts.
• “Require a token” — every link must carry &token=…, which stops everything that does not know it, command-line tools included. The costs: the token is visible to other processes while open runs, each agent that uses links must be given it (so its provider sees it), and you rotate it if it leaks.
• “No protection” — every link accepted. A web page (after one browser confirmation), a link in mail, a message or a document, or a QR code could then put the Mac to sleep, shut it down, or keep it awake so the screen never locks. Only for a Mac nobody else uses.

Step 3 — Copy the message into your agent

“Copy for Your Agent” (the label reads “Copied” for a moment). Paste it into a new session of your agent. Nothing is copied automatically; the clipboard changes only when you press the button.

The message is short. It tells the agent what AtControl is, where its setup guide lives inside the app (…/AtControl for Mac.app/Contents/Resources/atcontrol-agent/SETUP.md), the capability token only if deeplinks are on and set to “Require a token” (otherwise it says no token is required), and to ask its questions first and finish with a check.

When the token is included, the screen says so next to the button:

Includes your token. Paste it only into an agent you trust with this Mac. — Cloud agents send the conversation to their provider, so the token is seen there.

If macOS is running AtControl from a temporary copy (the app is still in Downloads or on a disk image), the button is disabled: “Move AtControl to Applications first. macOS is running a temporary copy.”

Pasting it again into an agent that was set up before is how you start over. The agent first looks for what an earlier setup left — a skill, a section in its instructions, hook entries, an MCP server — lists it, and asks whether to replace it with a fresh setup or keep it. Only after your yes does it remove its old files, tell you which hook or MCP entries to remove, and set itself up from the beginning, asking every question again. Keep, and it only runs the check.

Step 4 — Answer the agent’s questions, watch it check in

The agent first tells you which way in it will use (normally Shortcuts), and that macOS may ask about AtControl’s shortcuts — choose Always Allow (step 5). Then it asks at most three questions, each with a recommended answer — reply “defaults” if you like:

Shutdown is never offered as a default; it happens only when you ask for it in that task.

The agent then creates a small pointer in its own settings (for example a skill folder whose SKILL.md says “read and follow the guide inside AtControl”); and runs a check: it starts and immediately ends a session called “AtControl setup check” — no sleep, no shutdown.

On AtControl’s screen the “Last command” row changes: grey and breathing, “Nothing has arrived yet — listening” while you answer; “Your agent is checking in…”; then green, “Your agent is set up”. A refusal is shown in orange with its reason.

Step 5 — Allow each shortcut once

The first time a program runs one of AtControl’s shortcuts, macOS asks you whether it may. Choose Always Allow, every time:

This matters most for End Session and Sleep and End Session and Shutdown. They normally run for the first time when the work is done, often with nobody at the Mac to answer. A question nobody answers means the shortcut never runs, and the Mac neither sleeps nor shuts down.

So after the check the agent offers to go through all five now. Say yes and stay at the Mac: it runs Agent Status, Begin Session, End Session and Sleep, End Session and Shutdown and End Session once each, and macOS asks about each one you have not allowed yet. Nothing sleeps and nothing shuts down. The agent opens two sessions named “AtControl permissions check”, asks Sleep and Shutdown to end a session that does not exist (AtControl refuses, and the journal shows those two refusals), then ends its two sessions and tells you which shortcuts ran.

You can repeat it at any time: ask your agent to “go through the AtControl shortcuts again”. When it runs without a single question, all five are allowed. If you chose Don’t Allow and the question does not come back, reset that shortcut’s permission in its details in the Shortcuts app, then go through them again.

The agent finishes by telling you what it installed, where, and how to undo it.

If your agent’s sandbox blocks Shortcuts (Codex)

Some agents run their own commands in a sandbox that cannot reach Shortcuts; Codex does. The agent says so during setup and gives you one line to add AtControl’s MCP server to it — you add it yourself, because it lets the agent act outside its sandbox:

codex mcp add atcontrol -- /usr/bin/python3 "/Applications/AtControl for Mac.app/Contents/Resources/atcontrol-agent/mcp/atcontrol_mcp.py"

The Codex app does not put codex on your PATH; use /Applications/ChatGPT.app/Contents/Resources/codex, or the MCP servers section of Codex’s settings. Then start a new conversation. Every sleep or shutdown the agent asks for through the server shows you a confirmation first.

Hooks (Codex, Claude Code)

With a hook, the agent’s host holds the Mac for every turn:

A hook never decides on sleep or shutdown by itself. The agent records your request during the turn in which the work is complete; the hook acts on it once the reply has been fully written. Every new prompt starts again with nothing recorded. Because the Mac sleeps only after the reply, a long answer is never cut off halfway.

You add the hook, like the MCP server; the agent gives you the exact entries with the path filled in. For Codex they go in ~/.codex/hooks.json — four events: UserPromptSubmit, Stop, Interrupt, SessionEnd — and each runs:

/usr/bin/python3 '/Applications/AtControl for Mac.app/Contents/Resources/atcontrol-agent/scripts/atcontrol.py' hook --label Codex

Then open /hooks in Codex and trust the four entries: Codex skips a new or changed hook until you do. Codex also needs the MCP server above, which is how the agent records a sleep request from inside its sandbox. For Claude Code the entries go under "hooks" in ~/.claude/settings.json (UserPromptSubmit, Stop, StopFailure, SessionEnd), with --label "Claude Code".

The hook prints nothing when all is well and a one-line note when AtControl could not be reached; it never blocks or delays a turn. It keeps a small file per conversation and a log in ~/.atcontrol/hooks/.

Updates — what you never have to do

The guide, the rules and the helper scripts live inside the app and update with it. What the agent wrote in its own settings is a pointer, so there is nothing to update there. If you move the app, every AtControl status answer carries the guide’s current location and the agent re-points itself.

The one thing that needs action, and only if your deeplinks require the token: regenerating the capability token (Settings ▸ Agents ▸ Access ▸ Regenerate…). Every deeplink built with the old token is refused until it carries the new one, so update whatever builds them.

Undo, and uninstalling

Delete what the agent created (it told you where): its skill or instructions, and the hook entries and MCP server you added. To stop all agents at once, switch both ways in off in Settings ▸ Agents.

Deleting AtControl does not remove that: it lives in your agent’s settings, where the app never writes. An agent that still points at AtControl reports that it cannot find it and does nothing else.