Spawnosaurus is a Grok-powered agent CLI that can execute Execode plans or run direct Grok tasks.
npm install spawnosaurus-cliSpawnosaurus is a Grok-powered agent command-line tool that can either execute tasks directly via Grok or run plan-driven workloads materialised by ExeCode.io in the Vercel Sandbox. Think of it as the command-line twin of ExeCode.io’s browser experience: fast local setup, automated plan execution, and structured results that are safe to pipe into other tooling.
- Interactive REPL mode – Start a continuous session with conversation history, multi-line paste support, and command history navigation. Perfect for iterative development.
- Skip manual orchestration – feed Spawnosaurus an ExeCode.io plan and it runs every task (or a single task) with the correct dependencies.
- Bring-your-own prompt – run one-off Grok prompts from the terminal and capture structured JSON output.
- Safety-first tooling – Spawnosaurus limits Grok to a vetted toolbelt (read, write, patch, bash, etc.) so file edits are predictable and auditable.
- Fits into CI/CD – deterministic JSON output, exit codes, and summary metadata make it easy to plug into automated pipelines.
1. Install dependencies
``bash`
cd spawnosaurus-cli
npm install
npm run build
`
2. Authenticate (required for Grok calls)
bash`
echo "XAI_API_KEY=sk-your-grok-key" >> .env
# or export XAI_API_KEY=sk-your-grok-key
`
3. Run your first command
bash`
# Interactive REPL mode – start a continuous session
spawnosaurus repl
# or, using the shorter alias
spawno repl
# Direct mode – ask Grok to do something immediately
spawnosaurus "Draft a migration plan for converting Jest tests to Vitest" --output json
# or, using the shorter alias
spawno "Draft a migration plan for converting Jest tests to Vitest" --output json
`
4. Run an ExeCode.io plan
bash`
spawnosaurus hatch \
--plan .agent/plan.json \
--output json
# alias works here too
spawno hatch \
--plan .agent/plan.json \
--output json
Prefer a global install? npm install -g spawnosaurus-cli drops the spawnosaurus binary (and spawno alias) onto your PATH.
- 🎯 Interactive REPL Mode – Continuous session with conversation history, multi-line paste, and command history navigation
- ⚡️ Zero-config TypeScript CLI build with tsuphatch
- 🤖 Grok 4 Fast Reasoning integration via Vercel AI SDK
- 🧠 Plan-driven subcommand that iterates every task in an ExeCode.io plan
- 🛠️ Rich LLM toolbelt (bash, read, write, edit, patch, list, glob, grep, todo, webfetch)
- 📝 JSON or text output formats for easy downstream tooling
- Node.js v18.18 or newer
- REPL mode (repl): Grok API key (XAI_API_KEY with optional legacy alias GROK_API_KEY)hatch
- Plan mode (): plan + task JSON files written by ExeCode.io (usually .agent/plan.json and .agent/tasks/) + Grok API keyXAI_API_KEY
- Direct mode: Grok API key ( with optional legacy alias GROK_API_KEY)
1. REPL mode (repl) – Start an interactive session that maintains conversation history across commands. Perfect for iterative development where you need context from previous interactions. Supports multi-line paste, command history, and special session management commands.
2. Plan mode (hatch) – ExeCode.io produces a plan (.agent/plan.json) and per-task artifacts. Spawnosaurus reads the plan, replays each task in order, and exposes a curated toolbelt to Grok so that the run stays within the sandboxed workspace.submit_task_result
3. Direct mode – Skip the plan and run a single Grok-powered task inline. Great for one-off fixes, docs, or research queries.
4. Structured output – Every task must call with a schema-validated payload, ensuring Spawnosaurus always emits machine-readable JSON.
5. Streaming feedback – Task logs, stdout/stderr, and progress summaries are streamed to the console for fast feedback loops.
6. Agent-like behavior – Spawnosaurus uses an iterative Observe→Think→Act→Repeat workflow, continues until task completion (not fixed step limits), and self-corrects when errors occur. See SPAWNOSAURUS_AGENT_IMPROVEMENTS.md for details.
Spawnosaurus supports two execution modes for task execution:
Direct Mode uses Grok to directly call a set of predefined tools (bash, read, write, etc.) for efficient, multi-step operations within a single LLM turn. This is the preferred default mode for most tasks.
When to use:
- Simple file operations (create, read, edit)
- Running shell commands
- Installing packages
- Quick code generation
- Most day-to-day development tasks
Example:
`bash`
spawnosaurus "Create a hello.txt file with content 'Hello World'"
OpenCode Mode uses the OpenCode CLI for complex scaffolding tasks. Spawnosaurus spawns the OpenCode CLI as a subprocess, which handles its own LLM orchestration and tool execution.
When to use:
- Scaffolding full-stack applications
- Multi-file project setup
- Complex project bootstrapping
- Tasks requiring extensive code generation
Example:
`bash`
spawnosaurus --opencode "scaffold a full-stack React app with Express backend"
Requirements:
- OpenCode CLI must be installed: npm install -g @opencode-ai/cli
- Provider credentials (OpenRouter or XAI API key)
Mode Selection:
- Explicit: Use --opencode flag to force OpenCode mode
- Auto-detection: Spawnosaurus automatically detects complex tasks (scaffold, multi-file, full-stack, project setup, bootstrap) and uses OpenCode mode
- Default: Simple tasks use Direct mode automatically
Provider Configuration:
Spawnosaurus supports two providers for OpenCode mode:
1. OpenRouter (Preferred): Uses model x-ai/grok-4.1-fast via OpenRouter`
bash`
spawnosaurus --opencode --openrouter-api-key sk-... "scaffold a React app"
# or via environment variable
export OPENROUTER_API_KEY=sk-...
spawnosaurus --opencode "scaffold a React app"
2. XAI Direct: Uses model grok-4.1-fast directly from XAI`
bash`
spawnosaurus --opencode --xai-api-key xai-... "scaffold a React app"
# or via environment variable
export XAI_API_KEY=xai-...
spawnosaurus --opencode "scaffold a React app"
CLI Flags:
- --opencode: Use OpenCode mode (for complex tasks)--openrouter-api-key
- : OpenRouter API key (for OpenCode mode via OpenRouter)--openrouter-model
- : OpenRouter model (defaults to x-ai/grok-4.1-fast)--xai-api-key
- : XAI API key (alternative to OpenRouter, uses model grok-4.1-fast)
Environment Variables:
- OPENROUTER_API_KEY: OpenRouter API key (fallback if flag not provided)OPENROUTER_MODEL
- : OpenRouter model (defaults to x-ai/grok-4.1-fast if not provided)XAI_API_KEY
- : XAI API key (alternative to OpenRouter, uses model grok-4.1-fast)
Provider Selection Priority:
1. OpenRouter (if OPENROUTER_API_KEY or --openrouter-api-key provided)XAI_API_KEY
2. XAI direct (if or --xai-api-key provided, and no OpenRouter)x-ai/grok-4.1-fast
3. Default: OpenRouter with if OPENROUTER_API_KEY available
`bash`From the project root
cd spawnosaurus-cli
npm install
npm run build
Global install (optional):
`bash`
npm install -g spawnosaurus-cli
Uninstall:
`bash`
npm uninstall # local
npm uninstall -g spawnosaurus-cli # global
Verify the installed version:
`bash`
spawnosaurus --versionor
spawno --version
| Mode | When to use it | Required input | Typical command |
|------|----------------|----------------|-----------------|
| REPL (repl) | Interactive session for continuous command execution with conversation history | Grok API key | spawnosaurus repl (alias: spawno) |hatch
| Plan () | Replay an ExeCode.io plan, honour task dependencies, produce CI-friendly JSON | .agent/plan.json (+ task files) | spawnosaurus hatch --plan .agent/plan.json --output json (alias: spawno) |spawnosaurus "Explain this stack trace" --output json
| Direct | Fire off a one-liner Grok task from your terminal | Prompt text + Grok API key | (alias: spawno) |
ExeCode.io writes the plan and task artifacts into the sandbox before invoking the CLI. By default spawnosaurus hatch executes every task sequentially and stops on failure:
`bash`
spawnosaurus hatch \
--plan .agent/plan.json \
--output json
Narrow the run to a single task:
`bash`
spawnosaurus hatch \
--plan .agent/plan.json \
--task spawnosaurus-smoke-task \
--output json
Key flags:
- --plan : Path to the agent plan JSON file (required)--task
- : Execute a single task (omit to run the full plan)--all
- : Explicitly run every task (default behaviour)--task-file
- : Override the task JSON location-k, --api-key
- : Grok API key (defaults to XAI_API_KEY, falls back to GROK_API_KEY)-m, --model
- : Model identifier (grok-4-1-fast-reasoning default)-o, --output
- : text or json (defaults to text)--opencode
- : Use OpenCode mode for complex scaffolding tasks--openrouter-api-key
- : OpenRouter API key (for OpenCode mode via OpenRouter)--openrouter-model
- : OpenRouter model (defaults to x-ai/grok-4.1-fast)--xai-api-key
- : XAI API key (alternative to OpenRouter for OpenCode mode)
Spawnosaurus now executes every plan task through a tool-enabled Grok workflow. Available tools:
| Tool | Purpose |
|------------|----------------------------------------------------------------|
| bash | Execute shell commands within the workspace |read
| | Read file contents |write
| | Create or overwrite files |edit
| | Apply exact string replacements in an existing file |patch
| | Apply unified diff patches |list
| | List directory contents |glob
| | Match files using glob patterns |grep
| | Search files with regular expressions (ripgrep fallback) |todowrite
| /todoread | Persist task-level todos in .agent/spawnosaurus-todos.json |webfetch
| | Retrieve remote web content |
Each task responds with structured JSON (status, summary, details, nextSteps) and the CLI--output json
prints an aggregated summary (or emits full JSON when is selected).
As of version 0.4.0, Spawnosaurus uses tool-based structured output to ensure reliable JSON responses.
Instead of prompting Grok to return freeform JSON (which can include extra text), the CLI now requires
Grok to call a submit_task_result tool with a predefined Zod schema:
`typescript`
{
status: 'success' | 'failed' | 'blocked',
summary: string, // Brief description of outcome
details: string[], // List of key actions taken
nextSteps: string[], // Optional follow-up recommendations
stdout?: string, // Optional captured output
stderr?: string // Optional error output
}
This guarantees parseable output for every task and makes Spawnosaurus output safe for automation and
CI/CD pipelines. All tool invocations are also logged and can be displayed in the ExeCode.io UI.
> ℹ️ ExeCode.io's sandbox installs the CLI directly from npm (spawnosaurus-cli). Keep the published package up to date so new sandboxes always receive the latest binary.
`bashHuman-readable summary (default)
spawnosaurus "Draft a migration plan for converting Jest tests to Vitest"
This mode allows quick prompting without plan artifacts. Use
--output json only when you need deterministic JSON for downstream automation; otherwise enjoy the default text summary. Provide a Grok API key in both cases.$3
The REPL mode provides an interactive terminal experience where you can continuously execute commands without restarting the CLI. It maintains conversation history across commands, supports multi-line paste, and offers command history navigation.
`bash
Start interactive REPL
spawnosaurus replWith custom model
spawnosaurus repl --model grok-4With JSON output
spawnosaurus repl --output json
`Key Features:
- Conversation History: Maintains context across multiple commands, allowing for follow-up questions and iterative development
- Multi-line Paste: Automatically detects and handles pasted multi-line code blocks
- Command History: Navigate previous commands with up/down arrow keys (persisted to
~/.spawnosaurus-history)
- Special Commands: Built-in commands for managing the sessionSpecial Commands:
-
.exit, .quit, exit, quit - Exit the REPL
- .clear - Clear conversation history
- .history - Show conversation history
- .help - Show available commands
- .editor - Open external editor for multi-line input (uses $EDITOR env var)
- .model [model] - Show or change the AI model
- .output [format] - Show or change output format (text/json)Usage Tips:
- Multi-line Paste: Simply paste multi-line code directly - it will be detected automatically
- Cancel Operations: Press
Ctrl+C to cancel a running command
- Exit: Use Ctrl+D, .exit, or type exit to quit
- Editor Mode: Use .editor to open your preferred editor ($EDITOR) for composing longer prompts
- Conversation Context: The REPL maintains conversation history, so you can reference previous responses in follow-up questionsExample Session:
`bash
$ spawnosaurus repl
🚀 Spawnosaurus Interactive REPL
Type .help for available commands or start typing your promptspawno> Create a simple hello world function in Python
✅ Task completed successfully
...
spawno> Now add error handling to that function
✅ Task completed successfully
...
spawno> .history
Conversation History:
1. 👤 user: Create a simple hello world function in Python
2. 🤖 assistant: Task completed successfully...
3. 👤 user: Now add error handling to that function
4. 🤖 assistant: Task completed successfully...
spawno> .exit
👋 Goodbye!
`Command History:
Command history is automatically saved to
~/.spawnosaurus-history and loaded when you start a new REPL session. Use arrow keys to navigate through previous commands.Troubleshooting
-
Error: XAI_API_KEY not set – Create a .env file or export the variable in your shell (export XAI_API_KEY=...). Global installs should add it to .zshrc/.bashrc.
- Plan file not found – Confirm you are in the workspace root where .agent/plan.json lives, or pass an absolute path to --plan.
- Task JSON missing – Use --task-file when task artifacts are stored outside the default .agent/tasks/ directory.
- npm install dependency errors – Spawnosaurus continues even if dependency installation fails; inspect the error log in the task summary and rerun after fixing package issues.
- Unstructured output – Upgrade to Spawnosaurus v0.4.0+ to guarantee tool-enforced JSON responses.
- REPL not starting – Ensure you have a valid XAI_API_KEY set. The REPL requires an API key to initialize the session.
- Command history not working – Command history is saved to ~/.spawnosaurus-history. Ensure you have write permissions to your home directory.Environment Variables
| Variable | Purpose |
|----------|---------|
|
XAI_API_KEY | Primary Grok credential (required for REPL, direct mode, and plan execution). Also used for OpenCode mode when OpenRouter is not available. |
| GROK_API_KEY | Optional legacy alias for XAI_API_KEY |
| OPENROUTER_API_KEY | OpenRouter API key for OpenCode mode (preferred, uses model x-ai/grok-4.1-fast) |
| OPENROUTER_MODEL | OpenRouter model for OpenCode mode (defaults to x-ai/grok-4.1-fast) |
| EDITOR | External editor for REPL .editor command (defaults to nano if not set) |$3
Local development (within the
spawnosaurus-cli folder):`bash
cd spawnosaurus-cli
echo "XAI_API_KEY=sk-your-grok-key" >> .env
npm run build
`Alternatively export it for the current shell session:
`bash
cd spawnosaurus-cli
export XAI_API_KEY=sk-your-grok-key
spawnosaurus --version
`Global installs: add the key to your shell profile (e.g.
~/.zshrc, ~/.bashrc) so spawnosaurus can pick it up anywhere:`bash
echo 'export XAI_API_KEY=sk-your-grok-key' >> ~/.zshrc
source ~/.zshrc
spawnosaurus --version
`You can always override the environment by passing
--api-key to any command:`bash
spawnosaurus hatch --plan .agent/plan.json --api-key sk-your-grok-key
`Publishing Updates
After making changes, publish a new version to npm so the sandbox can install it:
`bash
npm run build
npm publish
``Update the version in the ExeCode.io repository when you release a new build.
MIT © ExeCode.io