@obversa/engine-grok-cli runs one engine attempt through the grok
command-line tool, in a fresh process. Use it to put an xAI model in a seat.
The plugin runs Grok the way you run it: with your own home folder, your
Grok login and your Grok settings. Grok has no clean mode, so it
doesn’t run clean by default the way the other command-line engines do. Grok
loads the repository’s instruction files under its own rules, such as
whether you trust the project. The plugin adds only what the step needs,
through Grok’s own flags: the tools and permission rules the step declares,
read-only enforcement where the step only reads, subagents only when the
step asks for them, and structured output.
Install
@obversa/obversa.
Requirements
- Grok CLI 1.0.44, the version the plugin is tested with, at an absolute
path you pass as
executable. - Grok signed in with
grok login, or a login file you pass asauthFile.
Identity
You name the provider and model family in theidentity option, such as
{ provider: 'xai', modelFamily: 'grok-4' }, and the plugin records them as
given. Before its first attempt it runs grok --version and refuses to run
if the version differs from version.
Quickstart
grok(model, { executable }) is the seat helper a workflow() role takes,
as claude(model) is for Claude. grok('grok-4', { executable: '/usr/local/bin/grok' })
is a seat on grok-4 that reads with read_file, grep and list_dir.
The seat serves the provider xai and the model family read from the model
name, grok here.
new GrokCliEngine(options) is the same engine without the seat identity.
Construct it with the executable, its version and the identity it serves,
then run one request:
examples/safe-node-attempt.ts (excerpt)
Options
environment and authFile
The child gets your own environment. environment sets more values on top
of it. Names that start with GROK_ are refused.
authFile signs Grok in with another login file instead of yours. The
plugin copies that file into a temporary Grok home folder for each attempt,
because Grok’s sandbox reads no login outside its home folder. Grok then
reads no settings from your own Grok home folder.
Tools and permission rules
A step names Grok’s own tools, such asread_file and search_replace, and
the permission rules that allow them, such as Read and Edit. A workflow
role gives the seat’s tools as both. A Grok tool named as a rule is read as
the rule for that tool: read_file and list_dir as Read, grep as
Grep, search_replace as Edit, run_terminal_command as Bash,
web_fetch as WebFetch and use_tool as MCPTool.
clean
Grok has no clean mode, so clean: true throws an error that says why.
Grok’s strict sandbox reads no login outside its own home folder, so a run
can’t leave your Grok home out and keep your own login.
Its row in the engines table: runs on your
setup, no clean mode, read-only held on your setup.
Your MCP servers and write steps
Grok starts your own MCP servers in every run, from its own settings and from~/.claude.json. A step that declares no MCP tool keeps their tools
from the model. A write step runs in Grok’s workspace sandbox, which also
lets the model change files outside the repository: in Grok’s own home
folder, ~/.grok, and in temporary folders.
The rest
Errors
- A version that differs from
versionrefuses the run before the first attempt. - A relative, empty or malformed
executableis refused. EngineErrorkinds as the API lists them.
API
grok(model, options): aTeamSeatfor a workflow role. Quickstart.GrokCliEngine: the engine class.GrokCliEngineOptions,GrokCliIdentity,GrokSeat,GrokSeatOptions: its types.buildGrokArgs: the argument builder, exported for tests.
Next steps
- Safe node attempts: the whole example, with the OpenCode engine beside it and the output.
- API: the engine contract this plugin implements.