Settings and the Resources page¶
This page lists every control in the Mac's Settings window, Agents ▸ Settings…, pane by pane, the Resources page (not in that window), and the system settings the app on iPhone and iPad depends on.
The Mac's Settings window has panes chosen from one rail down its left side:
Appearance, Sidebar, Account and Mac; then Agent Runtimes and Spending; then Agent Configuration; then
Control plane. Agent Runtimes and Agent Configuration are headings: each runtime
has its own page under Agent Runtimes, and Agent Configuration's pages (Overview,
Instructions, Skills, MCP servers, Plugins and Other files) sit under Agent Configuration,
each with a count and a warning sign on any that needs a look. Project Settings has the
same pages under the same heading, for the project's .agents, between its own General
and Worktrees. The window opens at one size and stays there whichever pane you choose,
so it never jumps. You can resize it larger; it will not go smaller than the size it opens
at. Agents on iPhone and iPad, and the web page, each have a Settings screen with
Appearance (text size) and Sidebar; everything else follows the Mac they are paired
with.
| Device | Pane | Control | What it does |
|---|---|---|---|
| Mac | Appearance | Appearance: System, Light, Dark | Sets the app's look. System follows your Mac, and changes with it. |
| Mac, iPhone, iPad, web | Appearance | Text size: Default, Large, Larger | The size of the app's text on this device only. The terminal keeps its own size. |
| Mac, iPhone, iPad, web | Sidebar | Pinned, Needs You, Working, Unread, each on or off | Which smart groups the sidebar shows, on this device only. All are on at first. A group that is off is not shown: its sessions go to the next group they fit, or under their project. With Needs You off, approvals are not listed in the sidebar. |
| Mac | Account | You: What agents call you, and Pronouns | The name every agent is told to use for you, and to use for itself by its runtime's name, in questions only (a form card, a finished turn that needs your answer, or a question in a reply): "Claude (this agent) will…", "Alex, do you want…?", never a bare "I" or "you". Anywhere else, plain "I" and "you" are fine. Blank uses the first word of your Mac account's full name, shown as the placeholder. Without pronouns, agents use your name or "they". Each server is given the same name and pronouns. Told to an agent once, before its first turn, so one already started keeps what it was told. |
| Mac | Mac | Sleep: Keep this Mac awake while agents are working, and After they stop | On (the default): the daemon holds the Mac awake while an agent is working, then for the time below once the last one stops, so you can reply. Off: the Mac sleeps on its own schedule, including mid-turn; the time you chose is kept and the menu is dimmed. After they stop is Right away, then 1 hour through 8 hours. The default is 1 hour. The screen can still sleep. At 20% battery or below the hold ends anyway. A server has no idle sleep to hold off, and the phone has no control for this. |
| Mac | Mac | Archived agents | How many archived agents there are and how much space they take, and how long they are kept. |
| Mac | Mac | Delete archived agents after: 7 days, 14 days, 30 days, 90 days, Never | How long an archived agent is kept before it is deleted: its conversation and record are removed. The default is 30 days. Never keeps archived agents until you delete them with Delete…. If a change would delete agents at once, you are asked first, with how many and how much space it frees. Each server keeps to the same setting. |
| Mac | Agent Runtimes ▸ each runtime | Runtime status and install controls | Each runtime has its own page. It says where the runtime is, Not on this Mac (with the download's size where the app fetches it), or what it is doing while it installs, with Install, Retry after an install failed, Update when the app carries a newer version of one it installed, or Open install page. Claude's page says whether it runs from the app's own folder, with nothing added to your PATH, or through your own Node. Where its allowance stands is on the Runtimes page, under Activity. |
| Mac | Agent Runtimes ▸ Cursor / Grok | Permission mode, Default or Always-approve | How that runtime asks permission. Default asks before it does something that needs permission. Always-approve answers every permission request for you; questions that are not permission still wait. Each control is independent, survives quitting, and applies to every agent on that runtime — including ones started by a workflow or on a server. The control is still there when the runtime is not installed. Claude, Codex, Gemini, Antigravity and Copilot keep the permission modes they already have under the prompt. |
| Mac | Agent Runtimes ▸ each runtime | Command sandbox: As configured by runtime, On, Off | Whether the runtime runs its commands in its own sandbox, for every agent on it that has no choice of its own. As configured by runtime (the default) adds nothing, so the runtime's own settings decide. On limits what commands can write, and, where the runtime's sandbox covers it, the network; Off lets them run with your own access. Neither changes the permission mode, and the app's own folder and tool rules apply either way. Claude and Grok have all three. Codex's Off is its Full access mode, which also stops its approval prompts, and On takes it out of Full access. Gemini has no On: its sandbox cannot start when the app runs it. Cursor and Copilot say Runtime controlled, because only their own settings reach their sandbox; Antigravity and OpenCode say No sandbox. A change applies from each agent's next turn, on this Mac and on servers. One agent's own choice is the sandbox capsule under its prompt; see Choose a runtime, model and mode. |
| Mac | Agent Runtimes | Install your agents (a sheet at start-up) | Shown when the app starts and a runtime it can install is not on this Mac, with the same rows. Not now or Done puts it away; it comes back only for a runtime it has not offered before. A runtime that is installed but signed out does not count as missing. |
| Mac | Agent Runtimes ▸ Gemini | Paste a Gemini key, Save, Check again, Replace…, Remove | The Gemini API key Gemini agents sign in with, on this Mac and on servers: Google's own sign-in no longer works for individuals. It starts AIza or AQ., from aistudio.google.com/apikey. It says Works, Checking…, No key, or that Gemini refused it and why. Kept in this Mac's Keychain. It is lent to a server only while an agent runs there, and never written on the server; nothing of it is kept by the control plane. |
| Mac | Agent Configuration | Overview | What every agent gets from ~/.agents: a grid of instructions, skills, MCP servers and plugins by runtime, with a count or a tick where it gets them, n of m where some are left out, — where it has no way to take them and ? where it is not checked yet. Needs a look lists each clash, anything left out and any runtime with no way in, and opens its page. Reveal in Finder opens ~/.agents. |
| Mac | Agent Configuration | Instructions, Skills, MCP servers, Plugins, Other files | One page each: what is there, and how each runtime gets it. Skills shows a skill's SKILL.md, has Add skill… to search a marketplace (skills.sh unless you choose another; see Choose marketplaces) and add one, and for a skill added from a catalogue shows From and Taken at, an update mark when its source has changed, and Update… and Remove… (see Add a skill from a catalogue); MCP servers shows your servers, the app's own and those only in one runtime's own config, with env and header names but never their values, and says so when mcp.json cannot be read. Add server… searches the marketplace chosen in its Marketplace menu (GitHub's MCP registry unless you choose another), or with Add by hand… takes a local command or a remote URL and connects to it with Verify before anything is written (see Add an MCP server by hand); a server the app added shows registry and its version, or added by hand, and has Set…, Replace… and Remove… (see Add an MCP server from the registry). A secret that is not set is named, and agents start without that server. A remote server that asks for a sign-in says needs sign-in and has Sign in…; one signed in says signed in and has Sign out (see Sign in to an MCP server). Plugins shows what each contains. Edit opens the file in your editor. See Share skills, instructions and servers with every agent. |
| Mac | Project Settings ▸ Agent Configuration | Overview, Instructions, Skills, MCP servers, Plugins, Other files | The same pages for the project's .agents, committed with it. Instructions are AGENTS.md at the top of the project. The Overview counts what is there, with no grid by runtime, and lists anything that needs a look, such as an mcp.json that can't be read. Other files marks what the app keeps there itself (project.json, pins.json, workflows and the folders it makes as it works). Only for a project on this Mac; on a server Project Settings shows only General. |
| Mac | Spending | Per agent, with an amount, a currency, Set and No limit | The most one agent may spend across its whole life, not one turn. An agent that reaches it finishes the turn it is in and takes no further prompt, so it may end a little over. If agents have already spent this much, the pane says so as you set it. |
| Mac | Spending | Per day, with an amount, a currency, Set and No limit | The most everything may spend in one local day, in every project. When the day reaches it, nothing new starts and no prompt is sent, including a workflow on a schedule. Whatever is working finishes its turn and holds. What you typed waits until the day rolls over. Each server keeps to this limit on its own. |
| Mac | Spending | Tokens per agent, with a number, Set and No limit | The most tokens one agent may use across its whole life, beside Per agent: whichever is reached first stops it. Counts fresh input and output, not cache reads. For runtimes that report tokens and no price (#838). |
| Mac | Spending | Tokens per day, with a number, Set and No limit | The most tokens everything may use in one local day, on the same terms as Per day. |
| Mac | Spending | Today | What today has cost so far and the tokens it has used, and how much is left under Per day and Tokens per day. Shows Nothing yet before anything is spent. |
| Mac | Spending | The most workflows that may run, 1 to 50 | How many approved workflows turned on may run at once, across every project. The default is 10; choosing the value marked (default) puts it back. One turned off or archived takes no place. Past it, a workflow is listed and says how many are already running, and turning another on is refused until you turn one off or archive one. Raising it lets the ones past it run from their next trigger; lowering it stops the last ones, by project folder and then file name. Only a person can change it: agents and workflows can't. Each server keeps to the same number, counting its own workflows. See Workflows ▸ Limits. |
| Mac | Spending | What the limits have stopped | The agents that reached a limit, with what each spent. Shown only when there are some. |
| Mac | Control plane ▸ Clients | The list of clients | Every window, device and browser paired with the control plane, each of which may do everything, and how it reaches the control plane now: connected directly, connected through a Mac (iCloud relay), or when it was last seen. Forget… cuts a client off at once, directly and through the relay. Any client may be forgotten, the last one too. See Connect a window or phone. |
| Mac | Control plane ▸ Clients | Pair a Device… | Shows a code to scan with Agents on an iPhone or iPad. It pairs one device within five minutes, and stops working when you close it. |
| Mac | Control plane ▸ Clients | Pair a Mac… | A code to paste into Agents on another Mac. That window can then do all this one can. |
| Mac | Control plane ▸ Hosts | The list of hosts | This Mac and every server that runs agents for the control plane, online, offline, or Stopped, Starting or Stopping when it runs on a provider's workspace. Each server has one button (Start or Stop for a linked one, Check again for the rest) and a ··· menu: Choose Projects…, Check again, Link to Workspace… or Unlink, Start when used, Stop when idle, and Remove…. Stop asks first while agents are working there. See Add a server and Start workspaces from Agents. |
| Mac | Control plane ▸ Hosts | Add a Server…, Add by Code… | A command to run on a Linux server, or an install over ssh; a code for another Mac's Agents Host. |
| Mac | Control plane ▸ Providers | The list of providers | Each workspace provider and its workspaces, with their state, which host each is linked to, and when they were listed. Add as Host… installs a running workspace over ssh and links it. A provider's ··· menu has List Again and Remove…; removing one leaves its hosts, unlinked. Shown only on a control plane with one copy. See Start workspaces from Agents. |
| Mac | Control plane ▸ Providers | Add Provider… | Pick a kind (Docker, DigitalOcean, Codespaces, Coder, Workstations, your own commands, or an MCP server), then its few fields and any secrets. It is checked and listed before it is kept. See Add a workspace provider. |
| Mac | Project Settings ▸ General | Helpers running, 1 to 10, Helpers not archived, 1 to 20, and Helpers queued, 1 to 20 | Limits on sessions that other sessions start in this project with start_session, counted across the whole project. Helpers running (default 3) counts the ones working, waiting on a question or permission, starting, or waiting to carry on by themselves (blocked on other agents or a time, waiting on events, or waiting for an allowance); finished, stopped and archived ones do not count, nor do ones asking to be archived. Helpers not archived (default 5) counts every one you have not archived. A start that would go over either is queued instead, and the agent is told which limit and which agents hold it: it starts by itself, oldest first, once a place of each kind is free. Helpers queued (default 5) is how many may wait; queued ones count only against it, and take their other places when they start. Past it, a start is refused. Choosing the value marked (default) puts the project back to it. Running can't be set higher than not archived. Lowering a limit stops nothing; it queues the next start. Raising one starts what is queued, if there is now room. Only a person can change these, from the window or any paired phone or browser: agents and workflows can't, through the app's tools. They are saved in the project's own .agents/project.json, which you may commit, so a clone of the project, on this Mac or a server, has the same limits. Only what differs from the defaults is written, and the file goes when everything is back to the default. A value in the file past the maximums is held to them. Opened with File ▸ Project Settings… (Option-Command-comma); on a server it is written in the project's folder on that server. |
| Mac | Project Settings ▸ General | Helpers archived: Sessions may archive the sessions they started, on or off | Whether a session may archive, with archive_session, a session it started in this project once that session's turn has ended, which frees its not-archived place. On by default. Never your sessions and never another session's; you can bring any of them back from Archived. Off, archive_session waits for you to approve archiving it. On, a session started by another whose turn ends Complete or Nothing to do after archive_session is archived without your approval; off, it waits for you to approve it. Only a person can change this, from the window: agents and workflows can't. Saved in .agents/project.json with the helper limits. |
| Mac | Project Settings ▸ General | Low disk space, 5 to 100 GB, and Critical disk space, 1 to 10 GB | When free space on the disk holding this project, its worktrees or the Agents root falls below these, a strip across the top of the window says how much is free and which worktrees are largest, and machine.disk_low is raised for agents' waits and workflows; machine.disk_ok once it climbs back. Low (default 20 GB) also counts as low below 5% of the disk, whichever is more; critical (default 2 GB) is where commands start failing. Looked at once a minute and after each lease is given back. A disk holding several projects goes by the highest line any of them sets. Saved in .agents/project.json as "diskSpace": {"lowGB": 20, "lowPercent": 5, "criticalGB": 2}; lowPercent is set only in the file. Only the Mac's window shows the strip for now. |
| Mac | Project Settings ▸ General | Keep or Undo a change made outside the app | The app writes .agents/project.json and .agents/pins.json itself and keeps a copy of each as you last approved it, outside the project. When one changes some other way (an agent's shell command, a merge or pull), the app goes on using the approved copy and General shows who changed it, for example Lead changed .agents/project.json, with the lines removed and added. Keep uses the change from now on; Undo writes the approved copy back. A change made while no agent turn is running in the project counts as yours and is used at once, unless it is what the project's last commit holds, which waits. While a change waits, the app does not write that file: settings and pins are refused until you choose. The rail shows a dot on General. The same question, with the same lines, Keep and Undo, is asked on the Mac, the iPhone, the iPad and the web page: over the prompt of the session whose agent made the change, or, when no agent did (a merge or pull) or that agent is archived, on the project's own page, where a new session starts. It notifies you as a question from an agent does. |
| iPhone and iPad | Settings ▸ Agents | Local Network | Lets the app reach a control plane on the network you are both on, such as the one on your Mac. Without it, the app reaches it only through the relay. |
| iPhone and iPad | Settings ▸ Agents | Notifications | Lets the Mac tell this device when an agent needs you. When it is off, the device is not chosen. |
Runtimes¶
Runtimes is not a Settings pane either. It is a page under Activity, at the foot of the projects column, and it says where every runtime this app knows stands: whether it is on this Mac, and where its allowance is, as Available, Rate limited · trying again at a time, Out · reset a time · checking after a time, Out since a time · checking after a time, or Credit used up · checking after a time. Under it, where the runtime says so, what is left of its plan, such as 28% left this week · resets Sun 20:39 · as of 14:02. Mark available says it is back before a check does, and asks nothing first, because a wrong mark costs one refused turn. It is shown only: a chat on an out runtime can still be sent a message. The row in the sidebar says how many are out, with a red dot, and says nothing when none are. See Keep going when a runtime runs out.
Above the prompt, the runtime chooser is in the same two runs. A runtime whose allowance is spent is still listed, under Out, and can still be picked, so the way back to it is there when it recovers. What it says under the name is the same line the page gives.
Resources¶
Settings ▸ Resources is where you declare resources: things agents should take turns with that the app can't find by itself, such as build. Each has:
- a name, which agents lease it by;
- a description, which agents read in
list_resourcesand their briefing, and are told to follow: they lease the resource whenever it applies to what they are about to do; - Held by: how many agents may hold it at once, 1 by default. With 2 or more, that many hold it together and the rest wait in line, in order;
- a usual length and a longest length for a lease on it, in minutes. Left blank, they are the app's own: 30 and 240.
Add Resource… declares one, Edit… changes it, and Remove stops declaring it. Anyone holding a resource you remove or shrink keeps the lease until they release it. The screen, simulators and browsers are listed under Found on this Mac, read-only: one agent at a time each. Declared resources belong to this Mac's host, kept in its folder beside its leases, because how many builds a machine can take is that machine's.
The Resources page is not a Settings pane. It is a page of its own, opened from View ▸ Resources (Option-Command-L) or the Resources row at the foot of the projects column. It lists the declared resources first, free or held, with their descriptions, then every resource found on this Mac — each simulator, each installed browser, and the screen — whether it is free, who holds it and since when, when the lease runs out, and who is waiting. A declared resource more than one agent may hold says "2 of 3 held" and names each holder. You can end a lease or take an agent out of a line from here. See Leases on shared resources.
On iPhone and iPad, Resources under Activity shows the same list read-only, and so does Resources under each host on the web page. Declaring, editing and ending leases are on the Mac.
When an agent reaches a spending limit, Raise the limit above the prompt opens the Settings window.