Run an agent on a Task

An agent runs a Task in an Environment on a connected machine. The Task keeps the conversation, files, running state, and delivery together while the agent works.

​

Prerequisites

• A Task you can edit.
• An Environment connected to the Task’s Project.
• An online machine for immediate work. Work remains queued when its selected machine is offline.
• For automatic GitHub delivery, a Git repository and a connected GitHub App.

​

Start work

Before filing or starting work, Cogno checks related Tasks across your Workspace. It uses the existing Task for the same outcome and coordinates with its owner when goals or changes conflict. Independent work continues. This is a default agent instruction; it does not automatically reassign or close anyone’s Task. There is no separate run button. To point at part of the conversation, select the words in a reply or in your own message and choose Comment. The comment waits under Comments (N) above the message box, where you can edit or delete it, and goes to the agent with your next message. Only one run can be active for a Task. Dragging a Task into In Progress does not start work; Cogno asks you to send a message instead.

​

Choose the Environment

The Task creation form places an Environment control beside the assignee. Automatic uses Automatic routing to select from the Task assignee and available machines. You can also select a registered Environment directly. A Task that has already run keeps its Environment, machine, and directory for later turns. When the machine differs from the current one, the Task identifies where it runs. A saved session keeps its recorded working directory when the Environment’s default folder changes. If that directory is missing, the run stops with an error asking you to open a new session.

​

Sign in on this computer

Use the sign-in action in Mac setup, agent settings or a local model picker. On supported Desktop and Engine versions, finish sign-in in your browser and return to Cogno. Cogno checks the result and refreshes the agent’s availability. A model picker that specifies a Claude account keeps sign-in scoped to that account; it does not replace another account’s sign-in or change the default. Windows and older Desktop or Engine versions keep the Terminal sign-in flow. Authentication errors do not start a second login in Terminal. The separate Claude account controls in Settings → Computers, described below, retain Terminal sign-in and Check sign-in.

​

Choose a Claude account on your Mac

Use your own Claude accounts for Tasks in the macOS, Linux or Windows Desktop app. During startup or resume, messages remain queued, including when you choose Send now. Messages for a different account wait until the running turn ends. Account selection applies to this Mac’s local Desktop and its authenticated queued work. Cloud runs and other providers do not use it. A signed-out account, missing history or unfinished background work stops the switch and keeps the previous selection. Sign in again or finish the background work, then send again. When the default account has reported a usage limit, a new Session without an explicit account uses the next registered, signed-in account outside its known limit. The saved default is unchanged. Limits survive an Engine restart until the reported reset or a later successful turn on that account. In a local Desktop Task conversation, an explicit Claude quota refusal before any tool ran can retry your message and attachments once on another signed-in account. Cogno stops the old worker, starts a new Session in the same working copy, and provides the earlier conversation as a readable record. Your model, effort and requested access are retained, and permissions are checked again. Queued input, unfinished background work, a stop request, a connection failure, or an unknown tool count prevents this retry. A retry that also fails is not sent to a third account. Restarting Engine does not resend a rejected message. For scheduled Project work, an explicit Claude quota refusal before any tool call can hand unanswered work to a fresh Session on another signed-in account. Cogno rebuilds the work from its current sources. It does not replay a stopped conversation. A turn that called a tool, lost its connection, or ended without an explicit quota result keeps its normal recovery path. Cogno stores account names and references. On macOS, Claude uses Keychain and these launches refuse file-based credential fallback. On Linux, Claude owns credentials inside the selected private account directory. Cogno checks ownership, permissions, links and writability before launching the CLI.

​

See which Claude account is signed in

After Check sign-in succeeds, each account shows Signed in as and the Claude email, with the organization when there is one. If two accounts use the same Claude account, the row says Same Claude account as and the other account’s name. When a check finds a different Claude account than last time, Cogno says so: Now signed in as the new email, with the previous one.

​

Remove an account

Sessions that used a removed account keep their history. Choose another account to continue them.

​

If an account can’t be used

Each message names its own fix.

​

Choose a Codex account on your Mac

Use separate Codex sign-ins for local Tasks in the macOS, Linux or Windows Desktop app. A choice made during a turn applies to the next message. Continuing an existing Session transfers only that thread’s history; its Task, working directory, and thread ID stay the same. A failed switch keeps the previous Session account. Codex account selection is local to this computer and supports manual switching.

​

Computer use on your Mac

On an Apple silicon Mac, Cogno Desktop includes computer use. Agents running on that Mac can see and operate its apps, such as reading a window, clicking, and typing, without an extra install. They work in the background and do not take over your pointer.

• Cogno needs Accessibility and Screen Recording under System Settings → Privacy & Security. These are the same permissions meeting recording uses; no other app is added.
• Computer use is available while Cogno Desktop is open on that Mac. A run that starts while it is closed has no computer use.
• It is there whether or not personal connectors are turned on, and on Cogno credits.
• When an agent clicks in an app, a faint ring briefly marks the spot. No cursor moves around your screen. If you prefer to watch a cursor, choose Black or Silver instead of Ripple under Settings → Preferences → Computer use; it applies from the agent’s next session.

​

Plan at creation and choose a model

Use Plan it first while creating a Task to start with a planning run. The model menu reads models from the selected Engine. Default model follows that Engine’s default. Choosing a named model pins it for the Task. If discovery fails, select Refresh models; Cogno does not invent a fallback model. For background runs using Optimized, an unavailable automatic selection service falls back to a model in the selected agent’s current Engine catalog. The conversation records the model used and why fallback was needed. If the Engine cannot load its model catalog, the failure keeps its cause and asks you to check the Engine connection and agent sign-in before resending. If the model is unavailable, choose an available model in the composer and resend. Model selection stays fixed while a turn is active. Stop the turn before changing it.

​

Follow the run

While a turn runs, select Stop or press Escape to interrupt it. Pressing Enter on another message adds it to a queue above the composer; the queued messages are sent together as the next turn as soon as the current one ends, including after a Stop. Press ⌘Enter to send now instead: the composer text first, then the queued messages oldest first, all into the running turn. Each queued row has its own send-now, edit, and remove controls. A follow-up from a connected source waits while the coding agent starts or resumes. If the running turn ends before delivery, Cogno continues the same session as a new turn after checking its execution permissions. You can select Stop while that turn is still starting. If its execution permission is revoked, Cogno interrupts the turn. The work surface carries the same search shortcuts an editor has. ⌘F (Ctrl+F) finds and replaces inside the file open in the editor. ⌘⇧F (Ctrl+Shift+F) opens the Search segment and finds text across the whole working copy; select a result to open that file at the line, or type a replacement to change every occurrence at once. ⌘P (Ctrl+P) jumps to the file-name search in All files. Content search needs the machine’s Engine to be current; the segment says so when it is not. An agent can delegate bounded work to a sub-agent. Open the Agent tool row to read that sub-agent’s nested messages, tool calls, result, tokens, and duration. The Running file-panel segment lists background shells, watchers, or servers only while they remain active.

​

Review the result

Read the agent’s result in the Task conversation and inspect Changes. A Git Environment with automatic delivery can push a branch and open a pull request. A local-only branch or direct Environment has no automatic pull request. A completed run can propose Backlog, Ready, or In Review. Applying that proposal releases Cogno control. A failed or stopped run leaves a Cogno-controlled Task in In Progress. The agent cannot select Done for its own work. Review the result and move the Task when you decide it is complete.

​

Run states

pending, claimed, and running are live states. Completed, failed, and cancelled are terminal run states; they do not close the Task. An automatic Task run that reports zero tool calls and submits no Task result is recorded as failed, even if its coding agent exits normally. This does not close the Task. Runs that used tools, submitted a result, or did not report a tool count keep their normal completion rules. If a run ends without submitting a Task result or a report card, its fallback card says that the result was not submitted. Check any operations already performed before choosing Re-run. A finished run alone does not confirm that a result was delivered.

​

Workspace and Project work

Cogno can review incoming work before it belongs to a Task. A Workspace Run gathers up to 20 due Attention items with the same Project scope and requester. Items can join a compatible queued batch until execution is claimed. Independent batches can start while other Workspace Runs are active, subject to the selected computer’s concurrency limit. Gmail and meeting deliveries keep their own batches and conversations. The first local Workspace batch starts a conversation. Later batches reuse it while its Environment, requester, Project scope and execution configuration remain compatible and the saved Session is available. A busy Session is skipped when selecting history for an independent batch. Closing the Session, losing its local history or changing those conditions starts a new conversation. Follow-ups addressed to an existing Session retain their execution order. Each batch checks permission again. Saved conversation history does not require an agent process to stay running. After a quiet Workspace turn, Claude closes its worker after two seconds; unfinished background activity keeps its existing protection. Codex closes its Workspace worker at the end of the turn and resumes saved history next time.

​

Work waiting for authentication

When a machine reports that its coding agents cannot authenticate, new queued work stays pending without using an execution attempt. Restore authentication on that machine. A successful authentication check makes it eligible to receive work again; a missing or inconclusive check keeps the work waiting. Usage limits or other execution faults can still keep it waiting.

​

Usage-limit notices

When a recent Run stops because Claude Code or Codex reaches its usage limit, a compact, neutral one-line notice below the Workspace header names the agent and says that a Run stopped. Use Open Task (or Open Project for a Project Run) to return to the stopped work. It stays visible while you view another Task. The notice uses the latest Run for each Task or Project in the recent Run history. A newer Run for the same Task or Project replaces the failed Run’s notice. Other Tasks and Projects can continue running. The notice reports a Run’s outcome; it does not determine whether every Run on that machine can run.

​

Provider credit balance

If a Run reports insufficient provider credits, check that provider’s billing or credit balance. After restoring enough credit, send another turn on the Task. Cogno does not infer a quota-reset time from a low-credit-balance message.

​

Troubleshooting

For other failures, see Troubleshooting.

​

Related docs

• Work with Tasks
• Task statuses
• Take over a Task in your terminal
• Machines

​

Removing a Codex account

Select Remove to sign out through Codex and remove the saved account name. Finish or stop its active, queued and background Sessions first. Conversation history is kept. If logout fails, Forget account removes only the Cogno registration; credentials may remain in the private account directory. The existing sign-in cannot be removed. Added accounts require a verified file credential store; incompatible organization policies disable them.