Links and tags

Links that mocante opens go to your system browser. A browser router such as Finicky can send each link to a browser and profile of its own: a client’s project to that client’s Chrome profile, a work host to your work Firefox profile. mocante tells the router what a link is about through its window title, and tags on your projects, workspaces and hosts give the router something to match.

Tag projects, workspaces and hosts

Open the edit dialog of a project, a workspace or a host, and add tags in the Tags field.

• A tag uses lowercase letters, digits and -, _, . or /, up to 32 characters. One record holds up to 16 tags.
• Spaces become dashes and a leading # is dropped, so #Client Acme becomes client-acme.

A session carries the tags of its project, its workspace and its workspace’s host together. If you tag a project client-acme and a host work, every session of that project on that host is #client-acme #work.

Tags sync between your devices with the rest of your configuration.

The window title

Each main window’s title names what it shows:

api · acme @ build-vm #backend #client-acme #work — mocante

That is the workspace, the project, @ and the host, then the session’s tags, then — mocante.

• A project page shows only the project and its tags.
• The fleet and the Hosts screen show mocante alone.
• A pop-out window puts its session and pane first: auth-retry · Code — api · acme @ build-vm … — mocante.

Some links belong to another session than the one on screen, for example a pull request badge on a card in the fleet. When you open one, the title changes to that link’s session for two seconds, while the browser takes the link.

The format is stable, so rules you write against it keep working. In a rule, match:

• a tag with #tag followed by a space or the end of the tags,
• a host with @ name,
• a project with · name.

Route links with Finicky

Finicky 4.4 and later (an alpha release in September 2026) reads the window title of the app that opened a link, as opener.windowTitle.

1. Install Finicky 4.4 or later.
2. Give Finicky the Accessibility permission in System Settings → Privacy & Security → Accessibility. It needs this to read window titles.
3. Add rules to ~/.finicky.js, like the example below.

~/.finicky.js

const fromMocante = (opener) => opener?.bundleId === "ltd.uplift.mocante";
const tagged = (opener, tag) =>
  fromMocante(opener) && new RegExp(`#${tag}( |$| —)`).test(opener.windowTitle ?? "");

export default {
  defaultBrowser: "Safari",
  handlers: [
    {
      match: (url, { opener }) => tagged(opener, "client-acme"),
      browser: { name: "Google Chrome", profile: "Acme" },
    },
    {
      match: (url, { opener }) => tagged(opener, "work"),
      browser: { name: "Firefox", profile: "work" },
    },
    {
      match: (url, { opener }) => fromMocante(opener) && opener.windowTitle?.includes("@ build-vm"),
      browser: "Firefox",
    },
  ],
};

Finicky runs the handlers in order and uses the first that matches, so put the narrower tags first.

Links opened by programs in a session

A program in a session that opens a link, such as gh pr view --web, a CLI login or a dev server that opens its page, sends the link to your device, on a remote host too. The link opens as if you had opened it from that session, with the session in the window title, so your browser router applies.

This is on by default. To turn it off, open Settings, go to Terminal, and switch off Open links from sessions. Links then open on the host, as they would without mocante.

mocante sets BROWSER in every session to a small script, ~/.local/share/mocante/bin/mocante-open. Most command-line tools read BROWSER, and on a host without a desktop xdg-open uses it too. Only http and https links go to your device. Anything else, such as a file, opens on the host as before.

A link stays on the host, and the host’s own xdg-open takes it, when:

• Open links from sessions is off,
• no mocante desktop window is connected (the web build in a browser tab does not take these links),
• the host sent more than 5 links in 10 seconds.

A host with no xdg-open prints the link in the terminal instead.

Sessions that existed before

A session gets BROWSER when it is created. For a session that existed before, or one you adopted, mocante sets it within a few seconds, but only tabs you open after that inherit it. Open a new tab, or run this in a shell that is already running:

export BROWSER=~/.local/share/mocante/bin/mocante-open

Programs that call xdg-open or open

mocante does not change your PATH. On a Linux host with a desktop, programs that call xdg-open directly open links on the host. To send those links to your device too, put ~/.local/share/mocante/bin first on PATH in that host’s shell startup file. The folder has an xdg-open that forwards links.

Note

On a macOS host, programs that call open directly do not read BROWSER, so their links open in the host’s own browser, without the session in the window title. Most command-line tools try BROWSER first.