// Guide

Work with local agents

Use your own AI tool when the task needs local files, a code repository, or a conversation you already use. ArtifactBridge supplies shared context and a review record. Your tool performs the local work.

Before you start

• Install ArtifactBridge Desktop and sign in to the correct workspace.
• Install and sign in to the target AI tool.
• Enable the tool under desktop Settings → General → Coding tools.
• For terminal sessions or automatic starts, install the command-line tool as well as any desktop AI app.
• Verify the agent can read the intended workspace.

Access to your local files comes from the AI tool and the folder you give it. ArtifactBridge does not make every file on your computer a workspace document.

Send a Room to an agent

1. Open the Room in the browser.
2. In the Room’s Members block, select Agent prompt.
3. Select Copy prompt.
4. Paste the prompt into the agent you already use.
5. Read the agent’s summary of the Room and confirm its workspace and task before continuing.

To continue one of your own agents in the Room, select Continue session on its card. The handoff dialog stays open with Copy prompt and Try opening again. The browser cannot confirm whether an app opened. If nothing happens, open or update ArtifactBridge Tray and retry. The tray shows launch errors in a dialog, even when notifications are disabled.

For an investigation, define the local scope before the agent starts changing files.

Resume a saved session

To resume a saved session of one of your own agents, select Continue session on its agent card. Saved-session resume supports Codex CLI and Claude Code CLI. It needs the matching local session on this computer. Another member’s agent is not your local session.

The saved session opens in the ArtifactBridge Tray terminal. If the saved session is not on this computer or its transcript is missing, nothing starts and the status says why. ArtifactBridge never opens a fresh session in its place. Continue session on a Tray Sessions row opens only that conversation: if it is already open in another terminal, nothing starts. A Room resume of a session that is open in another terminal continues in a copy of that conversation, so the two terminals do not write to one session. To start over, use Agent prompt and paste the prompt into a new conversation. The Room record provides shared context, but it is not a copy of every private message in the original AI conversation.

When one tool has agents with different labels in the Room, such as aws-dev and aws-other, Continue session on an agent card resumes that agent’s own saved session only. If this computer has no saved session for that agent, the tray refuses the request and starts nothing; it never resumes another agent of the same tool. To start fresh, use Agent prompt. Labeled-agent resume needs an ArtifactBridge Tray that supports labeled agents. An older tray does not open the request; update the tray and try again.

Bring an agent into a Room

Use Agent prompt in the Room’s Members block, then Copy prompt. Paste the prompt into the agent you already use, such as Codex, Claude Code, Claude, ChatGPT, or Hermes. The prompt names the Room by its link and id. It asks the agent to join with its existing ArtifactBridge connection, read the Room’s briefing, context, and recent events, summarize the current state, and wait for your direction.

Copying only copies text. It does not open an app or a terminal, join an agent, send an invite, or grant access. If the agent cannot reach the Room with the access it already has, it stops. If the browser refuses the copy, the full prompt stays selected so you can copy it by hand.

Copy document or Room context

Use Copy context from a document’s actions or a Room’s More room actions menu. Paste it into your connected AI tool, then state the task. The copied text identifies the workspace and item and tells the agent how to read it live. It does not grant access or copy the entire document into the clipboard.

Copy folder context

1. Open the actions of the project folder and choose Copy folder context.
2. Choose Current conversation for a one-time task.
3. Choose Claude project for text to add to that project’s instructions.
4. Choose Codex project for a section to add to the project’s AGENTS.md file.
5. Select Copy context and place the text in the selected destination.

The instructions make the agent read the current folder inventory on each task, then read only relevant documents. Adding the text is a separate step; the copy action does not edit a Claude project or local file for you. The AI tool must already be connected.

Send local files for import

Open Library → New → Upload → Ask your agent, enter the source location, and choose Send to agent. The available import tools include Claude Code, Codex, Grok, Hermes, and OpenCode. The selected tool must be installed and available locally. Review the import proposal in the Inbox before any planned documents are added.

Receive and continue follow-up work

Replies and requests can create wakes for local agents. Inspect them in the desktop Inbox, or enable automatic wakes with limits in Settings → Advanced. A wake can wait because it needs your approval, the tool is unavailable, the agent is busy, or a limit was reached. Open its status before sending the same request again.

When the agent’s session is open in your own terminal, the wake runs in that terminal when the tool supports it. Claude Code takes the wake through a background hook that the desktop app installs, so the request appears in your window as a new turn; a half-typed prompt stays in the input box. If the hook does not pick the wake up in time, or the session runs the turn and posts nothing in the Room, the desktop app answers from a hidden copy of the session and shows the notification Agent wake falls back to a fork, so you know to look for the answer in the Room and not in your window.

A Codex terminal that is a client of the shared Codex app server takes the wake as a queued message. A queued message cannot be taken back, so when nothing confirms that turn the desktop app does not answer from a copy. It shows Agent wake not confirmed, and you reply in the Room yourself.

When the tool has no in-session delivery, the desktop app answers from a hidden copy of the session without a notification, as before, and the Room shows the answer. This is the case for an embedded Codex terminal that is not a client of the app server, for a Claude Code session started before the desktop app installed its hook, and on Windows.

A Grok Build wake runs in a hidden copy of the session, or in a new session when the earlier one is no longer open. The desktop app turns on the ArtifactBridge connector that you added on grok.com for that process only, so that process has the same Room tools as your Grok Build window. If the connector does not give that process its Room tools, the wake stops and reports the problem. The wake tells Grok not to read stored sign-in files, but it does not remove the file and shell tools of that process.

Wake a Hermes chat

A Hermes chat that created or joined a Room can take a wake as a new turn in the same chat. The desktop app never starts a new Hermes session for the wake and never uses the one-shot Hermes mode, which skips approval prompts. A busy chat runs the wake after its current turn, and a pending approval or clarification stays pending until you answer it.

The artifactbridge-wake plugin queues the wake inside the Hermes backend (hermes serve), so Hermes Desktop needs no plugin and no open window. This needs Hermes from the first release after v0.21.5 that contains Hermes PR #121604. With an older Hermes, the plugin delivers through its Hermes Desktop part instead (the last step below).

Set it up on the computer that runs the Hermes backend of the profile. For a Hermes Desktop that connects over SSH, this is the remote computer.

1. Install ArtifactBridge Desktop on that computer and sign in, so that it watches your Rooms.
2. Run artifactbridge agent hooks install --hermes-profile NAME. It adds the capture hook to the profile’s config.yaml and the artifactbridge-wake plugin to the profile’s plugins folder. It approves and enables nothing.
3. Approve the hook: check it with hermes --profile NAME hooks list, then approve it at the first-use prompt of an interactive session or in the profile’s shell-hook allowlist. hermes serve must find artifactbridge on its path.
4. In the profile’s config.yaml, enable the plugin and let it queue messages. Add these keys to the existing plugins section, then restart the profile’s backend:

   plugins:
     enabled:
       - artifactbridge-wake
     entries:
       artifactbridge-wake:
         allow_gateway_injection: true

   Without allow_gateway_injection, the plugin refuses each wake, and the Room shows it as not delivered.
5. Only with a Hermes older than that release: in Hermes Desktop, turn on ArtifactBridge wakes in Capabilities → Plugins. For a remote backend, first copy desktop/plugin.js from the installed plugin folder to ~/.hermes/desktop-plugins/artifactbridge-wake/plugin.js on the Desktop computer.

With the plugin enabled, a Hermes chat that opens or joins a Room joins under its profile name. It also sends the display name of the profile, the type of computer (Mac, Linux, or Windows), and a session key for the chat. To show another short computer label, set ARTIFACTBRIDGE_ORIGIN_LABEL. The plugin makes the session key from the chat with a random value that stays on this computer. The chat id, the host name, and file paths are not sent. Two profiles of one person therefore appear in the Room as two agents, each named after its profile.

A wake goes to the chat that created the Room, or to the chat that joined as the participant that the request addresses. A later post or join from another chat does not change this. The plugin gives each Hermes chat its own session key. When two chats join as the same participant, for example without the plugin, the desktop app wakes neither chat. The request then goes to the fallback below, or shows as not delivered.

The wake arrives only while the chat is open in the Hermes backend. When the backend delivers and the chat is not open at that moment, the chat does not get the request. When several Hermes backends serve the same profile, only the backend that ran a turn in the chat since it started delivers the wake. Until then the wake waits, for up to 15 minutes. With the Hermes Desktop part, Hermes Desktop must also have the connection of that profile active. The desktop app holds a wake for 15 minutes, also across a restart. A question for a chat that is open but busy waits longer, for up to 2 hours, and arrives when the chat finishes its current turn. After that the request goes to the fallback below, or shows as not delivered, and you answer in the Room. The desktop app sends each wake once: when it cannot tell whether Hermes accepted a wake, it reports the wake as uncertain and does not send it again. The Hermes Desktop part supports Hermes 0.21 only, and it stays inactive when the backend delivers the wakes itself.

When the chat cannot take a wake, the desktop app runs it once in your registered Hermes command, as with dedicated routing. A wake that Hermes possibly accepted is never sent again. The wake history tells the reasons apart: Hermes found the chat not open and sent nothing to it, or the chat sent no sign that it was open. This works only after you run artifactbridge agent runtime enable hermes once with --command and --working-directory, also when the command is already saved. Without it, the wake shows as not delivered.

You can run two sessions of the same AI tool in one Room, for example one terminal that designs and one that writes. Ask each agent to join with its own session key. Each session then appears as a separate participant, and a request that you address to one of them does not start the other.

Bring another of your sessions into a Room

An agent in one Room can find your other existing sessions, for example a second terminal or Hermes chat that works on the same issue in its own Room. It finds them among your own sessions in Rooms that share a work item with this Room, or in a Room that you name.

A request goes only to a participant of the Room where it is asked. The agent cannot address a session through its participant in another Room: the server refuses that request and saves nothing. To bring the other session in, ask it to join this Room, in its own Room or in its terminal or chat. Then the agent addresses its participant in this Room. A dedicated session or the Hermes fallback that you set up can also start a new session in this Room for a request to your participant here.

Only a reply from the participant that the request names, or your own answer in the Room, answers the request. A reply from another of your sessions is part of the discussion, and the request stays open.

Requests to a session in another Room that were sent before this change keep their recorded target. They can still arrive on the earlier path. They are never sent to another session or sent again.

Keep useful outcomes in the Room and put reusable content in the Library. A result left only in a terminal conversation is not automatically shared with your team.

Wake a custom command-line agent

A command-line agent that is not one of the supported tools can also take wakes. Register it on the computer that runs ArtifactBridge Desktop, with the command that runs one turn of the agent:

artifactbridge agent runtime enable LABEL \
  --working-directory DIRECTORY \
  --command "COMMAND" \
  --prompt-stdin \
  --tray-binding

• LABEL is the runtime name that the agent joins Rooms with. A request that names this runtime as its target starts the command. The agent does not need to be in the Room first. When a request names only the runtime, and no person or participant, it starts the command only on the computers of the Room owner.
• --prompt-stdin gives the wake request to the command on its standard input and then closes the input. Without it, the request is the last argument of the command. Other programs on the computer can read the arguments of a running process, so use standard input when your command can read it.
• --tray-binding is for an agent that has no ArtifactBridge hooks. After the first start in a Room, the desktop app records that the agent works in that Room and gives it a session key to join with. Later replies in that Room, an answer or a task result, then start the agent again. Its own replies, other Room activity, and questions to you do not start it. --tray-binding requires --prompt-stdin.

Each wake starts the command again. The desktop app cannot continue an earlier conversation of a custom agent, and Send to agent does not list it. To address the agent in a Room, name its runtime: a request to its exact participant is not delivered. The automatic-wake limits in Settings → Advanced apply as for any other tool. To stop the wakes, run artifactbridge agent runtime disable LABEL.

When a request to you needs a new agent session and the Room has no bound agent session, the desktop app starts the default wake runtime if you set one with artifactbridge agent runtime default LABEL. Without a default, it starts the first enabled runtime whose command you set with --command, then the runtime of your last completed wake, then the first enabled runtime. Run artifactbridge agent runtime default --clear to remove the default. Disabling the default runtime also removes it.

For example, an OMP (Oh My Pi) setup that runs each Room turn through a sandboxed wrapper command registers the runtime omp:

artifactbridge agent runtime enable omp \
  --working-directory HARNESS_DIRECTORY \
  --command "python3 -m omp_harness room-wake --home ROOM_HOME --model MODEL --" \
  --prompt-stdin \
  --tray-binding

Replace HARNESS_DIRECTORY with the directory that contains the wrapper, ROOM_HOME with the wrapper home for Room turns, and MODEL with the model selector. The wrapper reads the request from standard input and runs one turn. It also applies its own limits for each Room and each day.

Send a runtime's wakes to one dedicated session

By default, a wake goes to the chat that is bound to the Room, for example the Hermes chat that created it. If you work in that chat, a wake interrupts your work. Dedicated routing sends every wake of one runtime on this computer to one separate session instead: the Tray starts the registered command for each wake, as a background command without a terminal. Wakes of the runtime run one at a time, in the order they arrived, across all Rooms and workspaces. A wake that cannot start within 15 minutes, or that finds 128 wakes already waiting, is not delivered, and the Room shows the reason.

For Hermes, give the command a named chat so that every wake continues the same history:

artifactbridge agent runtime enable hermes \
  --working-directory DIRECTORY \
  --command "hermes chat -c 'AB wakes' --create-if-missing --oneshot -q" \
  --wake-routing dedicated

• When a request names one of your participants, the session acts as that participant and does not join the Room again. Otherwise it joins the Room once as its own participant and keeps that participant for later wakes.
• Privacy: the named chat keeps the content of every Room it worked in, also after someone removes your access to a Room. Use it only for your own agents, and never share the named chat with another person.
• Turn it off: run the same command with --wake-routing bound. Wakes that wait for the dedicated session then end as not delivered; they are not sent to your chat.
• Hermes fallback: with --wake-routing bound and the same --command, a Hermes wake that its chat cannot take still runs here. A command that the desktop app or an earlier release saved does not count. A later change of the command without --command turns the fallback off.
• After a crash: if the Tray stops while a dedicated session runs and cannot prove later that the session ended, it starts no other wake for that runtime. The Tray log names DedicatedLaneFenced. Make sure that no process of the runtime still runs the wake, then remove the reservation entry of the runtime from dedicated-wakes.json in the ArtifactBridge state directory.

Run the Tray headless on a Linux server

Desktop is required today: a server needs the ArtifactBridge desktop app installed, because headless mode is a launch option of its artifactbridge-tray program. Sign in to your workspace on that computer first. If the Tray has no sign-in, its log names the command to run. With --headless, the Tray starts wakes for local agents and opens no window, tray icon, or notification, and it needs no display. It does not update itself; your package manager updates it. A wake that needs your approval is not started, so set automatic wakes with artifactbridge agent wake set auto --workspace WORKSPACE_ID. When agents wake each other many times in a row, the Tray stops and the wake reports consecutive_auto_limit. Your next message in the Room restarts the count, or run artifactbridge agent wake reset --workspace WORKSPACE_ID. The command saves a reset request and prints its generation, and the Tray applies it once, before its next wake. The limits do not change, and the other wake limits still apply. Replace WORKSPACE_ID with the ID of your workspace. The reset works only when the artifactbridge command and the Tray come from the same release: do not mix versions that write the wake settings, and an older version that you install again does not keep the count restarted. After you update, run the reset again if a wake still reports consecutive_auto_limit. Only one Tray can start wakes for one computer and user: a second Tray exits and names the process that owns wakes. Messages go to ~/.artifactbridge/logs/. An example systemd --user unit, in ~/.config/systemd/user/artifactbridge-tray.service:

[Unit]
Description=ArtifactBridge Tray (headless)
After=network-online.target

[Service]
ExecStart=/usr/bin/artifactbridge-tray --headless
Restart=on-failure
Environment=PATH=%h/.local/bin:%h/.bun/bin:/usr/local/bin:/usr/bin:/bin
KillMode=control-group

[Install]
WantedBy=default.target

Add the directories of the artifactbridge command and of each agent command to the PATH line. Then run systemctl --user enable --now artifactbridge-tray. To keep the service running when you are not logged in, run loginctl enable-linger.

Outside-rollout instructions: the optional per-task Space and tray prerelease instructions below describe legacy shared agents. They do not certify a pooled client or activate the pool. For the prerelease fixed-Space pool, create agents with Create agent in the browser's rail Agents view and join from the tray's This computer view with explicit open-pool, no-sandbox consent. Personal wakes and targeted questions keep their existing execution path. See computer slots and controls and pooled tasks.

Prerelease: a pooled request from a Room with a space. The tray shows the agent's fixed space and the Room's space on separate lines. Both are pinned when the task is accepted. Each line names its space only when you can open it now: Uses Space Marketing as its agent space, Uses a Space you can’t open as the room space. When you can open both and they are the same space, one line names it: Uses Space Marketing as its agent space and the room space. The last line names the sender, for example Reads with Ana Silva’s access. A request from a Room without a space shows the lines described below.

A shared tray agent with a Space

A member can attach one Space to a task for a shared agent that runs on its owner's computer (see Send a space with a task for a shared agent). Before they send, the composer tells them, for example: Research bot runs on Dana Novak's computer and reads Marketing with your access, private documents included. Results post to this Room. A task without a Space works as before.

• What the owner sees. When you open a request with a Space in the tray, it shows two lines before the consent text. The first line is Uses Space Marketing when you can open the Space now, or Uses a Space you can’t open when you cannot. The second line names the sender, for example Reads with Ana Silva’s access. The rest of the request and your decision work as before.
• Approval gives no access. Approving the request does not give you access to the Space. The instructions that your local agent receives never name the Space or give its id, also when the tray shows you its name.
• The agent reads with the sender's access. It sees what the sender can see in the Space at the moment of each read, private documents included. The Space grants no write.
• Content reaches your computer. What the agent reads is stored on your disk, in the agent's session files, and the agent can quote it in the Room. There is no sandbox. When the sender later loses access, new reads stop, but content that was already delivered cannot be recalled. There is no erasure guarantee.
• When the Space cannot be read. Every task with a Space tells the agent: If you can't read the Space, or you don't have artifactbridge_read_space_context, say in the Room that you can't load the Space and ask what to do. Don't carry on as if you had read it. The agent does not read a folder instead.

For how a cloud agent handles the same task, see Tasks that come with a Space.