feat(harnesses): add Grok CLI harness with broker MCP injection

Expose `grok` in @agent-relay/harnesses for PTY spawn workflows, register
Grok in the CLI registry, and configure Relaycast MCP via `grok mcp add`
so spawned agents can message over Relay. Auto-inject `--always-approve`
for unattended broker spawns.

Author: willwashburn

CHANGELOG.md

@@ -9,6 +9,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 
+- `@agent-relay/harnesses` adds a `grok` PTY harness for the Grok CLI, with broker MCP injection via `grok mcp add` so spawned agents can use Relaycast tools.
 - `@agent-relay/harnesses` is now published to npm, so SDK consumers can install the prebuilt PTY harnesses and harness-authoring helpers.
 - `agent-relay drive` and `agent-relay passthrough` add adaptive predictive echo so typing stays responsive when driving a high-latency or remote agent, and stays invisible on fast local links.
 - `@agent-relay/harness-driver` exports a reusable `PredictiveEchoEngine` so other attach UIs (CLI, Electron, browser) can share one predictive-echo implementation.

crates/broker/src/snippets.rs

@@ -687,7 +687,7 @@ pub fn ensure_cursor_mcp_config(
     Ok(changed)
 }
 
-/// - `cli`: CLI tool name (e.g. "claude", "codex", "gemini", "droid", "opencode", "cursor")
+/// - `cli`: CLI tool name (e.g. "claude", "codex", "gemini", "droid", "grok", "opencode", "cursor")
 /// - `agent_name`: the name of the agent being spawned
 /// - `api_key`: optional relay API key (empty or `None` means omit)
 /// - `base_url`: optional relay base URL (empty or `None` means omit)
@@ -765,6 +765,7 @@ pub async fn configure_agent_relay_mcp_with_result(
     let is_gemini = cli_lower == "gemini";
     let is_droid = cli_lower == "droid";
     let is_opencode = cli_lower == "opencode";
+    let is_grok = cli_lower == "grok";
     let is_cursor = cli_lower == "cursor" || cli_lower == "cursor-agent" || cli_lower == "agent"; // "agent" is cursor-agent's binary name
 
     let api_key = api_key.map(str::trim).filter(|s| !s.is_empty());
@@ -920,6 +921,17 @@ pub async fn configure_agent_relay_mcp_with_result(
             None,
         )
         .await?;
+    } else if is_grok {
+        configure_grok_mcp(
+            cli,
+            api_key,
+            base_url,
+            Some(agent_name),
+            agent_token,
+            workspaces_json,
+            default_workspace,
+        )
+        .await?;
     } else if is_opencode && !existing_args.iter().any(|a| a == "--agent") {
         ensure_opencode_config_with_result(
             cwd,
@@ -1110,6 +1122,138 @@ fn gemini_droid_mcp_add_args_with_result(
     args
 }
 
+fn grok_mcp_add_args(
+    api_key: Option<&str>,
+    base_url: Option<&str>,
+    agent_name: Option<&str>,
+    agent_token: Option<&str>,
+    workspaces_json: Option<&str>,
+    default_workspace: Option<&str>,
+) -> Vec<String> {
+    let mut args = vec!["mcp".to_string(), "add".to_string()];
+    if let Some(key) = api_key {
+        args.push("--env".to_string());
+        args.push(format!("RELAY_API_KEY={key}"));
+    }
+    if let Some(url) = base_url {
+        args.push("--env".to_string());
+        args.push(format!("RELAY_BASE_URL={url}"));
+    }
+    if let Some(name) = agent_name.map(str::trim).filter(|s| !s.is_empty()) {
+        args.push("--env".to_string());
+        args.push(format!("RELAY_AGENT_NAME={name}"));
+        args.push("--env".to_string());
+        args.push("RELAY_AGENT_TYPE=agent".to_string());
+        args.push("--env".to_string());
+        args.push("RELAY_STRICT_AGENT_NAME=1".to_string());
+    }
+    if let Some(token) = agent_token.map(str::trim).filter(|s| !s.is_empty()) {
+        args.push("--env".to_string());
+        args.push(format!("RELAY_AGENT_TOKEN={token}"));
+        args.push("--env".to_string());
+        args.push("RELAY_SKIP_BOOTSTRAP=1".to_string());
+    }
+    if let Some(wj) = workspaces_json.map(str::trim).filter(|s| !s.is_empty()) {
+        args.push("--env".to_string());
+        args.push(format!("RELAY_WORKSPACES_JSON={wj}"));
+    }
+    if let Some(dw) = default_workspace.map(str::trim).filter(|s| !s.is_empty()) {
+        args.push("--env".to_string());
+        args.push(format!("RELAY_DEFAULT_WORKSPACE={dw}"));
+    }
+    args.push(AGENT_RELAY_MCP_SERVER.to_string());
+    let mcp_command = agent_relay_mcp_command();
+    args.push("--command".to_string());
+    args.push(mcp_command.command);
+    args.push("--args".to_string());
+    args.extend(mcp_command.args);
+    args
+}
+
+fn grok_manual_mcp_add_cmd(cli: &str) -> String {
+    let mcp_command = agent_relay_mcp_command();
+    let mut rendered_parts = vec![mcp_command.command];
+    rendered_parts.extend(mcp_command.args);
+    let rendered_mcp_command = rendered_parts.join(" ");
+    format!(
+        "{cli} mcp add --env RELAY_API_KEY=<key> --env RELAY_BASE_URL=<url> {AGENT_RELAY_MCP_SERVER} --command {rendered_mcp_command}"
+    )
+}
+
+#[allow(clippy::too_many_arguments)]
+async fn configure_grok_mcp(
+    cli: &str,
+    api_key: Option<&str>,
+    base_url: Option<&str>,
+    agent_name: Option<&str>,
+    agent_token: Option<&str>,
+    workspaces_json: Option<&str>,
+    default_workspace: Option<&str>,
+) -> Result<()> {
+    let exe = shlex::split(cli)
+        .and_then(|parts| parts.first().cloned())
+        .unwrap_or_else(|| cli.trim().to_string());
+    let manual_cmd = grok_manual_mcp_add_cmd(&exe);
+
+    for server_name in [AGENT_RELAY_MCP_SERVER, LEGACY_RELAYCAST_SERVER] {
+        let _ = std::process::Command::new(&exe)
+            .args(["mcp", "remove", server_name])
+            .stdin(Stdio::null())
+            .stdout(Stdio::null())
+            .stderr(Stdio::null())
+            .spawn()
+            .and_then(|mut c| c.wait());
+    }
+
+    let mut mcp_cmd = Command::new(&exe);
+    mcp_cmd.args(grok_mcp_add_args(
+        api_key,
+        base_url,
+        agent_name,
+        agent_token,
+        workspaces_json,
+        default_workspace,
+    ));
+    mcp_cmd
+        .stdin(Stdio::null())
+        .stdout(Stdio::null())
+        .stderr(Stdio::piped());
+
+    match mcp_cmd.spawn() {
+        Ok(mut child) => match tokio::time::timeout(Duration::from_secs(15), child.wait()).await {
+            Ok(Ok(status)) if !status.success() => {
+                anyhow::bail!(
+                    "failed to configure Agent Relay MCP for {cli}: `{cli} mcp add` exited with code {:?}. \
+                     Please configure the Agent Relay MCP server manually:\n  {manual_cmd}",
+                    status.code()
+                );
+            }
+            Ok(Err(error)) => {
+                anyhow::bail!(
+                    "failed to configure Agent Relay MCP for {cli}: {error}. \
+                     Please configure the Agent Relay MCP server manually:\n  {manual_cmd}"
+                );
+            }
+            Err(_) => {
+                let _ = child.kill().await;
+                anyhow::bail!(
+                    "failed to configure Agent Relay MCP for {cli}: `{cli} mcp add` timed out after 15s. \
+                     Please configure the Agent Relay MCP server manually:\n  {manual_cmd}"
+                );
+            }
+            _ => {}
+        },
+        Err(error) => {
+            anyhow::bail!(
+                "failed to configure Agent Relay MCP for {cli}: {error}. \
+                 Please configure the Agent Relay MCP server manually:\n  {manual_cmd}"
+            );
+        }
+    }
+
+    Ok(())
+}
+
 #[allow(clippy::too_many_arguments)]
 async fn configure_gemini_droid_mcp(
     cli: &str,
@@ -1584,6 +1728,32 @@ mod tests {
         assert_eq!(args[0], "--mcp-config");
     }
 
+    #[test]
+    fn grok_mcp_add_args_use_command_and_args_flags() {
+        let args = super::grok_mcp_add_args(
+            Some("rk_live_xyz"),
+            Some("https://api.relaycast.dev"),
+            Some("GrokWorker"),
+            Some("tok_grok_123"),
+            None,
+            None,
+        );
+
+        assert!(args.starts_with(&["mcp".to_string(), "add".to_string()]));
+        assert!(args.contains(&"--env".to_string()));
+        assert!(args.contains(&"RELAY_API_KEY=rk_live_xyz".to_string()));
+        assert!(args.contains(&"RELAY_AGENT_NAME=GrokWorker".to_string()));
+        assert!(args.contains(&"RELAY_AGENT_TOKEN=tok_grok_123".to_string()));
+        let server_idx = args
+            .iter()
+            .position(|arg| arg == "agent-relay")
+            .expect("agent-relay arg");
+        assert_eq!(args[server_idx + 1], "--command");
+        assert_eq!(args[server_idx + 2], "npx");
+        assert_eq!(args[server_idx + 3], "--args");
+        assert_eq!(args[server_idx + 4], "-y");
+    }
+
     #[test]
     fn droid_mcp_add_args_include_option_separator() {
         let args = super::gemini_droid_mcp_add_args(

crates/broker/src/worker.rs

@@ -280,6 +280,7 @@ impl WorkerRegistry {
                 let is_claude = cli_lower == "claude" || cli_lower.starts_with("claude:");
                 let is_codex = cli_lower == "codex";
                 let is_gemini = cli_lower == "gemini";
+                let is_grok = cli_lower == "grok";
                 if let Some(model) = apply_codex_model_arg_fallback(
                     &resolved_cli,
                     &cli_lower,
@@ -356,6 +357,10 @@ impl WorkerRegistry {
                     Some("--dangerously-bypass-approvals-and-sandbox")
                 } else if is_gemini && !effective_args.iter().any(|a| a == "--yolo" || a == "-y") {
                     Some("--yolo")
+                } else if is_grok
+                    && !effective_args.iter().any(|a| a == "--always-approve")
+                {
+                    Some("--always-approve")
                 } else {
                     None
                 };
@@ -481,6 +486,7 @@ impl WorkerRegistry {
                     let is_claude = cli_lower == "claude" || cli_lower.starts_with("claude:");
                     let is_codex = cli_lower == "codex";
                     let is_gemini = cli_lower == "gemini";
+                    let is_grok = cli_lower == "grok";
                     if let Some(model) = apply_codex_model_arg_fallback(
                         &resolved_cli,
                         &cli_lower,
@@ -559,6 +565,10 @@ impl WorkerRegistry {
                         && !effective_args.iter().any(|a| a == "--yolo" || a == "-y")
                     {
                         Some("--yolo")
+                    } else if is_grok
+                        && !effective_args.iter().any(|a| a == "--always-approve")
+                    {
+                        Some("--always-approve")
                     } else {
                         None
                     };

packages/cli/src/cli/telemetry/orchestrator-harness.test.ts

@@ -18,6 +18,7 @@ describe('orchestrator harness detection', () => {
   it('maps common process command names to harness identifiers', () => {
     expect(inferHarnessFromCommand('/usr/local/bin/claude')).toBe('claude-code');
     expect(inferHarnessFromCommand('/opt/homebrew/bin/codex')).toBe('codex');
+    expect(inferHarnessFromCommand('/Users/will/.grok/bin/grok')).toBe('grok');
     expect(inferHarnessFromCommand('/Applications/Cursor.app/Contents/MacOS/Cursor')).toBe('cursor');
     expect(inferHarnessFromCommand('/usr/local/bin/gemini-cli')).toBe('gemini-cli');
     expect(inferHarnessFromCommand(String.raw`C:\Users\will\AppData\Roaming\npm\gemini.cmd`)).toBe(

packages/cli/src/cli/telemetry/orchestrator-harness.ts

@@ -47,6 +47,7 @@ export function inferHarnessFromCommand(command: string | undefined): string | u
   if (base === 'opencode' || lower.includes('opencode')) return 'opencode';
   if (base === 'goose' || lower.includes('goose')) return 'goose';
   if (base === 'droid' || lower.includes('droid')) return 'droid';
+  if (base === 'grok' || lower.includes('/grok')) return 'grok';
   if (base === 'amp' || normalized.includes('/amp')) return 'amp';
   if (lower.includes('copilot')) return 'github-copilot';
   if (base === 'zed' || lower.includes('zed')) return 'zed';

packages/cloud/src/permissions.ts

@@ -14,6 +14,7 @@ export type AgentCli =
   | 'gemini'
   | 'aider'
   | 'goose'
+  | 'grok'
   | 'opencode'
   | 'droid'
   | 'cursor'

packages/config/src/cli-registry.generated.ts

@@ -24,6 +24,8 @@ export const CLIVersions = {
   DROID: '0.1.0',
   /** OpenCode v1.2.24 */
   OPENCODE: '1.2.24',
+  /** Grok v0.1.0 */
+  GROK: '0.1.0',
   /** Aider v0.72.1 */
   AIDER: '0.72.1',
   /** Goose v1.0.16 */
@@ -40,6 +42,7 @@ export const CLIs = {
   CURSOR: 'cursor',
   DROID: 'droid',
   OPENCODE: 'opencode',
+  GROK: 'grok',
   AIDER: 'aider',
   GOOSE: 'goose',
 } as const;
@@ -420,6 +423,18 @@ export const OpencodeModels = {
 
 export type OpencodeModel = (typeof OpencodeModels)[keyof typeof OpencodeModels];
 
+/**
+ * Grok model identifiers.
+ */
+export const GrokModels = {
+  /** Grok Build (default) */
+  GROK_BUILD: 'grok-build',
+  /** Grok Composer 2.5 Fast */
+  GROK_COMPOSER_2_5_FAST: 'grok-composer-2.5-fast',
+} as const;
+
+export type GrokModel = (typeof GrokModels)[keyof typeof GrokModels];
+
 /** Reasoning effort levels supported by model providers. */
 export const ReasoningEfforts = {
   LOW: 'low',
@@ -637,6 +652,14 @@ export const OPENCODE_MODEL_OPTIONS: ModelOption[] = [
   { value: 'openai/o4-mini-deep-research', label: 'O4 Mini Deep Research' },
 ];
 
+/**
+ * Grok model options for UI dropdowns.
+ */
+export const GROK_MODEL_OPTIONS: ModelOption[] = [
+  { value: 'grok-build', label: 'Grok Build' },
+  { value: 'grok-composer-2.5-fast', label: 'Grok Composer 2.5 Fast' },
+];
+
 /**
  * Claude Code model metadata keyed by model id.
  */
@@ -836,6 +859,14 @@ export const OPENCODE_MODEL_METADATA: Record<OpencodeModel, ModelOption> = {
   'openai/o4-mini-deep-research': { value: 'openai/o4-mini-deep-research', label: 'O4 Mini Deep Research' },
 };
 
+/**
+ * Grok model metadata keyed by model id.
+ */
+export const GROK_MODEL_METADATA: Record<GrokModel, ModelOption> = {
+  'grok-build': { value: 'grok-build', label: 'Grok Build' },
+  'grok-composer-2.5-fast': { value: 'grok-composer-2.5-fast', label: 'Grok Composer 2.5 Fast' },
+};
+
 /**
  * All models grouped by CLI tool.
  *
@@ -854,6 +885,7 @@ export const Models = {
   Cursor: CursorModels,
   Droid: DroidModels,
   Opencode: OpencodeModels,
+  Grok: GrokModels,
 } as const;
 
 /**
@@ -875,6 +907,7 @@ export const ModelOptions = {
   Cursor: CURSOR_MODEL_OPTIONS,
   Droid: DROID_MODEL_OPTIONS,
   Opencode: OPENCODE_MODEL_OPTIONS,
+  Grok: GROK_MODEL_OPTIONS,
 } as const;
 
 /**
@@ -887,6 +920,7 @@ export const ModelMetadata = {
   Cursor: CURSOR_MODEL_METADATA,
   Droid: DROID_MODEL_METADATA,
   Opencode: OPENCODE_MODEL_METADATA,
+  Grok: GROK_MODEL_METADATA,
 } as const;
 
 const MODEL_METADATA_BY_CLI: Record<CLI, Record<string, ModelOption>> = {
@@ -896,6 +930,7 @@ const MODEL_METADATA_BY_CLI: Record<CLI, Record<string, ModelOption>> = {
   cursor: CURSOR_MODEL_METADATA,
   droid: DROID_MODEL_METADATA,
   opencode: OPENCODE_MODEL_METADATA,
+  grok: GROK_MODEL_METADATA,
   aider: {},
   goose: {},
 };
@@ -1001,6 +1036,13 @@ export const CLIRegistry = {
     install: 'npm install -g opencode-ai',
     npmLink: 'https://www.npmjs.com/package/opencode-ai',
   },
+  grok: {
+    name: 'Grok',
+    package: 'grok',
+    version: '0.1.0',
+    install: 'Install from x.ai (Grok CLI)',
+    npmLink: undefined,
+  },
   aider: {
     name: 'Aider',
     package: 'aider-chat',
@@ -1027,4 +1069,5 @@ export const DefaultModels = {
   cursor: 'composer-2-fast',
   droid: 'opus-4.6-fast',
   opencode: 'openai/gpt-5.2',
+  grok: 'grok-build',
 } as const;