> ## 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.

# Concepts

> Cogno's mental model in one picture: a cloud half that decides what should happen, machines that do it, and the two seams that join them.

Cogno has two halves. One runs in the cloud and decides what should happen. The other runs on
real computers and makes it happen. Almost everything in these docs is one half, the other, or
the seam between them.

<div className="cd cd-model">
  <div className="cd-panel">
    <div className="cd-head">Cloud · Cogno decides</div>

    <div className="cd-row">
      <span className="cd-name">Workspace</span>
      <span className="cd-desc">members · Memory · Instructions</span>
    </div>

    <div className="cd-row cd-i1">
      <span className="cd-name">Project</span>
      <span className="cd-desc">a set of repositories</span>
    </div>

    <div className="cd-row cd-i2">
      <span className="cd-name">Task</span>
      <span className="cd-desc">statement · conversation · delivery</span>
    </div>
  </div>

  <div className="cd-seams">
    <div className="cd-seam"><span>points at</span><i /></div>
    <div className="cd-seam"><span>runs as</span><i /></div>
  </div>

  <div className="cd-panel">
    <div className="cd-head">Your machines · work runs</div>

    <div className="cd-row">
      <span className="cd-name">Machine</span>
      <span className="cd-desc">runs the Engine</span>
    </div>

    <div className="cd-row cd-i1">
      <span className="cd-name">Environment</span>
      <span className="cd-desc">a folder + agent + model</span>
    </div>

    <div className="cd-row cd-i2">
      <span className="cd-name">Session</span>
      <span className="cd-desc">one task's work, on disk</span>
    </div>
  </div>
</div>

Read the two seams and you have the whole model: **a project points at a folder**, and **a task
runs as a session** in it.

## The cloud half

This half is always on and independent of your computers. It runs whether or not anything of
yours is awake.

| | |
| - | - |
| **Workspace** | The top-level container — members, projects, tasks, settings. **Memory** is what Cogno knows about your team; **Instructions** are the standing rules it follows ("ignore #random", "always branch off stg"). Memory is *what's true*, Instructions are *how to behave*. |
| **Project** | A set of repositories, plus the sources it watches. Every task belongs to one, and that is how Cogno knows where work runs and where pull requests belong. |
| **Task** | The unit of work. Its **statement** says what should be done; its **conversation** is a live agent session, not a comment thread; its **delivery** is the pull request that comes back. Five statuses — Backlog, Ready, In Progress, In Review, Done. See [Task statuses](/docs/task-statuses). |
| **Events** | Activity from your connected tools, read as it happens. Sources are what Cogno *reads*; GitHub is the action side it *delivers through*. See [Connect integrations](/docs/integrations). |
| **The Cogno agent** | The actor. It reads events against Memory and your existing Tasks, files the Task in the status it belongs in with the mark of its source, and hands the work to a machine. Cogno-controlled Ready work can appear in the **Cogno** group inside Ready; start, move, or reject it to decide what happens next. |

## The machine half

Nothing here is a cloud sandbox. Work runs in a real checkout, on a real computer, as you.

| | |
| - | - |
| **Machine** | Any computer running the Engine — yours through the desktop app, a teammate's, or a server enrolled with `cogno server install`. It is **Online** or **Offline**, nothing in between. See [Manage your machines](/docs/machines). |
| **Engine** | The always-on local runtime. It installs with the desktop app and is what actually starts the coding agent. Its **Readiness** line is the machine's honest answer to "can work run here?" — the agent CLI installed and signed in, git present, disk free. |
| **Environment** | A folder on that machine plus the settings work runs under there: which coding agent (**Claude Code** or **Codex**) and which model. You own yours; you can have more than one. |
| **Session** | One task's work inside an environment. It outlives any single run — the history stays on that machine, and you can pick it up in your own terminal with **Resume in CLI**. See [Take over a task in your own terminal](/docs/task-sessions). |

## Where the halves meet

Two seams, and only two.

### A project points at a folder

A project lives in the cloud, but the code it works in does not. Each member connects their own
**environment** — one folder on their machine — from the project's page (**Choose folder**, or
**Clone repositories**). One project, one environment per person. Until someone does that, the
project has nowhere for its work to run. See [Set up a project](/docs/projects).

### A task runs as a session

A task's conversation *is* its session. When a run starts, the task binds to one environment and
keeps it, so every later run lands in the same folder with the same history. That is why a task's
messages, its branch and its working directory all line up.

### What crosses the line

The Engine reaches out to Cogno and claims work; nothing reaches into your machine. Its only
listener is a local socket for the desktop app on the same computer.

<div className="cd cd-wire">
  <div className="cd-box">
    <span className="cd-name">Cogno</span>
    <span className="cd-desc">the cloud half</span>
  </div>

  <div className="cd-msgs">
    <div className="cd-msg to-cloud">anything to run here?<i /></div>
    <div className="cd-msg to-machine">what to do · environment · branch · model<i /></div>
    <div className="cd-msg to-cloud">messages · status · branch + PR<i /></div>
  </div>

  <div className="cd-box">
    <span className="cd-name">Engine</span>
    <span className="cd-desc">on your machine</span>
    <div className="cd-chip">Claude Code or Codex runs here — your checkout, your tools, your credentials</div>
  </div>
</div>

* **Down to the machine:** what to do, which environment and branch to use, which model.
* **Back up to the cloud:** the agent's messages as it works, the run's status, and the delivery
  — repository, branch, PR number.
* **Never:** your Claude or Codex credentials. You sign those CLIs in yourself and they hold
  their own. Cogno does not keep a copy of your repository either — the checkout stays where
  it is.

## The loop, end to end

<Steps>
  <Step title="Something happens in your tools">
    A Slack thread, a decision in a meeting, a Notion comment. It arrives as an **event**.
  </Step>

  <Step title="Cogno decides whether it is work">
    Weighed against Memory, your Instructions and the tasks you already have. If it is worth
    doing, Cogno files it against a project, in the status it belongs in, marked with the source
    it came from.
  </Step>

  <Step title="You glance">
    The task is already on your board in the status Cogno chose. Leave it, move it, or archive
    it — seconds, not a workflow.
  </Step>

  <Step title="A machine picks it up">
    The task binds to an environment, the Engine claims the turn, and a coding agent runs in
    that folder. If no machine is free the work waits rather than failing.
  </Step>

  <Step title="The result comes back to the Task">
    The Task shows the delivery and the conversation shows how it got there. Git work can
    return as a pull request; direct work stays in its connected folder. You review the result
    and decide when the Task becomes **Done**.
  </Step>

  <Step title="And round again">
    That merge is itself an event. The loop has no separate start: connect a tool and it begins
    at step one, or type a task yourself and join at step four.
  </Step>
</Steps>

## Related docs

* [Introducing Cogno](/docs/introduction) — what Cogno is and what it does.
* [Getting started with Cogno](/docs/getting-started) — set it up end to end.
* [Work with tasks](/docs/tasks) — what Cogno proposes, the conversation, day-to-day flow.
* [Set up projects](/docs/projects) — repository sets and environments.
* [Manage your machines](/docs/machines) — the Engine, readiness, and enrolled servers.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.