From 4ff65e81374832f0b8d41ce3789ec723bd1ad2e1 Mon Sep 17 00:00:00 2001
From: Gregory Gauthier <gregory.gauthier@perspectum.com>
Date: Wed, 4 Mar 2026 14:31:05 +0000
Subject: [PATCH] docs(chat): add documentation for interactive agent mode

- Introduce `--agent` flag for `grokkit chat` as the new primary way to work with Grok on code
- Describe features: tool calling, safety previews, confirmation, persistent sessions
- Note deprecation of old `grokkit agent` command in v0.3.0
- Mention use of fast non-reasoning model for reliability
---
 README.md | 17 +++++++++++++++++
 1 file changed, 17 insertions(+)

diff --git a/README.md b/README.md
index 23998b1..037c0c3 100644
--- a/README.md
+++ b/README.md
@@ -72,6 +72,23 @@ grokkit chat --debug            # Enable debug logging
 - History is saved automatically between sessions
 - Use `--debug` to see API request timing
 
+### 🧠 `grokkit chat --agent`
+
+**Interactive Agent Mode** — the new primary way to work with Grok on code.
+
+Grok can now call tools directly (`edit`, `scaffold`, `testgen`, `lint`, `commit`) while maintaining full conversation history and safety previews.
+
+```bash
+grokkit chat --agent
+```
+- Uses the fast non-reasoning model for tool reliability
+- Every tool action shows a preview and requires explicit confirmation (y/n)
+- Persistent session — you can iterate, reject changes, or give follow-up instructions
+- Normal grokkit chat (without --agent) remains unchanged (full reasoning model for thoughtful conversation)
+
+**Note**: The old `grokkit agent` command is deprecated and will be removed in v0.3.0. Please migrate to chat --agent.
+
+
 ### ✏️ `grokkit edit FILE "instruction"`
 AI-powered file editing with preview.