App links (agentsroom://)

  • Desktop, mobile and web
  • All plans

What it does

A link that brings AgentsRoom to the front on the right place: an agent's console, a project, or a backlog ticket on its board. Another tool (a Git client, a script, a dashboard, a note, a chat message) puts the link next to a worktree or a task, and one click lands the user there instead of hunting through projects and tabs. Links only navigate: they never start an agent, send a message or change anything, so a link found on a web page or in an e-mail cannot make the app act.

Where to find it

No setting: the desktop app registers the agentsroom:// scheme with the system when it is installed (macOS, Windows, Linux), and the mobile app registers it on iOS and Android. Agents get ready-made links from the AgentsRoom tools (see below).

How to use it

Three routes:

  • agentsroom://agent/<agentId>: focuses that agent's console, in whichever open project holds it.
  • agentsroom://project/<projectId>: selects that project.
  • agentsroom://ticket/<ticketId>: selects the ticket's project and opens its backlog board on that ticket.

Each route has an HTTPS form, https://agentsroom.dev/agent/<id>, https://agentsroom.dev/project/<id> and https://agentsroom.dev/ticket/<id>: a small page that tries to open the app and offers a retry button and the download link. Use it where custom schemes are filtered (some chat apps, e-mail clients, documents).

Where the ids come from:

  • Agent: agents_list_live (complete answer) and agents_spawn return deepLink and webLink for each agent; the Local status API lists agents with their id on /v1/agents.
  • Project: the id returned by projects_list or by the local status API on /v1/projects. It is the account-wide id of the project, the same on every computer and on the phone (the project's own id when it was never synced).
  • Ticket: the ticket id returned by backlog_list, backlog_get or the local status API on /v1/backlog. Not the #42 number, which is only unique within one board.

Opening a link from a terminal:

open "agentsroom://agent/<agentId>"          # macOS
xdg-open "agentsroom://project/<projectId>"  # Linux
start "" "agentsroom://ticket/<ticketId>"    # Windows (cmd)

When several copies of the same repository are open as separate projects, an agent link lands on the copy that runs the agent's console; a project or ticket link stays on the copy on screen when it is one of them, else picks a copy that has a folder on disk. If the app is closed, the link starts it and waits up to fifteen seconds for the projects to load before giving up.

An agent link also finds an agent alive on another computer of your account, a trigger's agent included, and opens its real console over there, unless that agent has a console on this computer too (this one then wins). It never starts anything: an agent with no live console stays a click in the app.

An id that matches nothing open on this computer or alive on another one shows a short message and changes nothing. A malformed link is ignored.

Settings

None.

Agent tools (MCP)

  • agents_list_live, agents_spawn: return deepLink and webLink for each agent. Prefer webLink in messages, reminders and documents.
  • projects_list: the project ids to build a project link.
  • backlog_list, backlog_get: the ticket ids to build a ticket link.
  • ui_open (surface agent): the same focus, asked by an agent from inside AgentsRoom.

Providers

All providers, no difference: a link names an agent, a project or a ticket, never a CLI.

Mobile

Same three routes on iOS and Android. On a cold start the app restores the account and the connection to the computer first, then navigates. An agent of another computer is reached through the account's computers; a computer that is offline must come back online to open its console. An id it cannot find shows a message with a Retry button.

Limits

  • A link only reaches what the signed-in account already sees: knowing an id grants no access.
  • A ticket link resolves tickets of your own boards; a ticket of a team board shared with you is not reached by its link yet.
  • A project link reaches a project already open in the desktop app on this computer; it does not clone or add a project.
  • The HTTPS page may need one extra click: browsers ask before handing a link to an app.

Common questions

  • Can my Git client show an "Open in AgentsRoom" button next to a worktree? Yes: read the agents of the project from the local status API (/v1/agents?project=<path>) and open agentsroom://agent/<id>. For the project itself, use agentsroom://project/<id> with the id from /v1/projects.
  • The link does nothing on my Mac. Update the app: versions before the fix did not declare the scheme to macOS. On macOS, /System/Library/Frameworks/CoreServices.framework/Frameworks/LaunchServices.framework/Support/lsregister -dump | grep agentsroom should list the app.
  • Can a link start an agent or run a task? No. Links only navigate; every action stays a click inside the app.
  • What happens with a wrong id? A message says the target is not open on this computer, and nothing changes.
  • The link points to an agent running on my other computer. It opens its console from here as long as that computer is online and the agent is alive; otherwise you get the same message.