grok-acp — unofficial Grok Build ACP launcher for Xcode & other clients

Unofficial. Not affiliated with xAI, Grok, or Apple. See DISCLAIMER.md.

Small, user-agnostic wrapper that launches Grok Build as an Agent Client Protocol (ACP) stdio server.

IDE clients such as Xcode 27 spawn a subprocess and speak JSON-RPC on stdin/stdout. This script:

1. Finds the grok binary for the current user
2. Starts grok agent --always-approve --no-leader stdio
3. Keeps stdout clean (required for ACP)
4. Writes diagnostics to a log file (stderr only)

---

Prerequisites

• Grok Build CLI installed and authenticated (grok works in a terminal)
• Xcode 27+ for custom ACP agents under Settings → Intelligence → Agents
  (Xcode 26 and earlier do not expose this UI)

---

Install

# From this directory
chmod +x grok-acp

# Option A — user local bin (any account)
mkdir -p ~/.local/bin
cp grok-acp ~/.local/bin/grok-acp

# Option B — next to Grok’s own bin (if you use ~/.grok)
mkdir -p ~/.grok/bin
cp grok-acp ~/.grok/bin/grok-acp

Resolve the absolute path you will paste into Xcode:

# macOS
python3 -c "import os; print(os.path.realpath(os.path.expanduser('~/.local/bin/grok-acp')))"
# or
readlink -f ~/.local/bin/grok-acp 2>/dev/null || realpath ~/.local/bin/grok-acp

---

Xcode 27 setup

1. Open Xcode 27 (or newer).
2. Xcode → Settings → Intelligence
3. Under Agents, click Add an Agent (wording may vary slightly by beta).
4. Configure:

Field	Value
Name	Grok
Command	absolute path to grok-acp (example: /Users/you/.local/bin/grok-acp)
Arguments	(leave empty)

5. Enable the agent and select Grok in the coding assistant / agent UI.

Why a wrapper (not raw grok agent stdio)?

Problem without a wrapper	What the wrapper does
Xcode’s PATH often lacks ~/.grok/bin	Resolves grok from common install locations
Args glued or mis-split (agentstdio, single string "agent stdio")	No args needed — correct argv is built in-script
Permission prompts hang JSON-RPC	Passes --always-approve by default
Startup noise on stdout breaks framing	Logs go to a file; stdout is ACP-only

Always-approve

On by default. Tool runs do not wait for interactive approval (needed so Xcode does not sit on a request ID forever).

To disable (not recommended for Xcode):

export GROK_ACP_NO_ALWAYS_APPROVE=1

Or set that in a thin outer wrapper if your environment injects env vars into GUI apps.

Deny rules / hooks in Grok config still apply; always-approve does not mean “ignore all policy.”

---

Other ACP clients

Any client that can spawn:

command: /path/to/grok-acp
args:    []

and speak newline-delimited JSON-RPC (ACP stdio) can use the same binary.

Examples of the underlying command (what the wrapper runs):

grok agent --always-approve --no-leader stdio

Manual test without the wrapper:

printf '%s\n' '{"jsonrpc":"2.0","id":"1","method":"initialize","params":{"protocolVersion":1,"clientCapabilities":{},"clientInfo":{"name":"test","version":"1"}}}' \
  | grok agent --always-approve --no-leader stdio \
  | head -1

You should see a single JSON line with "id":"1" and a "result" object.

---

Sanity check after install

printf '%s\n' '{"jsonrpc":"2.0","id":"1","method":"initialize","params":{"protocolVersion":1,"clientCapabilities":{},"clientInfo":{"name":"test","version":"1"}}}' \
  | grok-acp \
  | head -1

Then open Xcode, select the Grok agent, send a short prompt.

If Xcode shows:

JSON-RPC request with ID … failed to produce a response

check:

1. Command is the absolute path to grok-acp (not a relative path).
2. Arguments are empty.
3. Logs after a failed attempt:

# default when ~/.grok exists:
tail -50 ~/.grok/logs/xcode-acp.log
tail -50 ~/.grok/logs/xcode-acp-debug.log

• Log does not grow → Xcode is not launching the binary (path / args).
• Log grows with spawn lines but no protocol progress → see debug log / auth (grok login in Terminal first).

---

Environment variables

Variable	Meaning
GROK_ACP_BIN	Absolute path to grok if auto-discovery fails
GROK_ACP_LOG_DIR	Override log directory
GROK_ACP_NO_ALWAYS_APPROVE=1	Disable always-approve
GROK_ACP_EXTRA_ARGS	Extra args after agent (e.g. --model grok-4.5)

---

OpenCode (for comparison)

OpenCode’s ACP entrypoint is different:

# Command:  /opt/homebrew/bin/opencode   (or `which opencode`)
# Arguments: acp

Do not pass acp to Grok; Grok uses agent … stdio.

---

License

MIT — free to use, copy, modify, and share.

This repository contains only this wrapper script and documentation. It does not include Grok Build, Xcode, or any proprietary vendor software. Each machine still needs its own licensed/authenticated Grok CLI.

Disclaimer

Unofficial community project; trademarks belong to their owners. Full text: DISCLAIMER.md.