Relay for CLI Agents

Relay for CLI Agents (Relay) sends file paths and code selections from the editor to a CLI coding agent running in a dedicated terminal. It is the VS Code version of Relay. The JetBrains version lives in jetbrains/.

Source code, issues and releases: github.com/sulsira/relay. This extension is in the vscode/ folder.

What it does

Illustrative animation, not a screen recording.

1. You press a shortcut in the editor.
2. Relay picks the target terminal: the active Relay terminal, else the last Relay terminal you used, else a new one for the default agent.
3. Relay starts that agent's command in the terminal, once.
4. Relay pastes a reference to your file or selection into the agent prompt, formatted for that agent. It does not press Enter.

How it works, step by step

Illustrations drawn for this README, not screen captures. Key labels use macOS names: ctrl, option.

1. Open Relay

Press Ctrl+Alt+T. A terminal tab named Relay:claude opens and runs the agent's command.

2. Send the file path

Press Ctrl+Alt+P with a file open. Relay pastes @src/foo.ts into the agent prompt. It does not press Enter, so you can keep typing.

3. Send a selection

Select lines, then press Ctrl+Alt+Enter. Claude gets the line range as @src/foo.ts#L3-L6.

4. Add a second agent

Press the key you bound to relay.openAgent with "args": "cursor" in keybindings.json (for example Ctrl+Alt+2). A second terminal opens, and the status bar shows Relay: cursor. Each agent has its own tab. The same selection now goes out in that agent's format: @src/foo.ts:3-6 for Cursor.

5. Sends follow the active tab

Switch back to the Claude tab. The next file path lands there, in Claude's format. Relay uses the tab you last used, not a fixed default.

Commands and shortcuts

• All commands are in the editor right-click menu under Relay.
• Change keys in Keyboard Shortcuts (Cmd/Ctrl+K Cmd/Ctrl+S).
• The status bar item Relay: <agent> shows who receives the next send. Click it to open an agent.

Per-agent shortcuts

Relay: Open Agent... accepts an agent name as an argument, so each agent can have its own key. Add this to keybindings.json (Preferences: Open Keyboard Shortcuts (JSON)):

[
  { "key": "ctrl+alt+1", "command": "relay.openAgent", "args": "claude" },
  { "key": "ctrl+alt+2", "command": "relay.openAgent", "args": "cursor" }
]

• The shortcut opens or focuses that agent's own terminal, creating it on first use.
• Later sends go to whichever Relay terminal is active.

Where sends go

• Several agents can run side by side, one terminal each, named Relay:<name>.
• Idle terminals keep running and receive nothing.

Settings

Open Settings and search for relay, or edit settings.json.

Agent profile fields

"relay.agents": [
  { "name": "claude", "command": "claude" },
  { "name": "cursor", "command": "agent" },
  { "name": "aider", "command": "aider --model sonnet", "referenceMode": "add" },
  { "name": "review", "command": "claude --model opus", "referenceMode": "at-mention" }
]

Formats for file src/foo.ts and lines 10 to 20:

Behavior details

• Relay tracks its terminals by object, not by title. A shell that renames the terminal does not create a duplicate.
• Each terminal remembers the agent it started. Edited referenceMode applies on the next send, but an edited command only applies to new terminals.
• Relay terminals restored from a previous window session are closed on startup. Their agent process is gone, so the next send opens a fresh terminal.
• Relay waits up to 3 seconds for shell integration before typing the agent command. Without shell integration it types the command after that wait.
• Paths are relative to the workspace folder. Files outside it use the absolute path.

Differences from the JetBrains plugin

Install manually (VS Code)

Use this to install without the Marketplace.

Get the file

Option A: use the prebuilt file in this repository (fastest)

1. The installable file is committed at releases/relay-vscode-1.5.2.vsix. Its checksum is in releases/SHA256SUMS.
2. Download it. Either of these works once the repository is public:
   1. Open the file on GitHub and click Download raw file.
   2. Or run curl -L -o relay-vscode-1.5.2.vsix https://github.com/sulsira/relay/raw/main/vscode/releases/relay-vscode-1.5.2.vsix.
3. If you cloned the repository, the file is already at vscode/releases/relay-vscode-1.5.2.vsix.
4. Optional check: run shasum -a 256 relay-vscode-1.5.2.vsix and compare it with releases/SHA256SUMS.

Option B: build it yourself

1. Run npm install in the vscode/ folder.
2. Run npm run package. It writes relay-vscode-<version>.vsix in vscode/.

Install it

Pick one way.

From the command line

1. Run code --install-extension relay-vscode-1.5.2.vsix. Use the full path if the file is not in the current folder.
2. Reload VS Code: Command Palette (Cmd+Shift+P), then Developer: Reload Window.

From the VS Code window

1. Open the Extensions view (Cmd+Shift+X).
2. Click the ... menu at the top of the view.
3. Choose Install from VSIX....
4. Select relay-vscode-1.5.2.vsix.
5. Click Reload if VS Code asks.

If the code command is not found: Command Palette, then Shell Command: Install 'code' command in PATH.

Check it

1. The status bar, bottom left, shows Relay: <agent>.
2. Command Palette, then type Relay. Five commands appear.
3. Open a file and press Ctrl+Alt+T. A terminal named Relay:<agent> opens.

Update or remove

If it fails

Develop and test

Requires Node.js 20 or newer and VS Code 1.93 or newer.

1. Open the vscode/ folder of the repository in VS Code.
2. Press F5 (Run Extension). A second VS Code window opens with Relay loaded.
3. Install a built package with code --install-extension relay-vscode-<version>.vsix. See Install manually (VS Code) above.

Code layout

Automated tests

• npm test runs 10 tests for format.ts. They cover agent detection and every reference format.
• npm run test:integration opens a VS Code window and checks, in order:
  1. The extension activates and registers 5 commands.
  2. relay.open creates Relay:a1.
  3. relay.openAgent creates and focuses Relay:a2, and reopening it creates no duplicate.
  4. File and selection sends reuse the active Relay terminal and open none.
  5. Closing Relay:a2 makes sends fall back to Relay:a1 without a new terminal.
  6. A stray Relay:ghost terminal is closed.
  7. The text that reaches the agent is exact, for four agents: zed (@path), claude (@path#L3-L5), cursor (@path:3-5), and adder in add mode (/add @path).
• The scenario uses a throwaway user-data directory and does not touch your VS Code settings.
• Step 7 uses cat > file as the agent, sends Ctrl+D twice to flush and close it, and compares the file with the expected text. A trailing newline would fail the check, so it also proves Relay does not press Enter.
• It runs against your login shell, so it assumes a POSIX-style shell where cat > file works.

Manual test checklist

Run in the F5 window with a workspace open and two agents, for example claude and cursor.

Known risks

• Closing restored terminals is tested only with a terminal created after activation. A real window reload with persistent terminals is covered by manual step 8 only.
• sendText(text, false) pastes without bracketed paste. References are single-line, so this is safe, but a multi-line payload would be typed line by line.
• Shell integration events need VS Code 1.93 or newer.

Publishing a release file

1. Raise version in package.json and add an entry to CHANGELOG.md.
2. Run npm test and npm run package.
3. Move the new file into releases/ and delete the old one: mv relay-vscode-<version>.vsix releases/.
4. Refresh the checksum: cd releases && shasum -a 256 relay-vscode-<version>.vsix > SHA256SUMS.
5. Update the file name in Install manually (VS Code).
6. Publish to the Marketplace with npx vsce publish.

Source code and support