Set up a project

A project is the repositories a body of work is about, plus an Instruction telling Cogno how to act in it, an Owner, and the environments its work runs in. Its tasks gather on its own page. A project is its repository set: one project per set of repositories in a workspace, and naming the same set again opens the project that already has them. Every task belongs to a project — work created without one files into the workspace’s default project.

​

Prerequisites

• A workspace you can write in.
• GitHub is optional. Connect it to choose from repositories that also have a checkout on this computer — see GitHub.
• The Cogno desktop app on the computer that will run the project’s work, to connect a folder.

​

Open a project

The sidebar’s Projects section is the list — there is no separate projects page, and old links to one land on Tasks. Opening a workspace lands on the project you last had open, or on the task list when there is none. The project’s page is its tasks. Use Switch task view beside the query bar to choose List, Board, Calendar, or Gantt; the page keeps every layout scoped to this project. The query bar otherwise works like the one on the Tasks page, minus the Project criteria because the project is already fixed. The filter is remembered per project: narrowing one project’s tasks leaves every other project untouched, and the project you narrowed reopens narrowed. By default a project shows its open tasks — Backlog, Ready, In Progress, and In Review — and hides Done; add Done in the filter panel to see finished work. Reset in the filter panel puts it back to the project default. In List, what is running right now appears first, one section per person, with the status groups under it. Drag rows between sections to move them. Each status initially draws up to 24 rows; select Load more — showing 24 of 83 to reveal the next 24. The page retrieves tasks in pages of up to 200 across the statuses the filter selects, and fetches another page when you reach the bottom. In Board, group columns by Status or User. See Task views for the Calendar and Gantt interactions and the settings shared across the workspace.

​

Create a project

+ beside the sidebar’s Projects heading opens a menu, not a form. A row is the whole decision: the project is created, named from what you picked, and its page is the next thing on screen. There is no name field to fill and no Create button to reach. The menu belongs to the desktop app. Every row under it needs the Engine on this machine — the folder lists are its scan, and binding a folder carries its machine credential. In a browser, or with the Engine down, the menu says Engine is not running on this machine. and offers Start Engine rather than rows that would fail on click. If the installed Desktop cannot open the OS chooser, the menu asks for the folder’s absolute path instead. Enter the same path you would have selected; the Engine inspects it before Cogno creates or connects the project. Several projects can run in the same folder. A folder that is already an environment stays on its list and says Already used by a Project on hover. Choosing a folder that one of your projects already runs in — from the list or through Open folder… — asks first: Open the project it belongs to, or name a new project and Create project to make a second one in the same folder. The name field starts with a free name, and a name the workspace already uses cannot be created. Linked Git worktrees are left out of both folder lists. A worktree shares its checkout’s remotes, so it is the same repository wearing another path, and a machine with several of them open would otherwise fill the lists with one repository. Recents drops folders that are already environments rather than dimming them — it is six shortcuts, and a folder whose project is already in the sidebar would take a slot from one that has none.

​

What it is called

Past two repositories the joined label stops being a name, so the folder’s own name takes over. The full join is not lost — it is the placeholder on Project Name in project settings, so clearing that field brings it back. This only decides the first name; rename it from there.

​

Where it runs

A folder picked under Recents, On this Mac, or Open folder… is bound as your environment behind the project page — the page opens first and nothing spins waiting for it. GitHub follows the same rule. Cogno only enables a repository when the Engine found a local folder containing it; choosing the row creates the Project and connects that folder together. A repository marked Not on this computer cannot create a folderless Project. Cogno does not clone it from this menu.

​

Configure the project

Open Project settings from the ⚙ on the project’s sidebar row. Inside settings, the sidebar becomes the settings navigation. Projects always lists every current project so you can move directly between their settings, followed by Archived Projects. Press ⌘K on macOS or Ctrl+K on Windows and Linux to open the command palette. Search for any available Settings destination or a project’s name to open its settings directly. Destinations that require a permission only appear when you have that permission.

​

Connect where the work runs

Source Folders lists the folders this Project uses for you on one machine, in order. It shows and changes your own folders only. The folder at the top is marked Primary: a run starts there, and the others are handed to the agent beside it. A Project can use up to 16 folders, and can mix Git and non-Git folders. From the Cogno desktop app:

• Add Folder opens the operating system’s folder chooser, where you can select several folders at once. They are added to the end of the list. Choosing a different machine from the menu moves the Project there instead. Remote machines use a path entry dialog because their operating system chooser is not available locally.
• A folder that is itself a Git repository gets Separate worktree per Task by default. Expand its row to turn it off and let Tasks work in the folder directly. A folder without Git — including a subfolder inside a repository — simply runs directly (Direct editing); no toggle is shown. The first folder may also be a parent of several repositories and use worktrees.
• A worktree folder has a Base branch inside its row: the branch its Tasks start from, chosen from the repository’s branches (search to narrow a long list). Repository default uses the repository’s default branch.
• Point at a folder and choose Set as primary to move it to the top. The others keep the order they were added in. × removes a folder. Removing does not change or delete anything in the folder. With one folder, × disconnects it.
• A parent of several repositories can use worktrees only as the primary folder. If another folder is set as primary, the parent runs directly, and the section says so.
• A Project someone else owns, with no folders of yours yet, offers Quick setup: its owner’s folders in the same order, with their modes and base branches. For each one, the picker beside it uses a matching checkout already on this machine, clones it from GitHub (when the workspace’s GitHub connection reaches the repository), or lets you choose a folder. Folder paths are never shared.
• A folder that is not on the machine any more is marked Missing; runs skip it until it is back. Remove it before saving other changes to the list.
• Running a Project in several folders needs a recent Cogno on that machine. If the machine’s Cogno is older, the section says Update Cogno on this machine to run a Project in several folders.

In a browser there is nothing local to connect; the section offers Open in the Cogno app instead. The Source Folders and GitHub repository selection are independent. Cogno does not reject a folder because it lacks a repository selected in Project settings.

​

Connectors are on your account now

The Claude Code and Codex connector preference used to sit beside your Environments row, once per project. It is one answer per person now, in Account → Connections — the servers are your own credentials, so the choice follows you. See Your connectors. If no account-level choice has been saved, connector use stays off until you explicitly enable it. What remains here is Project MCP servers: the servers this project’s folder adds on top of your account’s, From this folder, on top of the ones in Account › Connections. It is a list, not a control, so you can see what a run in this folder would reach. A folder that adds none says This folder adds no MCP servers of its own.

​

Edit the project’s memory

Memory is the folder this project’s agents keep between runs: notes, plans, and how-tos they write for next time. Agents find it at /projects/<name>, named after the project and renamed with it. Other Projects’ agents can read it but not change it. Memory on the project’s settings page is an editor for that folder, and it works like a code editor:

• The explorer on the left lists the folder. Click a file to open it in a preview tab, which the next click replaces; double-click to keep it open. The arrow keys move through the tree, Enter opens, F2 renames, and Delete (or ⌘⌫) deletes. Drag a file or folder onto another folder to move it, and drag the explorer’s edge to make it wider.
• Right-click the explorer for New file, New folder, Rename, Copy path and Delete. New names are typed in place; separate folders with /, and any folder that does not exist is created.
• Tabs run across the top. A dot marks a file with changes not yet saved.
• The status bar at the bottom says whether the file is saved, who updated it last — an agent or a person — and when, its size, and its type.

Files are always editable; there is no Edit button to press first. Changes save on their own a second after you stop typing, and ⌘S / Ctrl+S saves right away. Markdown files open as Rich text: headings, lists, checkboxes, tables and code look the way they read, markdown shortcuts such as # and - work as you type, and / inserts a block. Switch to Markdown source, at the top right of the file, to edit the text itself. A front matter block at the top of a file appears as Properties and is edited as text. Opening a file never rewrites it; once you edit it in Rich text, the whole file is written back in one consistent markdown style. Other files open in a code editor with syntax highlighting. You edit memory as the project does, so you can change only what is inside this project’s folder. Without edit access in the workspace, every file is read-only and the status bar says Read only. An agent can save a file while you have it open. If you have not changed it, the new version replaces what you see. If you have, your save never writes over theirs: This file changed while you were editing. appears, with Load latest to take the saved version and discard your edits, or Overwrite with mine to keep yours. Closing a tab whose changes could not be saved asks Discard your edits? first.

​

Project integrations

Project integrations lists the workspace’s connected services, GitHub first. Each connection is its own row and reads like that connection’s page under Integrations, narrowed for this Project: the same heading, the same channel switches, and the same Block / Ask / Allow choices. Two connections to the same service appear separately and keep separate settings. Each GitHub row also contains a Repositories control scoped to repositories available through that connection. Expand a connection to reach its places and Tool permissions. A Project can follow or narrow the Workspace, but it cannot grant more access than the Workspace connection allows. Ask is denied during autonomous runs because nobody is present to approve it. None of these settings add provider permissions or create a separate list of posting destinations. The list is per person: shared workspace connections, plus the ones you authorized yourself. A teammate’s personal connection — their Gmail, or any service they connected individually — is not listed for you, and neither is its address or account name. A connected service Cogno cannot act in yet stays visible with its controls disabled and the reason shown. Existing resource selections stay visible even when the list of choices cannot be loaded. Your Google Calendar connection here is the personal one used for meeting recording — it does not grant general calendar changes. If loading fails, select Retry. If saving an instruction fails, the text you typed stays in the field so you can try again; a failed save is never shown as saved.

​

Archive a project

Archive project at the bottom of the settings page keeps everything — confirming names what it holds: This project has N tasks. They stay with it, and unarchiving brings everything back. The workspace’s default project cannot be archived. Archiving frees the project’s name and its repository set for reuse, so a new project can take either. Archived projects live on their own page, reached from Archived projects at the end of the settings rail’s Projects list: it lists what the workspace has put away, with a search box, and Unarchive on a row brings that project back with its tasks. If a live project has taken the name in the meantime, Cogno asks the returning project for another one and suggests a free one — the project already in the workspace keeps its name. A repository set taken by another project has no such answer, because a project is its repository set: unarchiving is refused, and that project is the one to open.

​

Troubleshooting

For anything not listed here, see Troubleshooting.

​

Resume a document Task blocked by a repository

A Project without repositories does not inherit the Workspace’s only repository. If an older document Task is blocked by a repository it does not need, open the Task, select Review options, then Run directly. The recovery entry remains available when you reopen the Task, before sending another message. This removes the Task’s repository association and uses your connected Project folder directly, without creating a branch or Pull Request. Send your retained draft again to start the Task. Recovery applies to Tasks that have not created a Session or started GitHub delivery. If work is queued or running, wait for it to finish. A Project with declared repositories must use a compatible folder instead. The execution mode applies to every Project using this Environment. Your assigned, unstarted Tasks in those Projects are repaired together when they have no declared Project repositories, Sessions, queued work, or delivery history. New Tasks inherit the Environment’s mode. Started Sessions keep their existing execution location. Choosing another folder changes only your placement for this Project. Other Projects keep their folders. Run in a Worktree switches the selected Environment back to Worktree execution for new Sessions.

​

Resume code work in the selected repository

If a Task names a different repository from the Git folder you want to use, you can replace that association and start in a separate worktree. The choice also repairs your eligible, assigned, unstarted Tasks in Projects using this Environment. Choosing another folder applies that folder’s execution mode through the same recovery. The same recovery restrictions above apply. If the current folder contains a Git repository, Run in a Worktree can switch its Environment from Direct mode without choosing another folder. Recovery does not move an existing Session or convert its working directory.

​

Related docs

• Work with tasks — the tasks that gather on a project’s page.
• Task views — the four layouts and query bar available on the project page.
• GitHub — connect the repositories a project is about.
• Getting started — set up the desktop app and your machine.
• Memory — shared workspace and Project files, including instructions and skills.