- Instructions: plain-text guidance every new Session started with the Reason receives.
- Conversation: one long-running chat where you give it work.
- Sessions: the tasks it starts, which are filed under it.
- Loops: its scheduled and event-driven work.
- Defaults: the model, reasoning effort and repositories its new Sessions start with.
Your main Reason and named Reasons
Every person has exactly one main Reason in a Workspace. It is listed first, is never deleted, and holds the Sessions and Loops you have not filed under another Reason. Your main Reason stays personal: its Sessions are yours alone, and Workspace owners and admins do not get them either. Named Reasons are the ones you create. You can make one of your own named Reasons your main one, as long as it is personal and has never been shared. It keeps its name, instructions, memory and Sessions, and the former main Reason becomes an ordinary named Reason. In the app, your main Reason’s menu has Replace with different Reason.Give a Reason work
Messaging a Reason is the main way to give it work. Your message goes into its conversation, and the Reason decides how to do the work: it answers, starts Sessions, or sets up Loops. A message sent while the Reason is working steers its running turn. Anyone the Reason is shared with may message it, and each turn acts as the person who sent the message. From a terminal:NAME is a Reason’s name in any case, its id, or main. --queue waits for its running turn to end first, --detach returns once the message is accepted, and --json prints machine-readable output. reason agents is the same command.
Create and set up a Reason
In the app, choose New Reason in the sidebar. The Reason opens on its empty conversation; tell it what it is for. To change a Reason, ask it in its own chat, for example “Rename yourself to Release notes” or “From now on, keep answers short”. The API changes the same settings. What you can set:
A change applies from then on. Sessions that are already running keep what they started with.
Default model
A Reason’s default model is what its new Sessions start on when they pick none. In the app, open the Reason, choose Details, and set Default model under Instructions. Its owner and managers can change it; asking the Reason to change its model does the same.- Workspace default follows the Workspace’s default model in Settings › Models, and changes when that does. A Reason starts here.
- A fixed model is one of Reason’s models or a connected account’s model, with its reasoning effort. The list shows which account each model runs on.
- If the fixed model’s account is disconnected, or no longer has the model, new Sessions start on another model the Workspace can run, when there is one, beginning with its Model priority list. The row says so until you reconnect the account or pick another model.
- A Session that runs on a connected account keeps that account’s model for the Sessions it starts, unless the Reason’s default is another connected account’s model. Work on your subscription does not move to Reason credits.
- A Session created with the REST API names its own model or uses the Workspace’s default.
Share a Reason
- In a Workspace with two or more people, a new Reason starts shared with everyone. In a Workspace of one it starts private.
- Share this Reason on a Reason sets who has it: everyone in the Workspace, people you invite, or only you.
- Sharing has two levels. A Collaborator can chat with the Reason. A Manager can also edit its settings and share it with others.
- Everyone a Reason is shared with can talk to it, start Sessions under it, and read and continue its Sessions and Loops. Each person’s own chat with a team Reason stays theirs.
- Sharing a Reason makes it a team Reason: its Sessions run in the cloud and never use anyone’s personal secrets.
- Your main Reason cannot be shared. To share work from it, use Share on a Session, which makes a new shared Reason.
Delete a Reason
Only a Reason’s owner deletes it, and the main Reason is never deleted. Deleting a named Reason:- Removes it from every Reason list.
- Deletes its Loops, so nothing scheduled or triggered runs for it.
- Removes its own Slack app, if it has one.
- Archives its conversation with its history.
Limits
- A Workspace holds at most 500 live named Reasons. Main Reasons do not count.
- A name is at most 80 characters and instructions at most 16,000.
- A Reason has at most 6 default repositories.
API
Every call needs an API key with the scope shown. See Authentication and scopes.
Creating a Reason allocates no computer and starts no work. Send it a message to start:
end_cursor for its reply.
The Reason’s owner and its managers change its setup. Anyone else it is shared with gets 403 reason_manager_required.

