# GrokBoy

Minimal local **GrokBot-like** CLI agent. Phase **P2**: completion contract, loop guard, context truncation.

## Status

| Phase | Status |
|-------|--------|
| P0 streaming chat | done |
| P1 shell / files + ReAct | done |
| P2 completion / loop guard / truncation | done |
| P3 browser (Playwright) | later |

No Docker desktop, no Codex/LazyBoy fork.

## Setup (macOS)

```bash
export GROKBOY_API_KEY=your_key   # or XAI_API_KEY
# optional:
# export GROKBOY_BASE_URL=https://api.x.ai/v1
# export GROKBOY_MODEL=grok-4.6
# export GROKBOY_CONTEXT_CHARS=100000

cd ~/GrokBoy
cargo run -p grokboy -- chat
```

## Commands

- `grokboy chat` — interactive streaming chat (no tools)
- `grokboy run "<prompt>"` — one-shot agent with tools
- `grokboy run --session <id> "<prompt>"` — continue a saved session
- `grokboy smoke` — offline checks (no API key required)
- `grokboy help`

Tools: `shell`, `list_dir`, `read_file`, `write_file`, `report_done`, `report_blocked`.

Sessions are stored under `~/.grokboy/sessions/<id>.json`.

The agent stops on `report_done` / `report_blocked`, blocks identical tool rounds (×3), and truncates old context when over budget.

## 繁體中文

本機終端機 coding assistant。P2 已支援完成合約（`report_done` / `report_blocked`）、迴圈守衛與上下文截斷。

```bash
export GROKBOY_API_KEY=你的金鑰
cd ~/GrokBoy
cargo run -p grokboy -- smoke
cargo run -p grokboy -- run "列出目前目錄並讀 README.md"
cargo run -p grokboy -- chat
```

## Layout

```
crates/grokboy-core/   # config, model, tools, agent, session
crates/grokboy/       # CLI binary
docs/ACCEPTANCE.md
```