# GrokBoy product notes

**North star:** a local **Grok Bot–like** agent — thin CLI core, tool-using ReAct loop, optional Playwright **DOM** browser (not screenshot-first). GrokBoy is the sole main line; LazyBoy is reference only (no fork).

## Done (P0–P5)

| Phase | What |
|-------|------|
| **P0** | Streaming chat CLI (`grokboy chat`), xAI/OpenAI-compatible API |
| **P1** | Tools + ReAct (`shell`, files), sessions under `~/.grokboy/sessions/` |
| **P2** | Completion contract (`report_done` / `report_blocked`), loop guard, context truncation |
| **P3** | Optional Playwright DOM tools: navigate / snapshot / click / type / eval (fail-closed) |
| **P4** | Human browser handoff (`browser_handoff`) for login / OTP / captcha |
| **P5** | Interactive multi-turn agent REPL (`grokboy agent`) with tools + session persist |

## P5 — Interactive multi-turn agent (this slice)

Gap after P4: `chat` streams but has no tools; `run` has tools but is one-shot. P5 adds **`grokboy agent`**:

1. REPL reads a user line (ignore empty; `/exit` `/quit` leave; `/session` prints id).
2. Each turn runs the **same** ReAct loop as `run` (tools + handoff inherited).
3. Prints the verdict / assistant answer; **saves** under `~/.grokboy/sessions/` after every turn.
4. `--session <id>` resumes; omitting id auto-creates and prints the session id.
5. `chat` stays streaming no-tools; `run` stays one-shot.

### Env

- `GROKBOY_BROWSER_HEADED=1` — always launch Chromium headed (recommended for `run` / `agent` when handoff is likely).
- `GROKBOY_HANDOFF_AUTO=1` — auto-resume (tests / CI); `abort` to auto-abort.

### Non-goals (this slice)

- Multi-agent orchestration
- Desktop accessibility / native UI automation
- External connectors / SaaS integrations
- Forking LazyBoy or Codex
- Turning `chat` into a tools REPL (kept simple on purpose)

### Acceptance (summary)

See `docs/ACCEPTANCE.md` section P5.

## Roadmap hint (later)

P6+ may deepen session UX, richer browser persistence across process restarts, or more tools — still thin core, DOM-first browser.