Prerequisites
- A workspace you can write in.
- GitHub connected, to choose repositories — see GitHub. Without it the repository picker reads Connect GitHub to choose repositories.
- 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: the same query bar the Tasks page
carries — minus the Project criteria, since the page already is one project —
then what is running right now, one section per person, and the status groups
under that. Drag rows between sections to move them; a long list loads as you
scroll (Load more — showing 50 of 240).
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.
A folder that is already an environment, and a repository whose set already is
a project, stay on their list and go unclickable — Already added and
Already a project on hover. One repository set is one project, so picking a
spent row cannot make a second one; reaching the same folder through Open
folder… opens the project it already belongs to instead.
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 shortcut nobody can take is only
taking a slot from one they could.
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. Coming in through GitHub there is no folder yet, so Cogno asks the Engine which directories on this machine hold the whole set:- Exactly one — that is the folder, and it is bound with no further question.
- None — the OS chooser asks where to put it, and the repositories are cloned there.
- Several — the project lands without an environment and its page asks, because choosing between them would be a guess.
Configure the project
Open Project settings from the ⚙ on the project’s sidebar row. Inside settings, the sidebar becomes the settings navigation. With five or more projects, Projects starts folded on Account and Workspace settings so those sections stay in reach. Four or fewer projects stay visible. Select Projects to show every project and move between their settings. Cogno opens the list while you are in Project settings or Archived Projects, and while you search it. 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
Environments is one answer per person: the folder on your own computer this project runs in. Your row is first and is the only one you can change — teammates’ rows are read-only, their paths visible only to them (Folder path visible only to its owner). A row with no folder reads No folder connected. From the Cogno desktop app:- Choose folder connects an existing folder (or Change folder swaps it). Agent sessions run in Git worktrees, so the folder needs a Git repository; the connect dialog can initialize an empty folder for you.
- Clone repositories clones every repository in the project into a location you pick (Location, Browse), then uses that as your environment. If Browse is unavailable in an older Desktop, type the absolute path directly into Location.
- Disconnect folder unbinds it — This project will have no folder on your machine until you connect one again. The Environment stays registered, and nothing in the folder is changed or deleted.
An environment must hold every repository in the project’s set — that is how
the repository list decides where work can run. Widening the set can leave a
folder short; the affected person clones the missing repository or connects
a folder that has them all.
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.Project integrations
Project integrations lists the workspace’s connected services, GitHub first. Each connection is its own row, so two connections to the same service keep separate resource selections.
Expand a service to reach its filter, Tool permissions, and instruction. Select
Save to keep the instruction. A Project can inherit or reduce permission,
but it cannot grant more access than the Workspace connection allows. Ask each
time 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.
Related docs
- Work with tasks — the tasks that gather on a project’s page.
- Task views — the query bar the project page shares.
- GitHub — connect the repositories a project is about.
- Getting started — set up the desktop app and your machine.
- Instructions — the standing workspace rules that apply everywhere.