> ## Documentation Index > Fetch the complete documentation index at: https://cogno.studio/docs/llms.txt > Use this file to discover all available pages before exploring further. # Work with Tasks > Create Tasks, understand Cogno-managed work, start runs, and move work through review. A Task is Cogno's unit of work. It keeps the request, status, ownership, conversation, files, and delivery together from intake through review. Open **All tasks** in the sidebar to see work across Projects. See [Task statuses](/docs/task-statuses) for lifecycle rules and [Task views and filters](/docs/task-views) for layouts and saved views. ## Prerequisites * A Cogno workspace where you can create or edit Tasks. * For agent work, an Environment connected to the Task's Project. See [Set up a Project](/docs/projects). ## Open a Task Each full Task has its own page and shareable link. Back returns to the page where you opened it; Forward reopens it. Sidebar links leave the Task in one click. Moving between pages preserves your working sessions. In a browser, selecting a Task opens a side peek over the current page. Drag its left edge to resize it; release to save the width, or press Escape while dragging to cancel. You can also focus the edge and use the left and right arrow keys to adjust the width. Use **Expand to full view** to open the full Task or **Close task panel** to return to the list. | Surface | What opens | | - | - | | Browser | The Task statement: properties, description, and delivery details. | | Cogno desktop app | The agent conversation, Task statement, files, changes, running processes, and terminals in a rearrangeable work surface. | Shared HTTPS Task links prefer the Cogno desktop app on your device. Supported Desktop releases open verified links directly; other installations use a short browser handoff. If the app cannot open, the link continues in Web automatically. You do not need to choose between the app and the browser. If you are signed out in Desktop, sign in there. Cogno returns to the same Task after authentication. The link does not grant access: your account must have permission to view that Task. Shared links open the main window so authentication and the return stay in the same window. For a Cloud Project, the full Task view hides the conversation pane and its message composer. Task properties, description, and delivery remain available. Local Projects keep their conversation pane. Reloading the desktop app preserves your pane arrangement, right-panel visibility, and each Task’s expanded or folded terminal. While content loads, the work surface uses your saved arrangement. The address determines which Task opens. In the desktop work surface, drag a boundary between panes to resize them. Release to save the layout, or press Escape during the drag to restore it. A Task bound to another machine shows **Runs on \** or **Runs on another machine**. You can still read and edit the statement from the current surface. ## Understand Cogno-managed work Cogno can create and start Tasks from connected events. It creates them directly in **In Progress** and uses an orange treatment while it remains responsible for them. * In desktop List view, Cogno-controlled work sits in a **Cogno** group under the assignee's tab in **In Progress**. * In Board and mobile List, the Task stays in **In Progress** and keeps the orange treatment. * Top-level Tasks keep the source they came from. Show the **Source** column or read the inline **from \** mark. For a Local Project, Cogno prefers an idle or less loaded eligible member's Project folder when starting a Task that has no Environment yet. Task work ready to start counts alongside work already running while it waits. The assignee's machine wins when health, capacity, and load are equal. A Task with an existing Environment continues there. There is no Cogno-controlled Task in **Ready**. A failed or stopped run stays in **In Progress**, including while it waits for another Environment or turn. Deliberately moving the Task to another status releases Cogno control. Status proposals are separate metadata. Filter `suggested:true` to see Tasks whose proposed status remains unresolved. See [Task statuses](/docs/task-statuses#status-proposals). ## Create a Task ### Create and start with a connected Engine For a Cloud Project, **Create Task** saves your full request in the Task description and queues a Cloud run, including when you assign the Task to yourself. The run starts independently of the Task conversation. Cloud quick creation uses the Cloud execution defaults and does not offer attachment, model, access, or base branch controls. If you attached files before switching to a Cloud Project, remove them before creating. Desktop and browsers with an available Engine use the same prompt-first composer. For a Local Project or a Task without a Project, attach files and select **Create Task** to open the Task and send its first message through Engine. When model discovery is unavailable, Engine uses its default executor and model. Browsers without an available Engine use the full form below. Select **Later** beside **Create Task** to save the request to the backlog without starting a run. Select **Work** and write in **What should Cogno do?** Choose a Project, base branch, and model for Local execution, then select **Create Task** or press Enter. For Local execution, Cogno creates a Ready Task, opens it, and sends the prompt as the first turn. For your own Local execution, select the effort level beside the model before creating the Task. For example, the control shows **Medium** or **High**; it offers only levels supported by the selected model and Engine. Your selection applies to the first turn. Changing to a model that does not support the selected level uses that model's default, **Medium** when available, or its first available level. The control is hidden when effort is unsupported, for Cloud execution, or when assigning the Task to someone else. If creation fails, your prompt and attachments stay in the open composer. You can edit the prompt, Project, or model and select **Create Task** again; each attempt uses the current input. A previous unfinished creation does not block a new one, and reopening the composer does not restore that previous request. If the Task was saved but its response was lost, an automatic or manual retry can create a duplicate Task. If saving the first input on your device fails after the Task is created, that Task can remain without starting its first turn. For Local execution, the person chip beside the Project (**Assignee**) names whose machine runs the work. It starts as you. Choose someone else and **Create Task** assigns the Task to them and queues a run for their machine instead of opening it here: the run starts at once when they have a folder connected for the Project, and otherwise the Task waits under their tab in **In Progress** until they connect one. The attachment, model, and base branch controls belong to your own machine, so they step out of the composer for someone else. The **+** on a person's tab in **In Progress** opens this composer preset to that person. For Local execution, you can attach or paste files before creating. One message accepts up to 20 files; a local agent refuses a file over 25 MB. The send waits until every attachment finishes loading. The base branch defaults to the repository default. A direct Environment has no Git branch or automatic pull request. A named local-only branch also shows **no automatic PR**. ### Choose an exit from the full form The full form's **How to proceed** panel combines assignee, Environment, and the next action: Add a title and description. The editor accepts rich text, mentions, tables, and images. For a Local Project, the Environment starts at **Automatic** when a machine can be selected. Open it to use **Automatic routing** or choose a registered Environment. A Cloud Project uses its Cloud environment for any assignee. * **Watch it get built** creates the Task and starts implementation. * **Plan it first** creates the Task and starts a planning turn. * **Later** creates the Task in **Backlog** without a run. * **Create** creates the Task in **Ready** without a run. In a Cloud Project, **Watch it get built** and **Plan it first** start Cloud execution even when you assign yourself. In the browser, assigning yourself in a Local Project saves the Task and requires Desktop to start. See [Cloud environments](/docs/cloud-environments#start-a-cloud-task). ## Start and follow work There is no separate run button. In the desktop app, send a message in the Task conversation. The first message claims an Environment and moves the Task to **In Progress**. Later messages continue the same Task session. The composer reads **Message the agent…** and sends to the Task’s connected Engine session. If this surface cannot reach the machine, it shows the Task’s location instead of offering a message box. While work starts, the conversation shows **Starting…**. During the turn it shows **Running…**, and the send control becomes **Stop**. Enter on another message adds it to the queue for the next turn; ⌘Enter sends the composer text and the queue into the running turn now. Stop the turn before changing its model. A sent message leaves the composer at once and appears in the conversation; the send button stays disabled until Engine accepts it. If the send is refused, the text and attachments return to the composer so you can send again. Once a message is queued, it appears above the composer. The current turn continues while the message waits. Use **Send now**, **Edit**, or **Remove from queue** on that message to change what happens next. Attach, drop, or paste files into the composer. Images appear as thumbnails that open full size. Failed uploads block the message until you remove them. After you request a send in Desktop, opening another Workspace or Task allows the first message and a message waiting for a folder move to continue delivery. Keep the app open until Engine accepts the message. Accepted work continues independently of the Workspace you are viewing. If delivery fails, open that Task to review the restored text and attachments and retry. ### Replies in the source conversation For a Task created from Slack, Microsoft Teams, or Discord, a completed run that was answering that conversation can finish before it calls a message Tool. While Cogno keeps the Task **In Progress**, it schedules one follow-up to read the Task and source conversation and report what happened. If another run is active, this check waits until that run ends, including when it fails. Several waiting completions share one follow-up. Messages sent by another run do not cancel this check. Cogno checks the source conversation even if that run posts elsewhere or sent its message before a new request arrived. The follow-up reads the existing conversation before replying and sends nothing if the answer is already there. It starts no new work, and its own completion never creates another automatic follow-up. Replies still require the Project's current integration permissions and consent to send messages. Moving the Task out of Cogno-managed work keeps your control and prevents this recovery from restarting it. ### Start work for a person from the list Drag a Task onto a person's tab in **In Progress**, or onto the rows under the open tab. The Task is assigned to that person and a run is queued for their machine. On a Project page, dropping a Task onto your own name at the top of the sidebar does the same for you. * With a folder connected for the Project, the run starts right away. * Without one, the row shows a hollow branch mark whose tooltip reads **Starts when \ connects a folder**. The run starts on its own the moment they connect one. * A Task that already runs in an environment stays with its owner. While you hold it over another person, the lane shows **Fixed to \'s environment**, and releasing it changes nothing. * While a run is executing, the row's mark spins for everyone in the workspace, not only on the machine doing the work. ## Move through the lifecycle Change status from the Task, its row menu, or by dragging in List or Board. * Moving into **In Progress** without starting work is refused with *Send a message in the Task to start work.* Dropping the Task on a person's tab in **In Progress** is the way to start work from the list; see [Start work for a person from the list](#start-work-for-a-person-from-the-list). * Moving out of **In Progress** during a live run opens **Stop the running agent and move?** Select **Stop and move** to retain partial results and end the run. * A completed run can propose **Backlog**, **Ready**, or **In Review**. Applying that proposal releases Cogno control. A failed or stopped run leaves the Task in **In Progress**. * A clear reply in the Task conversation can decide the state directly. An explicit acceptance moves the Task to **Done**; a request to defer moves it to **Ready** or **Backlog**; a request for review moves it to **In Review**; and a cancellation moves it to **Rejected**. If the meaning is uncertain, the agent asks or reports before moving the Task. * Select **Done** when the work is complete. ## Edit, archive, or delete The Task statement contains Status, tags, dates, assignees, Project, preview, and actions. Descriptions support rich text, collaborative editing, and version history. Add **Parent task** from the row's `...` menu to nest the Task under a top-level Task, move it to another parent, or clear it with **No parent**. A Task that has sub-Tasks of its own cannot become a sub-Task. **Archive** removes a Task from active views and is reversible. **Delete permanently** removes the Task, sub-Tasks, comments, attachments, and history. On a machine that ran it, deletion also removes the local conversation and working copy, including uncommitted changes. Permanent deletion has no restore path for the machine-local conversation or uncommitted working-copy changes. ## Close a Task that has sub-Tasks Moving a Task to **Done**, **Rejected**, or **Archived** moves its open sub-Tasks there with it, and cancels any unfinished agent work on them. A sub-Task that was already archived stays archived. Reopening a parent — **Backlog**, **Ready**, **In Review** — leaves its sub-Tasks where they are. When the Task still has open sub-Tasks, Cogno asks first and names how many the move closes. Choose **Close all** to go ahead, or **Cancel** to leave everything where it is. For ten minutes after the move, **Undo** on the toast takes the whole press back: the parent and every sub-Task the move closed return to the status each had. A sub-Task you changed yourself after the move stays where you put it. The undo does not restart a run the move cancelled — the Task comes back, and you start the run again if you want it. A sub-Task belongs to its parent's Project. Moving a Task to another Project moves its sub-Tasks with it, and filing a Task under a parent in another Project moves it into that Project. If the Project cannot be loaded, the Task description and delivered output remain visible. Select **Retry** in the Project notice. The chat stays hidden while the Project execution location is being checked; Cloud Tasks keep it hidden after the check succeeds. ## Troubleshooting | Symptom | Fix | | - | - | | The Task cannot move to **In Progress** | Send a message in the Task to start work, or drop the Task on a person's tab in **In Progress** to queue a run for them. | | A row in **In Progress** shows a hollow branch mark | The run is waiting for that person's folder. Connect a folder for the Project on their machine; the run starts on its own. | | Dropping a Task on a person shows **Fixed to \'s environment** | The Task already runs in that person's environment and stays with them. | | The Environment menu has no destination | Connect your folder to the Project, then retry. | | **Models unavailable** appears | Open the model menu and select **Refresh models**. | | **Choose a Project to run this in** appears | The request is not in a Project yet, so there is no folder for it to work in. Move the Task into a Project, then send it again; your message is kept. | | A turn stays queued | Bring the selected machine online; the queued work remains available. | | A Task appears under **Cogno** | Cogno remains responsible for this Task in **In Progress**. Review the latest run, send another turn, or move the Task when responsibility changes. | For other failures, see [Troubleshooting](/docs/troubleshooting). ## Related docs * [Task statuses](/docs/task-statuses) * [Task views and filters](/docs/task-views) * [Run an agent on a Task](/docs/agents) * [Take over a Task in your terminal](/docs/task-sessions) ## Moving around the desktop Inbox, Meetings, and All Tasks stay at the top of the sidebar. Saved views appear before Projects. Click a Project name to open its page. Clicking the current Project again expands or collapses its working Tasks; its disclosure arrow does the same. Select the filter button beside **Projects** to choose which Projects appear. The sidebar keeps every Project in place and replaces each row's actions with a switch. Turn switches off or on, then select the filter button again to finish. Hidden Projects collect in **Hidden projects** at the bottom of the sidebar; select it to open or close the list, open a Project from there, or select the eye button to show it again. This changes only your sidebar; it does not archive or alter a Project. The choice is saved to your account, so desktop, web and the mobile app hide the same Projects. In the mobile app, press and hold a Project and choose **Hide** or **Show** from its menu. Back and Forward remain available in the title bar when the sidebar is collapsed. Settings has a separate Return to work action. The Task list address retains its applied search, filters, sort, and layout. Back and Forward restore that entry. A bare workspace entrance reopens the last work page remembered in this window for your account and workspace; explicit links always take precedence. In Board view, hiding or showing a status column updates the same status filter in the address. Reload and history therefore restore those columns too. ## Tasks on mobile Touch and hold a Task to open its status menu while your finger is still down, then choose the new status. Before moving a Task to Done, Archived, or Rejected, the app asks you to confirm that its subtasks will close and their runs will stop. To move a Task to **In Progress**, start work from the Task. Keep holding and drag up or down to reorder Tasks that share the same status, parent, and Cogno-managed state. On iOS, a parent Task's subtasks move with it. The order is saved including Tasks hidden by filters. Reordering Tasks is supported in Projects with 200 Tasks or fewer. To reorder Projects on iOS, touch and hold the Project name and choose **Move up** or **Move down**. On Android, touch and hold the Project name, drag it up or down, and release. The order is saved to your account. In the Tasks filter, open **Status** to select several statuses in a row. The menu stays open and updates the selection; tap outside it to close. ### Read AI run status on mobile Each Task row shows an AI run label beneath its title, including in search results. The label also forms part of the row's screen-reader description. It describes the latest run separately from the Task's business status: **AI run ended** means that run ended; review the result and choose **Done** when the request is finished. **In Progress** alone does not establish that AI is running. | Label | Meaning | | - | - | | **AI running** | The latest agent run reports that it is running. | | **AI queued** / **AI preparing** | The run is waiting to start or preparing to start. | | **AI awaiting approval** | The running agent is waiting for approval. | | **AI started · end unconfirmed** | A direct machine run acknowledged starting; its end has not been confirmed. | | **AI run ended** | The latest run reported completion. | | **AI run ended · syncing** | A fresh Engine session shows that the direct turn ended; the recorded run has not caught up yet. | | **AI run failed** / **AI could not start** | The run failed during execution or before starting. | | **AI stop awaiting confirmation** / **AI stopped** | A stop was requested, or the run confirmed that it stopped. | | **AI interrupted** | The direct run reported interruption. | | **AI handed off** / **AI run replaced** | The recorded run handed work onward or was replaced. | | **AI status unconfirmed** | Current execution information is unavailable or insufficient. | | **AI not started** | No run or Task execution Environment is recorded. | An open direct machine run shows **AI status unconfirmed** when its machine is offline. A machine being online and having acknowledged a start does not by itself confirm that a turn is still running. For your own active Task Environment, the app also reads its current Engine session when the binding still matches the direct run. A fresh active operation shows **AI running**; a fresh idle session updated after the start shows **AI run ended · syncing**. An unavailable or stale Engine session keeps **AI started · end unconfirmed**. Saved list data also shows **AI status unconfirmed** until a fresh fetch succeeds, and after a fetch error. Run updates refresh the list. While the app is in the foreground, lists containing **In Progress** Tasks or open direct runs refresh every 15 seconds. Returning to the app and manually refreshing fetch the current state again. ### Create a Task on mobile Tap **+** beside an expanded Project to open Task creation with that Project selected. On iOS, the small icon has a larger tap area that includes the surrounding blank space. Tap the Project name or its disclosure arrow to expand or collapse its Tasks. Enter **Title** and **What should be done**, then choose a Project. Use **Add Photo** or **Add File** to include attachments. When your Project has a reachable machine, **Create & Run** saves the Task, adds the attachments to its description, and starts the work. Otherwise, **Create** saves the Task without starting a run. After the run is accepted, the Task appears in **In Progress**. The app reloads the saved status before opening it and updates the Task list. **Create** keeps the Task in **Ready**. If the run is accepted but the latest status cannot be loaded, the app reports this and offers **Open Task** to check the saved Task. The conversation shows **Queued** while the accepted run waits for its machine, then **Starting…** and **Running…** as execution begins. A failed run shows its error. **In Progress** alone does not mean the agent has started. The sheet stays open while **Creating…** is shown. If creation fails, the draft stays available. If attachments cannot be added or the run cannot start, the app reports that the Task was saved and offers **Open Task**. An attachment failure prevents the run from starting; check the saved Task before starting work. ### Chat input on mobile Tap the model shown in the Task's input to select an Engine-provided model. Before the first session starts, you can also choose its executor. Use **Refresh models** to reload the available choices. On supported Engines, tap the access setting to select **Ask**, **Auto**, or **Full access**, within the machine's allowed access. **Full access** asks for confirmation. Toggle **Plan** before sending your message. Before the first session starts, Engines that support starting-branch selection show a base branch control. Choose a remote branch, or enter a branch, tag, or commit when the repository list is not ready. The starting branch applies to the new session; existing sessions keep their working branch. Use the photo button or **+** beside the message input to attach photos or files. Images show a preview; use the remove button to discard an attachment before sending. A message accepts up to 20 files, each no larger than 25 MB, and can contain attachments without text. If sending fails, the message and attachments return to the input so you can retry. In builds with speech recognition, the microphone adds spoken words to your draft. Allow microphone and speech recognition access when prompted. Sending or leaving the screen cancels dictation, including a pending permission request. The input shows **Preparing voice input…**, **Listening… Tap stop when finished.**, and **Finishing voice input…**. Tap the cancel button while preparing, or the stop button while listening. Wait for finishing to end before restarting. Editing the text stops recognition and preserves your correction. Builds without the native speech module hide this control; an OTA update cannot add it. Android on-device dictation requires the selected language's offline speech model. ### Diff base on mobile In a Task's **Changes**, each repository has a **Compare against** row. On iOS and Android, tap the row to open a searchable list of remote branches. Tap a branch to select it, including while the search keyboard is open. The base you choose applies to the changed-file list and to each file's patch, and each repository keeps its own base. The choice is kept while the app is open, per Task run and repository. Choose **Default branch** to return to the repository's default base. If the branch you chose has been deleted, choose the default or another branch from the same row; a stored branch stays in the list until you do. The row is shown even when a repository has no changes. If branches fail to load, tap the error to retry. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.