Projects & Workspaces

Open a repo, give each piece of work its own folder, clean it up after.

The three things in the tree

Project is a directory you opened. If it is a git repository, Kumo resolves it to the main repository root, so opening a worktree of a repo you already have adds nothing; it just ticks that worktree. A plain folder can be a project too, it just has no worktrees.

Workspace is a folder an agent can run in. For a git project that is the main checkout plus every worktree you added; for a plain folder it is that one folder. The main checkout is a Workspace like any other, so select it explicitly; selecting the project does not imply it.

Agent is one conversation, bound to one Workspace. You cannot start an agent with a project row selected, because a conversation has to have a folder to run in.

A Workspace can also belong to a Task, the piece of work it is for. When it does, its row carries the task’s #N in small type. Hover it for the link.

Kumo never scans your disk for repositories. A cold start is empty on purpose.

Import a project

Use the folder icon next to PROJECTS, the button in the middle of an empty window, or ⇧⌘O, and pick a directory. If it is a git repository, Kumo also offers the worktrees that git worktree list already knows about, so you can tick the ones you want on the tree.

Opening the same path twice focuses the project you already have. There is never a second copy.

A worktree you made later in a terminal does not appear by itself. Press the branch icon on the project’s title row (Join worktrees) and tick it there.

Managed projects

Sometimes there is no repository yet. The + folder icon next to PROJECTS (New managed project) asks for a name, creates the folder under ~/KumoProjects/, and can run git init with an empty first commit, so worktrees work straight away. After that it is an ordinary project.

The one difference is at the end: closing a managed project offers to delete its folder, because Kumo is the one that made it. Closing any other project never touches the disk.

New Workspace

Press + on a project’s title row, right-click it → New Workspace, or ⇧⌘N. One dialog:

• Branch. Type it, or pick from the list. A branch that exists locally or on origin is checked out into a new worktree. One that does not exist is created from the project’s base branch, which is origin/HEAD unless you set otherwise in project settings.
• Label. What the row is called in the sidebar. It is independent of the branch, and renaming it later does not touch git.
• First agent. Ticked by default: pick which agent, and keep or reroll the name. The button then reads Create & Chat, and you land in a fresh conversation on the new folder instead of pressing + again.

The list under the branch field has up to three groups, in this order:

1. TASKS: this project’s open tasks, the recently active first. Pick one and the dialog is filled the same way Start a Workspace… on the Tasks page fills it, and the new Workspace joins that task.
2. ISSUES & PULL REQUESTS, when the project’s origin is on GitHub and gh is signed in. Pick an issue and the branch is decided for you (<number>-<slug>). Pick a pull request and it is that PR’s head branch, fetched from wherever it lives, including a fork, which Kumo adds as a remote so your pushes go back to it. A banner warns once if the fork has maintainer edits turned off.
3. Branches, local and remote.

When you start from an issue, a pull request or a task, the first prompt is filled in with its title, body and link, plus a line telling the agent which task it is on. It is not sent until you press Enter.

The folder lands at ~/worktrees/<repo>/<branch>, with / in the branch turned into -. Reusing a branch lands in the same folder, so an agent’s per-folder history carries on. Change the root in Settings → General, or per repository in project settings.

Branch already used by another worktree? Kumo takes it back rather than refusing. A stale record is pruned, and a real folder somewhere else is moved, uncommitted changes and all, to the new path. The one case it still refuses is a branch the main checkout has checked out, because that one cannot move.

The sidebar

The left column has PROJECTS on top and AGENTS underneath, splitting the height evenly. Drag the line between them to change that, and double-click it to even it out again.

• Drag rows to reorder. Projects move freely. A Workspace moves only within its own project. The order is saved and survives a restart.
• Right-click a project for New Workspace and Close Project.
• Right-click a Workspace for Rename Workspace (the label only; the main checkout’s row always shows its current branch) and Delete Workspace.
• The gear on a project’s title row opens its settings, see below.

AGENTS lists every agent in every project, not just this Workspace. Each row answers who it is (the name), what it is doing (its summary), where it is (project · workspace), and how long ago it last said something. The status is both a dot and a word:

The order is the order of urgency: needs you, then unread, then the rest, each newest first. A row that flickers between running and idle does not jump around. Click a row to go to that agent, wherever it is; right-click it to rename, reopen or close it.

Delete a Workspace

Right-click the Workspace → Delete Workspace. It stops every agent on that folder, then runs git worktree remove. There is always one confirmation, even when the folder is clean.

If it is not clean (uncommitted changes, untracked files, or commits no other ref points at), the first attempt refuses and tells you which. A second confirmation forces it. Kumo will not throw away work quietly.

The main checkout cannot be removed. Close Project takes the project off the tree and stops its agents; the repository stays on disk. Closing a plain-folder project never deletes the folder.

If a folder disappears from under Kumo (you deleted it in a terminal), the row is marked lost, its agents stop, and taking it off the tree only edits the register.

Project settings

The gear on a project’s title row. Two things, both stored with the project rather than in the app, so they survive reinstalling:

• Base branch: what new branches fork from. Empty means origin/HEAD.
• Worktree directory: where this repository’s worktrees go. Empty means the global default.

Both only affect Workspaces created afterwards.