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.