AtControl
Join the beta

Help · Agents

AtControl and AI agents

Coding agents such as Claude Code and Codex can work for an hour while you are away. AtControl keeps the Mac awake while they work and, when you ask, puts it to sleep or shuts it down once the work is done — and only then, even with several agents running at once.

Setting an agent up is one copied message: the agent reads its instructions from inside AtControl, asks you how it should behave, sets itself up, and checks in. You see it turn green.

This section assumes you already use a coding agent in a terminal or an IDE. It does not assume you know Shortcuts, URL schemes or skills.

How it works, in one paragraph

An agent session is a lease. Before it starts work, the agent registers a session with a task name; AtControl holds the Mac awake, counts the session in the menu bar and lists it in the window’s agent grid and on your phone. When the agent finishes it ends its own session. If you asked for sleep or shutdown, AtControl performs it only after the last agent has finished; another agent still working delays it and the first agent is told deferred. An agent you asked for nothing afterwards has no time limit: it can work as long as the task needs. A session that asked for sleep or shutdown and was never ended — a crashed agent — ends when the session timeout runs out (8 hours by default), and the Mac goes to sleep, so the promise is kept; never a shutdown, and never while you keep the Mac awake yourself. Up to sixteen agents can hold sessions at once.

Asked for sleep too late — the agent is stuck on a prompt, or will only read your message once its current turn is over — you can arm it yourself: choose Sleep instead on the line under the agent card in the menu bar (“Then stays awake” becomes “Then Mac sleeps”), or in the Agents card of the window, or switch on Sleep when the agents finish on your phone. The session then ends with a sleep request however the agent ends it, and comes under the session timeout counted from that moment, so a stalled agent puts the Mac to sleep at the deadline instead of keeping it awake all night. Stay awake takes it back.

With a hook (Codex, Claude Code)

Agents that support hooks can let their host hold the Mac instead of remembering to do it themselves. The hook starts a session when you send a prompt and ends it when the reply is complete — also when the turn stops on an error or an exhausted usage limit. If you asked for sleep, the agent only records it during the turn, and the Mac sleeps after the whole reply has been written and shown, not while a long answer with pictures is still arriving.

What you need

  • A Mac with AtControl running.
  • An agent that can run commands on this Mac: Claude Code, Codex CLI, or any other with a shell tool.
  • The five AtControl shortcuts, installed once from Settings ▸ Agents. AtControl ships them signed; Shortcuts asks before adding each one.
  • Your permission for each shortcut, once. The first time an agent runs one of them, macOS asks you whether it may; choose Always Allow. Allow Once asks again next time, and a shortcut you never allowed cannot run while you are away, so a sleep or shutdown you asked for would not happen. During setup the agent offers to run all five while you are at the Mac.
  • Optional: Python 3 (it comes with the Xcode Command Line Tools). Without it the agent uses the shell version of the same helper. The agent checks; you never choose.

Using it

Say it in plain words, as part of the task:

  • “Fix the failing tests and put the Mac to sleep when you’re done.”
  • “Keep the Mac awake while the export runs; then release it.”
  • “Shut down after this task. If you run out of budget, save a checkpoint and shut down then too.”

The agent (or its hook) registers before the work starts. AtControl stays in the background — an ordinary command never brings the app forward; only a sleep or shutdown request does, so the Mac is never taken away without the app saying so. Every command, and every refusal, is in the journal.

Next