# 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: | Page | What it holds | | ----------- | ------------------------------------------------------------------------------------------------------------------------------ | | Worktrees | The git worktrees linked to the project. Not shown for the Personal project. See [Worktrees](https://patterm.com/docs/worktrees.md). | | History | Imported conversations from your agent CLIs, searchable and resumable. See [Conversation history](https://patterm.com/docs/conversation-history.md). | | Todos | Independent project todos. See [Todos and scratchpads](https://patterm.com/docs/todos-and-scratchpads.md). | | Scratchpads | Markdown notes. | | Media | Every image pasted into or viewed in the project's conversations, filtered by pasted or viewed. | 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: | Page | Path | | ----------------- | ----------------------------------------- | | Projects overview | `/projects` | | A project | `/projects/` | | An agent | `/projects//agents/` | | A process | `/projects//processes/` | | Worktrees | `/projects//worktrees` | | History | `/projects//history` | | Todos | `/projects//todos` | | Scratchpads | `/projects//scratchpads` | | Media | `/projects//media` | 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](https://patterm.com/docs/usage.md). ## 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](https://patterm.com/docs/multiple-hosts.md). ## Related - [Agents and processes](https://patterm.com/docs/agents-and-processes.md) - [Your first project](https://patterm.com/docs/first-project.md) - [Keyboard shortcuts](https://patterm.com/docs/keyboard-shortcuts.md) --- This is one page of the Patterm documentation. The index of every page is at https://patterm.com/llms.txt.