cockpit project

This reference is generated from the same canonical source distributed as cockpit CLI help. See Cockpit CLI for concepts and safe operating guidance.

A project groups one or more folders under a name. Tasks belong to a project: the sidebar, the overview board, and the PWA group tasks by project, and the agents of a task can use every folder of its project. The first folder is the primary folder, where new tasks start unless another folder of the project is chosen. The same folder can belong to several projects, and several projects can share a name. The same operations are available in Settings > Projects (cockpit open settings projects) and in the PWA. Every command returns JSON and is local-only.

cockpit project list
cockpit project get <id|name>
cockpit project create --name <name> [--folder <path> ...]
cockpit project update <id|name> [--name <name>] [--add-folder <path>]... [--remove-folder <path>]... [--primary-folder <path>]
cockpit project update <id|name> --folder <path> [--folder <path> ...]
cockpit project delete <id|name>
cockpit project icon get [--project <id|name> | --directory <path>]
cockpit project icon set <image-path> [--project <id|name> | --directory <path>]
cockpit project icon reset [--project <id|name> | --directory <path>]

A project is {"id","name","folders":[{"path"}],"createdAtMs","updatedAtMs"}. list returns {"projects":[...]}; get, create, and update return {"project":{...}}.

cockpit project create --name "Shop" --folder ~/repos/shop-web --folder ~/repos/shop-api
{"ok":true,"data":{"project":{"id":"8c1f...","name":"Shop","folders":[{"path":"/Users/me/repos/shop-web"},{"path":"/Users/me/repos/shop-api"}],"createdAtMs":1790000000000,"updatedAtMs":1790000000000}}}

<id|name> matches a project ID first, then an exact name. When several projects share the name, the command fails with ambiguous_project and lists the candidates with their IDs in details.candidates; pass the ID instead. An unknown project fails with project_not_found.

Folder paths are resolved to absolute paths, and ~/ stands for the home folder. --folder on create and --add-folder on update must be existing folders, otherwise directory_not_found. create without --folder makes a folder for the project, projects/<id>/<name> inside Cockpit's data folder, the same place Cockpit keeps per-project data; the folder is empty and is not a git repository, and the project's folders in the response shows its path. update removes the --remove-folder folders, appends the --add-folder folders, and then moves --primary-folder to the front. --folder on update replaces the whole folder list in the given order, which is how folders are reordered; it cannot be combined with --add-folder, --remove-folder, or --primary-folder. A --remove-folder or --primary-folder that is not in the project fails with folder_not_in_project, and removing the last folder fails with project_folder_required. Removing a folder does not move any task out of the project.

delete removes only the project. Its tasks and folders are untouched; the tasks move to "No project" and are listed in detachedTaskIds.

Which project a task joins

A new task takes the first of these that applies:

1. --project on cockpit task create or task run, or the project chosen in the New Task screen.
2. The parent task's project, for a child task.
3. For a worktree task, the folder the worktree was created from; for a Fleet task, the Fleet's folder. Rules 4 and 5 then use that folder instead of the working folder.
4. A project whose primary folder is the working folder, otherwise the most recently used project that contains it.
5. A new one-folder project named after the working folder.

Tasks started without a folder of their own (a temporary or persistent folder that Cockpit creates for the task, and task create without --directory) belong to no project, and so does every later task that works in one of those folders, unless rule 1 or 2 gives it a project. The sidebar and the PWA list these tasks by folder, as they did before projects existed, and show any other task without a project, such as a task of a deleted project, under "No project". Master tasks and Creative Studio tasks never belong to a project. Move a task later with cockpit task project <task-id> <id|name>; its child tasks move with it.

Only projects can be renamed or given an icon. The menu of a folder group (a Cockpit-made folder, Master, or Studio) offers pinning, opening and copying the folder, and the bulk actions. The group of a persistent folder (~/.agi-tools/workspaces/persistent-…) also offers Make it a project, which creates a project with that folder under the group's name and moves the group's tasks into it, as cockpit project create --name <name> --folder <folder> followed by cockpit task project <task-id> <id|name> does; temporary folders do not offer it. Once a folder Cockpit made for a task belongs to a project, it is kept when that task completes or is deleted.

Folders a task can use

Each time a task's agent session starts or resumes, the agent receives the working folder plus the project's other folders, read from the project at that moment. A folder added to a project is available from the next session on. Git, AGENTS.md, CLAUDE.md, and worktrees stay tied to the working folder; a worktree replaces only the folder it was created from, and the other folders are used in place.

In Cockpit Agent tasks and the visual UIs, the agent is told the paths of the other folders when its session starts, whatever its approval mode: Claude in its system prompt, Codex in its developer instructions, and Cockpit Agent, Antigravity, Cursor, Qoder, Grok, and Muse Code in a note sent ahead of the first message of the session. The chat shows only what was typed, and a slash command leaves the note for the next message. Cockpit Agent and the visual UIs of Claude and Codex can also read and write the other folders, Antigravity receives them with --add-dir, and Muse Code's visual UI receives them as additional workspace roots on every turn, so a folder added to the project is available from the next message. Muse Code's terminal UI has no option for extra folders and is not told them. The terminal UIs of Claude, Codex, Cursor, and Qoder receive the other folders with --add-dir, and Grok's terminal UI is told them with --rules; Codex's terminal UI with full access is not told their paths.

On the desktop, the task header shows the task's project; opening it lists the folders the task's agent received when its session started, with the working folder marked, and notes the folders added to or removed from the project since then. cockpit task reconnect <id> restarts a visual task's agent in place, so it receives the project's current folders. Project details, in a project's sidebar menu and on each project's row of the New Task picker, on the desktop and in the PWA, shows the project's name and folders, edits them, and deletes the project.

Icons

project icon reads and changes the icon shown next to a project in the sidebar, in the overview board, and in the PWA task list. --project targets a project. --directory targets the folder's project, found as in rule 4 above; it defaults to the current working directory and is resolved to an absolute path. A folder that belongs to no project, such as the master folder, keeps its own folder icon. --project and --directory cannot be combined.

get returns the icon that is actually rendered for the project. projectId and name identify the project (null for a folder without one) and directory is the folder the icon is detected from, the primary folder for a project. source is user when someone chose the icon, detected when Cockpit found it inside that folder (public/favicon.svg, a web manifest icons entry, apple-touch-icon.png, favicon.ico, and the other fixed candidates), and none when the project falls back to the default folder treatment. dataUrl is the encoded image and bytes its length.

cockpit project icon get --project Shop
{"ok":true,"data":{"projectId":"8c1f...","name":"Shop","directory":"/Users/me/repos/shop-web","source":"detected","dataUrl":"data:image/svg+xml;base64,...","bytes":246}}

set takes a path to a local image file. Nothing is ever fetched over the network. The file must exist, carry one of svg, png, webp, jpg, jpeg, gif, avif, ico, and its contents must match that extension — a renamed text file is rejected with unsupported_image. Files above 16 MB are rejected with file_too_large, and a missing path with file_not_found. A raster image is decoded and normalized to a 32 px square before it is stored, so a large PNG or JPEG is fine. An SVG is stored as-is and is never resized, so it must stay under the 64 KB encoded ceiling — roughly a 47 KB source file. A valid image that does not fit once encoded is rejected with image_too_large_encoded, which is a different code from unsupported_image so it is distinguishable from a file that is not an image at all. The chosen icon is persisted per project, survives a restart, and is pushed to open windows and connected PWA clients immediately.

reset removes the chosen icon and returns the project to the automatically detected icon, or to the default folder treatment when there is none. It re-runs detection, so it is also the way to pick up an icon that was added to the folder after Cockpit first looked.

cockpit project icon set ./public/favicon.svg --directory /Users/me/repos/app
cockpit project icon reset --project Shop