// 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

Open the Room in the browser.
Select Send to agent.
Choose a destination from the available groups below.
Allow the browser to open ArtifactBridge if prompted.
Read the opened agent session and confirm its workspace and task before continuing.

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. For a terminal session, check the CLI installation in desktop Settings. The tray shows launch errors in a dialog, even when notifications are disabled. You can also open the tool yourself and paste the Room prompt.

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

After opening the Room in your agent

Read this Room and its attached specification. Inspect the repository I have opened and identify the likely cause of the reported problem. Do not edit files or run database migrations. Post your findings, supporting file paths, and proposed next steps in the Room. Ask me before making changes.

Resume a saved session

Resume saved session lists supported sessions for your own agents in the Room. 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.

If the saved session is unavailable, the desktop handoff can start a fresh session in the selected tool instead. Read the status so you know whether the previous conversation was recovered. The Room record provides shared context, but it is not a copy of every private message in the original AI conversation.

Start a new terminal session

Use Start new with Codex CLI or Start new with Claude Code CLI. This also lets you bring your first agent into a Room. The tool starts with the Room context rather than a recovered transcript. Ask it to read the Room’s context, open questions, and recent events before acting.

Open a desktop AI app

Where supported, the menu offers ChatGPT, Open in Claude Code, and Open in Claude Cowork. ChatGPT opens with the Room prompt ready to review on macOS, Windows, and Linux. No Codex CLI is required. Connect ArtifactBridge in ChatGPT, then send the prompt. If the prompt is missing, copy it from the handoff dialog and paste it into ChatGPT. Claude Code opens the local workspace and asks you to confirm the folder. Cowork opens with the prompt only; choose a folder inside Cowork if needed. These actions do not restore a terminal transcript. The handoff dialog keeps the prompt available if a folder confirmation clears it. On Linux, install ChatGPT with its app-link handler to use this action. Claude Desktop options remain hidden on Linux.

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.

After pasting document context

Read this document and its linked sources. Propose a revision that makes the delivery dates consistent. Explain each changed date.

Copy folder context

Open the project folder and choose Copy context.
Choose Current conversation for a one-time task.
Choose Claude project for text to add to that project’s instructions.
Choose Codex project for a section to add to the project’s AGENTS.md file.
Copy 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.

Install ArtifactBridge Desktop on that computer and sign in, so that it watches your Rooms.
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.
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.
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.
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.

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. Ask each Hermes chat to join with its own session key: when two chats join as the same participant, the desktop app wakes neither and shows the request 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 request shows as not delivered at once, and you answer in the Room. 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. After that the request 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.

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.

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.