Troupe Docs
Getting started

Manage projects

Switch, rename, color, group, archive, and delete projects.

The Projects section of the sidebar on the left of the window holds all your projects. This page shows how to keep it in order.

Switch projects

Select a project in the list. Each project shows its chats under its name. See Find and resume chats. You can also:

  • Press Ctrl+1 to Ctrl+9 (Cmd+1 to Cmd+9 on macOS) to switch to one of your first nine projects. Hover over a project to see its key.
  • Open the command palette and type the project name.

Projects keep running in the background

When you switch to another project, the one you leave keeps running. Its terminals keep their commands going, its agents keep working, and its tabs stay as you left them. When you come back, everything is where it was.

Some switches take a moment. If so, Troupe shows Switching project… and keeps the old project on screen until the new one is ready.

Each project in the list shows what happens inside it:

  • A spinning circle means something is running.
  • A gray dot means an agent chat is open and waiting.
  • A colored badge with a number means chats need your answer. Select the badge to open the chat.
  • Crashed means a terminal in the project crashed.
  • Green and red numbers, such as +10, count the lines added and removed in changes you haven't committed yet.

Change a project

Right-click a project to open its menu, or hover over it and select the … button (More actions).

The menu has Settings, Rename, Change color, Default shell, Move to group, Switch worktree…, New worktree, Archive, and Delete. Switch worktree… picks the working copy the project uses. See Worktrees.

The + at the end of a project's row starts a new chat in that project.

Rename a project

  1. Right-click the project and select Rename.
  2. Type the new name and press Enter. Press Esc to cancel.

Renaming changes only the name in Troupe. The folder keeps its name.

Change the color

  1. Right-click the project and select Change color.
  2. Select a color.

The color shows on the project's icon in the list and in the command palette.

Change the default shell

Right-click the project, point to Default shell, and select a shell. New terminals in this project use it.

Open the project settings

Hover over the project and select the gear icon (Project settings), or right-click it and select Settings. The Project settings window opens for that project, even if you have another project open. Its pages are General, Shell, Environment variables, Worktree symlinks, Accounts, and Browser. See Project settings.

Reorder projects

Drag a project up or down in the list.

Group projects in folders

A folder group collects projects under one heading in the list. Groups exist only in Troupe. They don't move any files.

The projects list with a Client work group that holds payments-api and acme-shop, and an Archived section with the blog project

To create a group:

  1. Select + next to Projects, then select New folder group.
  2. In Group Folder Name, type a name.
  3. Select Create.

To put a project in a group, use one of these:

  • Drag the project onto the group.
  • Right-click the project, point to Move to group, and select the group. Select No group (root) to take it out again.
  • Right-click the project, point to Move to group, and select Create new group… to make a group and move the project into it.

Select a group's name to collapse or expand it. Drag a group to change its place in the list.

Right-click a group, or select the … button next to it (Group actions), for these actions:

  • Rename group and Change color.
  • Add project lists your projects with check boxes. Select a project to add it to the group or take it out. Import project… at the bottom picks a folder and adds it as a new project in this group.
  • Delete group (keep projects) removes the group and moves its projects back to the main list.
  • Delete group and all projects removes the group and every project in it from Troupe.

Groups and the order of the list are saved in this browser or on this computer. They don't follow you to other devices.

Archive a project

Archive a project to move it out of the way without removing it.

  1. Right-click the project and select Archive.
  2. If chats or terminals are still running in it, Troupe asks first. Select Stop and archive to stop them and archive the project, or Keep project to cancel.

Archived projects move to the Archived section at the bottom of the list. Select the section to show or hide them. You can still select an archived project to open it.

To bring a project back, right-click it in Archived and select Restore.

Delete a project

Deleting a project removes it from Troupe. Troupe doesn't delete the folder or any files in it.

  1. Right-click the project and select Delete.
  2. Select Delete to confirm.
  3. If chats or terminals are still running in the project, Troupe asks again. Select Stop and delete to stop them and delete the project, or Keep project to cancel.

To use the folder again later, add it as a project. See Add a folder you already have.

On this page