Skip to content

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.

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.

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.

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.

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.

A link from a tmux that runs inside a session, or from a separate tmux server such as tmux -L other, opens on your device without the session’s context, because that tmux is not the one mocante shows.

Some command-line tools log in through your browser and then send it back to localhost on the machine they run on. Claude Code’s /login and MCP server logins work this way. When such a login link comes from a session on a remote host, mocante opens it on your device and, for the length of the login, sends that localhost address on your device to the host. Sign in as usual and the tool on the host finishes the login.

mocante stops sending the address 30 seconds after the login completes, or after 10 minutes.

If the port is already in use on your device, the session shows a notice and the browser cannot reach the host. Use the tool’s manual option instead: Claude Code shows a link with a code to paste back into the terminal.

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:

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

mocante also puts mocante-open in ~/.local/bin on each host, so you can send a link to your device from any shell:

Terminal window
mocante-open https://example.com

mocante never replaces a file there that it did not write. mocante-copy sits beside it.

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. mocante does not put this xdg-open in ~/.local/bin, because there it would take links from every program on the host, also from programs outside mocante.