Projects

A project is a folder on disk that holds its own agents, processes, worktrees, conversation history, todos and scratchpads.

Add a project##

Open the projects page and choose Add project. You can also open the command palette with Ctrl+K and choose New project.

In the New project dialog:

1. Enter the directory in Path, or choose Browse… to pick it. In a browser the field is called Server path, because the folder lives on the machine running Patterm, not on the device you are browsing from.
2. Optionally enter a Name. It defaults to the directory name.
3. Choose Create project.

The path must be an existing directory. It does not have to be a git repository, although worktrees only make sense in one. Adding a path that is already registered opens the existing project instead of creating a second one.

You can rename the project, change its logo or remove it later from the projects page.

Switch projects##

The project button at the left of the top bar shows the current project. Hover over it or click it to list your projects. Each row shows the project logo, a dot when something in it needs your attention, and the number of open agents. Choose a project to open it.

The last entry, Project selector, takes you to the projects page.

You can also reach any project from the command palette (Ctrl+K). Projects other than the current one are listed by name, with their path beside them.

The projects page##

The projects page is the overview across all of your projects. It is where Patterm opens at /projects, and it is the page Project selector leads to.

Each project shows:

• its logo and name, and its path with your home directory shortened to ~;
• how many of its agents need you, are working, or are idle;
• the time it was last active, when it has no agents running;
• a Launch agent button;
• one row for each running agent, with its status and its latest summary. Choose a row to open that agent.

The page header counts your projects and the agents running across them.

Each project on this machine also has a ⋯ button with Rename…, Change logo… and Remove…. Projects shown from a paired host have no ⋯ button; change them on their own host.

Rename a project##

Choose ⋯ › Rename…, enter the new name and choose Save. Only the name Patterm shows changes. The folder keeps its name.

Change a project logo##

Choose the logo beside a project's name, or ⋯ › Change logo…. In the Project logo dialog you can:

• pick an image Patterm found in the project, such as a favicon or logo file;
• choose Upload image… to use your own;
• choose Use monogram to go back to the default letter logo.

Remove a project##

Choose ⋯ › Remove…. The dialog says how many of the project's agents are running, and Remove project confirms. Removing a project:

• stops its running agents and processes;
• deletes everything Patterm holds for it: its agents and processes, worktree records, todos, scratchpads, links, routines, timers and imported conversation history;
• unlinks it from any paired host.

It does not touch files on disk. The project folder, its worktree folders and its branches stay. Removal can't be undone, but you can add the folder again as a new project.

The Personal project can be renamed but not removed. Turn it off in Settings › Appearance › Navigation to hide it.

Project pages##

Each project has pages for the records that belong to it:

How you reach these pages depends on the navigation layout you chose in Settings › Appearance › Navigation:

• Tabs: open the command palette (Ctrl+K) and choose Todos, Scratchpads, Worktrees, Conversation history or Media. Agents takes you back to the terminals.
• Sidebar: the project pages are icons at the bottom of the sidebar.

In the browser, each page has its own URL, so you can bookmark it and use Back and Forward:

Opening a link to an agent or process does not resume a stopped agent or start a process.

The project board##

In sidebar mode, a project's own page is a board of its agents, grouped by what needs you, what is working, what is waiting, what is done and what is quiet. Each agent shows its full summary. Open the board with the grid button in the sidebar or with Ctrl+Shift+Space, and press Esc to go back to where you were. The board appears once the project has at least one agent.

The Personal project##

Some agents do not belong to any repository. Turn on Personal project in Settings › Appearance › Navigation to get a project for them. It is listed first, works in a private folder in Patterm's data directory, and has no Worktrees page. If you turn the setting off, the project still shows while something is running in it.

Usage##

Select the gauge button (Usage) in the top bar, or on the projects page, to see quota and token use across every project. See Usage.

Projects on several hosts##

When you have paired another machine and linked a project on it, the project shows the other host's name in muted text, and the projects page says which hosts it is linked with. See Multiple hosts.

Related##

• Agents and processes
• Your first project
• Keyboard shortcuts