GrokBoy

A local, general-purpose GrokBot-like CLI agent. It observes the environment, chooses tools, adapts to results, and verifies its work. Uses your existing xAI/OpenAI-compatible model configuration; no separate search API key.

For action tasks the agent briefly explains its approach, then starts. Multi-stage tasks get a short live plan. You can add instructions while it works, answer a question, or interrupt and resume. Simple questions remain simple answers.

Start

export GROKBOY_API_KEY=your_key  # or XAI_API_KEY
cargo run -p grokboy -- agent
# One-shot:
cargo run -p grokboy -- run "整理目前目錄的資料，產生報告並讀回驗證"
# Resume:
cargo run -p grokboy -- agent --session <id>
cargo run -p grokboy -- run --session <id> "繼續"

While running, enter additional instructions to steer the next step. Ctrl-C or /stop stops the turn and saves its state. In the REPL, /plan shows the current plan, /session shows its ID, and /exit or /quit exits when idle. During work /exit and /quit stop the current turn first. At an explicit question, new text answers that question. Already queued idle inputs remain separate tasks.

Progress, plans and questions go to stderr; final answers go to stdout. grokboy chat remains streaming chat without tools. grokboy help lists commands and settings.

Persistent agents and background work

Run grokboy serve in one terminal, then create identities with grokboy agents create <name> and open separate chats with grokboy agent --name <name>. Agents learn private memories and public expertise from their conversations. They can delegate to an existing agent or create a temporary worker while you keep chatting.

In named-agent mode, ordinary text is new chat. Use /tasks and /task <id> say|stop|resume to manage background work. Closing a chat leaves the service and its tasks running. Agent identity and task ownership are separate: one agent can help another without losing its own conversation.

See team setup and behavior for commands, budgets, privacy boundaries and recovery. GROKBOY_DATA_DIR defaults to ~/.grokboy/team; existing single-session commands keep their original behavior.

Tools

Capability	Tools
Progress and planning	report_progress, update_plan
Human interaction	request_user_input, request_user_confirm, browser_handoff
Completion	report_done, report_blocked
Commands	exec_command, write_stdin, legacy shell
Files	list_dir, search_files, read_file, edit_file, write_file
Browser observation	browser_navigate, browser_snapshot, browser_read_page, browser_tabs
Browser actions	browser_click, browser_type, browser_press, browser_select, browser_scroll, browser_wait
Browser file exchange	browser_upload, browser_download
Browser fallback	browser_eval

Long commands return a session ID and incremental output; write_stdin polls, sends input, closes stdin or terminates the command. One foreground command at a time, piped I/O, default ten-minute deadline. Legacy shell retains its 30-second limit. Full command output is saved under .grokboy-output/; large tool results are also stored there with a readable preview and path.

read_file accepts a zero-based line offset and line limit; search_files searches names or literal content; edit_file requires one unique exact match. File tools and browser file exchange check workspace paths and symlinks. Shell is still a local-user command runner, not an OS sandbox.

Optional browser

cd tools/playwright
npm install
npx playwright install chromium
cd ../..
export GROKBOY_BROWSER_HEADED=1  # visible browser, convenient for login handoff
cargo run -p grokboy -- agent

Playwright operates through DOM selectors/roles and can read page text, select tabs/popups and target an iframe. Search uses the ordinary browser. Missing browser dependencies produce an install hint. Legacy sessions have their own profiles; named-agent tasks reuse their owner’s persistent profile with exclusive browser access. Cookies and local storage survive restarts; the agent re-observes the page before continuing.

For login, OTP or captcha, browser_handoff opens the visible browser and waits for you. For irreversible public actions, the agent follows the existing explicit-approval rule; plans themselves do not require approval.

Settings

Environment variable	Default / meaning
GROKBOY_API_KEY	Falls back to XAI_API_KEY, then OPENAI_API_KEY
GROKBOY_BASE_URL	https://api.x.ai/v1; fallback OPENAI_BASE_URL
GROKBOY_MODEL	grok-4.6
GROKBOY_MAX_ROUNDS_TOTAL	48 model requests per user turn, including control tools
GROKBOY_MAX_ROUNDS	12; local progress interval, no extra model calls
GROKBOY_CONTEXT_CHARS	100000 approximate UTF-8 bytes; legacy name
GROKBOY_SESSIONS_DIR	~/.grokboy/sessions
GROKBOY_PROGRESS	0 silences progress, but not questions
GROKBOY_BROWSER_HEADED	1 launches visible Chromium
GROKBOY_CONFIRM_AUTO	Test-only approval/denial override; falls back to GROKBOY_HANDOFF_AUTO
GROKBOY_HANDOFF_AUTO	Test-only handoff override: 1 resume, abort deny

Session stop reasons: answer, done, blocked, budget_exhausted, failed, cancelled. One-shot exits 0 for answer/done, 1 for blocked/budget/failed, 130 for cancellation. The REPL remains usable after any turn outcome. done is a model declaration supported by reported evidence, not an independent proof of arbitrary task correctness.

Validation

cargo test --workspace
cargo clippy --workspace --all-targets -- -D warnings
cargo build -p grokboy
python3 tests/cli_flow.py
python3 tests/runtime_flow.py       # includes a real 31-second command + local Chromium
python3 tests/browser_flow.py       # headless Chromium, local fixture only
python3 tests/team_flow.py          # daemon, two CLI clients, mock API + Chromium
cargo run -p grokboy -- smoke
# Opt-in: uses your existing paid model configuration, max 12 requests:
python3 tests/live_cli.py
python3 tests/live_team.py          # opt-in team workflow, root task ceiling 16

Design and Codex references: CLI flow. Product scope: PRODUCT. Acceptance scenarios: ACCEPTANCE. Older scenario playbooks remain optional examples, not hardcoded workflows: scenarios.