Projects & icons

A project is a folder that one of your machines knows about. Glueprint derives each project’s identity from its git remote, so the same repository checked out on your laptop, your desktop, and a build server lines up as one project everywhere — one name, one icon, one colour.

There is nothing to configure. The machine that holds the folder works the identity out, and refreshes it when the folder’s git settings change.

How projects group across machines

Glueprint reads the folder’s configured git remotes and picks one:

1. origin, if it exists.
2. Otherwise the only remote, if there is exactly one.
3. Otherwise the first remote by name.

The chosen URL is reduced to a host and a path. The result ignores case, drops a trailing .git, and drops the protocol’s default port, so every way of writing the same remote lands on the same identity:

• git@github.com:Acme/Widget.git
• https://github.com/acme/widget
• ssh://git@github.com:22/Acme/Widget.git

All three identify github.com/acme/widget. Two machines that hold that repository under completely different paths — ~/code/widget on one, D:\src\Widget on the other — show as a single project, and expanding it lists each machine’s worktrees underneath.

The name on the group is the repository’s own name. The name you gave the folder on a given machine is kept and shown on that machine’s row.

If the chosen remote cannot be read as a URL, the project falls back to the folder rule below. Glueprint never tries a second remote: the identity would then depend on which remotes a particular checkout happens to have.

Folders that are not repositories

A folder with no git repository, or a repository with no remote, is identified by its folder name, lowercased.

Two unrelated folders that share a name — two different projects both called app — therefore appear as one group. That is deliberate: the folder name is the only cross-machine signal such a folder has. Give one of them a git remote, or rename the folder, if you want them apart.

The project icon

Glueprint looks inside the repository for an icon and uses the first file it finds, in this order:

1. public/apple-touch-icon.png
2. apple-touch-icon.png
3. public/favicon.svg
4. favicon.svg
5. public/favicon.png
6. public/icon.png
7. public/logo.png
8. favicon.png
9. app/icon.png
10. src/app/icon.png
11. public/favicon.ico
12. favicon.ico
13. app/favicon.ico
14. static/favicon.ico
15. src-tauri/icons/icon.png
16. assets/icon.png
17. src/assets/icon.png
18. public/icon.svg

PNG and PNG-backed ICO files up to 8 MiB, with image dimensions up to 1024×1024, are automatically resized to 128×128 thumbnails. The original file stays unchanged, and loaded thumbnails are cached in memory; the host also keeps optimized copies in its application cache. SVG files remain limited to 256 KiB and must pass Glueprint’s safety rules: a viewBox or explicit pixel dimensions are required, and scripts, external references, embedded images, text, masks, filters and dashed strokes are not supported. Every icon is converted into a small picture on the machine that holds the repository, so an unsupported SVG simply falls back to the next file in the list or the letter avatar.

When several machines hold the same repository and disagree about the icon — one checkout has a newer favicon, another has none — one icon wins for the whole group, and every surface on every device shows that same one:

• A machine with no icon never beats a machine that has one.
• The icon highest in the list above wins, so apple-touch-icon.png beats favicon.ico.
• If two machines report the same file, the more recently modified copy wins.
• If the winning machine is offline, Glueprint uses a copy it has already cached; otherwise it moves to the next machine in the same order.

On the Free plan, icons from other machines show as letter avatars. Icons from the machine you are on still show in the desktop app.

Icons render in the sidebar’s project rows, the workspace header and its details sheet, the projects list on the workspace home, and the pickers for a new session or a new terminal. Denser lists keep the letter avatar, which stays legible at small sizes.

The letter avatar

A project with no icon shows initials in a filled rounded square. Both the initials and the colour come from the project’s identity, not from the folder name you chose, so the same repository gets the same avatar on every machine, in the desktop app, in the web portal, and on your phone.

Adding a project

Add a project by pointing Glueprint at a folder, or by cloning a repository. You are asked for a name and a location, and the name is prefilled from the repository or the folder. There is no tagging step and nothing to pick.

The desktop app’s Settings > Projects lists this machine’s projects, and each row shows the repository identity, how many roots it spans, and how many machines hold it. In the portal and on mobile, a machine’s project list lives under Settings > Hosts > (host) > Projects.

Machines that have not updated yet

A machine running an older Glueprint reports no identity. Until it updates, Glueprint identifies that machine’s projects by their folder names, so a repository held by one updated machine and one old machine can appear as two groups for a while. Update the older machine and the two merge on its next connection. Nothing is lost and no work has to be moved.

Creating a project on a machine that has not updated registers a temporary entry for it. That entry is adopted into the real project the first time the machine reports its identity, and its board comes with it.

Boards, tasks, and teams

A board or a task can be scoped to a project. Those pickers list your organization’s projects — one entry per repository, shared by every machine that holds it — so a task created on one machine can start a session on whichever machine has that repository.

A project appears in those lists when you can see at least one machine that reports it.

What changed from project tags

Project tags are gone. They were the old way to link a project across machines and to colour it.

• Nothing needs tagging. Identity comes from the repository.
• Tag scopes (personal, team, organization) no longer exist. A project is visible to whoever can see a machine that holds it.
• The “this tag is not allowed on this host” prompt is gone.
• Boards, tasks, and teams that were pinned to a tag keep working; the pin now names the project.
• Tags you had archived come back as ordinary project entries in the pickers. Boards that were archived stay archived.

Related topics

• Sessions > Search and filter for finding work across many projects.
• Tasks and boards for the higher-level work tracking.
• Settings for where each of these screens lives.