grok-agent 0.5.0

package/README.md

@@ -0,0 +1,449 @@
+# grok-agent
+
+A coding assistant CLI powered by xAI's Grok models.
+
+`grok-agent` gives you an agentic assistant in your terminal that can chat, inspect and edit code, run shell commands, search a repo, attach files/images, use xAI server-side tools, and keep JSONL-backed session history.
+
+## Features
+
+- Exec mode: `grok-agent "fix the bug in utils.ts"`
+- Interactive REPL: `grok-agent`
+- Pipe mode: `git diff | grok-agent "review this patch"`
+- Local tools: `bash`, `read_file`, `write_file`, `edit_file`, `glob`, `grep`, `list_directory`
+- Session persistence with resume, fork, archive, rename, rollback, and compaction
+- Ephemeral mode for no-history runs
+- JSONL output mode for automation
+- xAI server-side tools: web search, X search, code execution, file search, and MCP
+- Search filters for domains, X handles, date ranges, and media understanding
+- Collection management backed by xAI's management API
+- Review mode for uncommitted diffs, branches, and commits
+- Sandbox modes and per-tool approval overrides
+- Batch API helpers and realtime client-secret creation
+- Image inputs and file attachments
+- Image generation, video generation, TTS voice listing, and streaming TTS
+- Structured JSON output with `--json-schema`
+- Token usage display, citations, approvals, hooks, and notifications
+
+## Quickstart
+
+```bash
+# Prerequisites: Node.js >= 20 and an xAI API key
+
+git clone https://github.com/baba20o/grok-agent.git
+cd grok-agent
+npm install
+npm run build
+npm link
+
+export XAI_API_KEY=your_key_here
+grok-agent doctor
+grok-agent "what does this project do?"
+```
+
+You can also place `XAI_API_KEY` in a local `.env` file. The CLI loads `.env` from:
+
+- the current directory
+- the parent directory
+- `~/.grok-agent/.env`
+
+## Usage
+
+```text
+grok-agent [options] [command] [prompt...]
+```
+
+Key options:
+
+- `-m, --model <model>`: use any specific model id
+- `--fast`, `--reasoning`, `--non-reasoning`, `--code`, `--research`: model shortcuts
+- `--max-turns <n>`: cap agent turns
+- `--cwd <dir>`: change working directory
+- `-r, --resume <id>`: resume a saved session
+- `--fork <id>`: copy a session into a new one
+- `-n, --name <name>`: assign a name to the session
+- `--ephemeral`: run without saving session state
+- `-o, --output <file>`: write final message to a file
+- `--approve`, `--deny-writes`, `--yolo`: approval policy
+- `--sandbox <mode>`: `read-only`, `workspace-write`, or `danger-full-access`
+- `--plan`: ask the model to plan before execution
+- `--json`: machine-readable JSONL events on stdout
+- `--json-schema <schema>`: require structured output
+- `--color <mode>`: set color output mode (`auto`, `always`, `never`)
+- `--web-search`, `--x-search`, `--code-execution`: enable xAI server-side tools
+- `--allow-domain`, `--exclude-domain`, `--search-images`: web search controls
+- `--x-allow`, `--x-exclude`, `--x-from`, `--x-to`, `--x-images`, `--x-videos`: X search controls
+- `--collection <id>` and `--file-search-mode <mode>`: enable file search over xAI collections
+- `--include-tool-outputs`, `--show-server-tool-usage`: expose server-side tool output and usage
+- `--mcp <urls...>`: connect remote MCP servers
+- `--mcp-allow <label=tool1,tool2>`: restrict MCP tools per server
+- `--mcp-desc <label=description>`: attach MCP server descriptions
+- `--image <paths...>`: attach images
+- `--attach <files...>`: upload files
+- `--show-reasoning`, `--show-usage`, `--show-diffs`, `--no-diffs`, `--no-citations`, `--no-tools`
+- `-v, --verbose`: output detailed tool calls
+- `--notify`: desktop notification on completion
+- `--responses-api`: force the Responses API
+- `--defer`: fire-and-forget deferred completion
+
+Full help:
+
+```bash
+grok-agent --help
+```
+
+## Commands
+
+| Command | Description |
+|---|---|
+| `models` | List models or inspect a specific model |
+| `sessions` | List, show, archive, rename, rollback, compact, delete, or clear saved sessions |
+| `review` | Run Grok in code review mode for local changes, branches, or commits |
+| `generate-image` / `imagine` | Generate images |
+| `generate-video` / `video` | Generate video |
+| `speak` / `tts` | Convert text to speech |
+| `tts-voices` | List currently available TTS voices |
+| `collections` | Manage xAI document collections and their documents |
+| `batch` | Create, inspect, cancel, and feed Batch API jobs |
+| `realtime` | Create ephemeral realtime client secrets |
+| `doctor` | Validate setup, API key, and session storage |
+| `tokenize` | Count tokens for text |
+| `config` | Show config or create a default config file |
+
+Examples:
+
+```bash
+grok-agent models ls
+grok-agent models info grok-4-1-fast-reasoning
+
+grok-agent sessions list
+grok-agent sessions show <id>
+grok-agent sessions archive <id>
+grok-agent sessions rename <id> "new name"
+grok-agent sessions rollback <id> --turns 2
+grok-agent sessions compact <id>
+grok-agent sessions delete <id>
+
+grok-agent review --base origin/main
+grok-agent review --commit HEAD~1
+
+grok-agent config --init
+grok-agent config
+```
+
+## Model Selection
+
+You can change models in three ways:
+
+1. One-off on the command line:
+
+```bash
+grok-agent -m grok-4-1-fast-reasoning "summarize this repo"
+grok-agent --code "fix the TypeScript errors"
+grok-agent --reasoning "design a migration plan"
+```
+
+2. Via environment:
+
+```bash
+export GROK_MODEL=grok-code-fast-1
+```
+
+3. Via config file:
+
+```json
+{
+  "model": "grok-code-fast-1"
+}
+```
+
+Selection precedence is:
+
+`CLI flag` > `config.json` > `GROK_MODEL` > built-in default
+
+Current built-in aliases:
+
+| Flag | Model |
+|---|---|
+| `--fast` | `grok-4-1-fast-reasoning` |
+| `--reasoning` | `grok-4.20-0309-reasoning` |
+| `--non-reasoning` | `grok-4.20-0309-non-reasoning` |
+| `--code` | `grok-code-fast-1` |
+| `--research` | `grok-4.20-multi-agent-0309` |
+
+To see what your API key can actually use:
+
+```bash
+grok-agent models ls
+```
+
+## Examples
+
+### Coding
+
+```bash
+grok-agent "fix the failing tests in src/utils.ts"
+grok-agent --code "refactor this module to use async/await"
+grok-agent --reasoning "design a caching layer for the API"
+grok-agent --plan "add a config migration for the new schema"
+```
+
+### Interactive
+
+```bash
+grok-agent
+grok-agent --ephemeral
+grok-agent -r <session-id>
+```
+
+### Research
+
+```bash
+grok-agent --research "compare React Server Components vs Astro Islands"
+grok-agent --web-search "what changed in Node.js 22"
+grok-agent --x-search "what are developers saying about Bun"
+grok-agent --web-search --allow-domain docs.x.ai --search-images "summarize the docs homepage"
+grok-agent --x-search --x-allow xai --x-from 2026-03-01 --x-to 2026-03-29 "recent Grok platform updates"
+grok-agent --collection engineering-handbook "find the deploy checklist"
+```
+
+### Images and Files
+
+```bash
+grok-agent --image screenshot.png "what is wrong with this UI?"
+grok-agent --attach spec.pdf "implement the auth flow from this spec"
+grok-agent --attach data.csv "summarize the anomalies in this dataset"
+```
+
+### Generation
+
+```bash
+grok-agent imagine "a minimalist logo for a CLI tool"
+grok-agent imagine --pro "photorealistic laptop on a desk"
+grok-agent video --duration 8 --aspect 16:9 "a futuristic terminal UI"
+grok-agent tts --voice eve "Build completed successfully."
+grok-agent tts --stream --codec mp3 --voice leo "Streaming speech sample"
+grok-agent tts-voices
+```
+
+### MCP
+
+```bash
+grok-agent --mcp https://mcp.deepwiki.com/mcp "explain this repository"
+grok-agent --mcp wiki=https://mcp.deepwiki.com/mcp --mcp custom=https://my-tools.example/mcp "research task"
+grok-agent --mcp wiki=https://mcp.deepwiki.com/mcp --mcp-allow wiki=search,read_page --mcp-desc wiki="Team wiki" "find release notes"
+```
+
+### Structured Output and JSON Mode
+
+```bash
+grok-agent --json-schema '{"type":"object","properties":{"files":{"type":"array","items":{"type":"string"}}}}' \
+  "list the source files touched by session persistence"
+
+grok-agent --json --ephemeral "say hi in one short sentence"
+```
+
+### Collections
+
+```bash
+grok-agent collections list
+grok-agent collections create "Engineering Docs"
+grok-agent collections upload col_123 handbook.pdf
+grok-agent collections search col_123 "on-call rotation policy"
+grok-agent --collection col_123 "summarize the deployment runbook"
+```
+
+Collection management requires `XAI_MANAGEMENT_API_KEY`.
+
+### Batch + Realtime
+
+```bash
+grok-agent batch list --limit 20
+grok-agent batch create nightly-evals
+grok-agent batch add-chat batch_123 "summarize this issue thread"
+grok-agent batch results batch_123 --limit 10
+grok-agent realtime secret --seconds 600
+```
+
+### Tokenization
+
+```bash
+grok-agent tokenize "fix the bug in approvals.ts"
+grok-agent tokenize -m grok-code-fast-1 "class User { constructor() {} }"
+```
+
+## Sessions
+
+Sessions are stored as JSONL files under:
+
+- `GROK_SESSION_DIR/sessions`
+- or `~/.grok-agent/sessions` by default
+
+Useful commands:
+
+```bash
+grok-agent sessions list
+grok-agent sessions list --all
+grok-agent sessions show <id>
+grok-agent -r <id> "follow-up question"
+grok-agent --fork <id> "continue on a new branch of thought"
+grok-agent sessions archive <id>
+grok-agent sessions unarchive <id>
+grok-agent sessions rename <id> "better title"
+grok-agent sessions rollback <id> --turns 1
+grok-agent sessions compact <id>
+grok-agent sessions clear
+```
+
+If you do not want any session state written, use:
+
+```bash
+grok-agent --ephemeral "one-off task"
+```
+
+## Configuration
+
+Create a starter config file:
+
+```bash
+grok-agent config --init
+```
+
+That writes `config.json` under your session dir (`GROK_SESSION_DIR` or `~/.grok-agent`).
+
+Supported config fields currently include:
+
+```json
+{
+  "model": "grok-4-1-fast-reasoning",
+  "approval_policy": "always-approve",
+  "sandbox_mode": "workspace-write",
+  "show_usage": false,
+  "show_diffs": true,
+  "show_citations": true,
+  "show_server_tool_usage": false,
+  "include_tool_outputs": false,
+  "notify": false,
+  "max_turns": 50,
+  "management_api_key": "",
+  "management_base_url": "https://management-api.x.ai/v1",
+  "mcp_servers": [
+    {
+      "label": "wiki",
+      "url": "https://mcp.deepwiki.com/mcp",
+      "description": "Team wiki",
+      "allowedTools": ["search", "read_page"]
+    }
+  ],
+  "tool_approvals": {
+    "defaultMode": "ask",
+    "tools": {
+      "bash": "allow",
+      "write_file": "deny"
+    }
+  },
+  "server_tools": [
+    {
+      "type": "web_search",
+      "filters": {
+        "allowedDomains": ["docs.x.ai"]
+      },
+      "includeSources": true
+    },
+    {
+      "type": "file_search",
+      "collectionIds": ["col_123"],
+      "retrievalMode": "hybrid",
+      "includeResults": true
+    }
+  ],
+  "hooks": {
+    "pre-tool": ["echo pre"],
+    "post-tool": ["echo post"]
+  }
+}
+```
+
+Environment variables:
+
+| Variable | Description | Default |
+|---|---|---|
+| `XAI_API_KEY` | xAI API key | required |
+| `XAI_MANAGEMENT_API_KEY` | xAI management API key for collections | unset |
+| `XAI_BASE_URL` | API base URL | `https://api.x.ai/v1` |
+| `XAI_MANAGEMENT_BASE_URL` | management API base URL | `https://management-api.x.ai/v1` |
+| `GROK_MODEL` | default model | `grok-4-1-fast-reasoning` |
+| `GROK_SESSION_DIR` | base dir for sessions and config | `~/.grok-agent` |
+| `GROK_SANDBOX_MODE` | default sandbox mode | `danger-full-access` |
+
+## Tools
+
+### Local Tools
+
+| Tool | Description |
+|---|---|
+| `bash` | Run shell commands |
+| `read_file` | Read file contents |
+| `write_file` | Create or overwrite files |
+| `edit_file` | Exact find-and-replace edits |
+| `glob` | Find files by glob |
+| `grep` | Search file contents by regex |
+| `list_directory` | List directory contents |
+
+### xAI Server-Side Tools
+
+| Tool | CLI support |
+|---|---|
+| Web Search | `--web-search`, `--allow-domain`, `--exclude-domain`, `--search-images` |
+| X Search | `--x-search`, `--x-allow`, `--x-exclude`, `--x-from`, `--x-to`, `--x-images`, `--x-videos` |
+| Code Execution | `--code-execution` |
+| File Search | `--collection <id>`, `--file-search-mode <mode>` |
+| Remote MCP | `--mcp <url>`, `--mcp-allow`, `--mcp-desc` |
+
+## Development
+
+```bash
+npm run lint
+npm run build
+npm test
+```
+
+Source layout:
+
+```text
+src/
+├── index.ts             CLI entry and subcommands
+├── agent.ts             Agent loop and interactive mode
+├── client.ts            xAI client wrapper
+├── cli-errors.ts        Shared CLI/network/session error formatting
+├── config.ts            Config and .env loading
+├── server-tools.ts      Typed server-tool normalization and serialization
+├── session.ts           JSONL session persistence
+├── json-output.ts       JSONL event output
+├── approvals.ts         Approval policy checks
+├── hooks.ts             Hook execution
+├── compaction.ts        Conversation compaction
+├── truncation.ts        Tool output truncation and token estimation
+├── system-prompt.ts     Dynamic system prompt
+├── collections-api.ts   xAI collections management helpers
+├── batch-api.ts         Batch API helpers
+├── voice-api.ts         TTS and realtime helpers
+├── project-context.ts   Optional repo context loading
+├── image.ts             Image input helpers
+├── notifications.ts     Desktop notification support
+├── usage.ts             Usage accounting
+└── tools/
+    ├── index.ts
+    ├── definitions.ts
+    ├── bash.ts
+    ├── read-file.ts
+    ├── write-file.ts
+    ├── edit-file.ts
+    ├── glob.ts
+    ├── grep.ts
+    ├── list-dir.ts
+    └── policy.ts
+```
+
+## License
+
+Apache-2.0

package/bin/grok-cli.js

@@ -0,0 +1,26 @@
+#!/usr/bin/env node
+
+// Entry point — delegates to compiled TypeScript or tsx in development
+import { pathToFileURL, fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
+import { existsSync } from "node:fs";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const distEntry = join(__dirname, "..", "dist", "index.js");
+const srcEntry = join(__dirname, "..", "src", "index.ts");
+
+if (existsSync(distEntry)) {
+  // Production: run compiled JS — use file:// URL for Windows compatibility
+  await import(pathToFileURL(distEntry).href);
+} else {
+  // Development: run via tsx
+  const { execFileSync } = await import("node:child_process");
+  try {
+    execFileSync("npx", ["tsx", srcEntry, ...process.argv.slice(2)], {
+      stdio: "inherit",
+      cwd: process.cwd(),
+    });
+  } catch (err) {
+    process.exit(err.status || 1);
+  }
+}

package/dist/agent.d.ts

@@ -0,0 +1,4 @@
+import type { GrokConfig, AgentOptions } from "./types.js";
+export declare function runAgent(config: GrokConfig, prompt: string, options: AgentOptions): Promise<string>;
+export declare function runInteractive(config: GrokConfig, options: AgentOptions): Promise<void>;
+//# sourceMappingURL=agent.d.ts.map

package/dist/agent.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent.d.ts","sourceRoot":"","sources":["../src/agent.ts"],"names":[],"mappings":"AA+CA,OAAO,KAAK,EACV,UAAU,EAGV,YAAY,EAKb,MAAM,YAAY,CAAC;AAqgBpB,wBAAsB,QAAQ,CAC5B,MAAM,EAAE,UAAU,EAClB,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,YAAY,GACpB,OAAO,CAAC,MAAM,CAAC,CA0FjB;AAED,wBAAsB,cAAc,CAAC,MAAM,EAAE,UAAU,EAAE,OAAO,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC,CAqS7F"}