# 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

```bash
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](docs/TEAM.md) 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

```bash
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

```bash
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](docs/CLI-FLOW.md). Product scope: [PRODUCT](docs/PRODUCT.md). Acceptance scenarios: [ACCEPTANCE](docs/ACCEPTANCE.md). Older scenario playbooks remain optional examples, not hardcoded workflows: [scenarios](docs/scenarios/README.md).