gmgauthier/grokkit
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 11 Wiki Activity
v0.2.0
grokkit/docs/user-guide/agent.md
Greg Gauthier cd47686679
All checks were successful
CI / Test (pull_request) Successful in 42s
Details
CI / Lint (pull_request) Successful in 27s
Details
CI / Build (pull_request) Successful in 23s
Details
docs: refactor README and docs structure for better organization 
- Simplified README.md by moving detailed command docs, workflows, and development info to dedicated user-guide/ and developer-guide/ directories.
- Created index.md files for both guides to improve navigation.
- Extracted individual command guides (e.g., chat.md, edit.md) into user-guide/ for focused, maintainable documentation.
- Moved architecture, configuration, and troubleshooting to developer-guide/.
- Updated README links to point to the new docs structure.
2026-03-07 22:42:43 +00:00

2.7 KiB
Raw Permalink Blame History

🤖 Agent Guide

The agent command is a multi-file autonomous agent that allows you to perform complex refactorings or feature implementations across multiple files using natural language instructions.

Warning

This command is currently experimental. Always ensure you have a clean git state before running the agent.

Why use Agent?

  • Multi-file awareness: Unlike the edit command, the agent command scans your project to understand the context and identifies which files need to be changed.
  • Autonomous Planning: Grok generates a high-level plan for the entire task before proposing any code changes.
  • Interactive Execution: You review the plan first, then review and approve changes for each file individually or all at once.
  • Project-wide Refactoring: Ideal for tasks like "refactor authentication to use JWT" or "add a new field to the User struct across all layers".

Usage

Multi-file agent for complex refactoring (experimental).

grokkit agent "refactor authentication to use JWT"

Options

Flag Description
--model, -m Override the default model (e.g., grok-4)

Workflow

  1. Project Scan: The agent scans the current directory for relevant files (currently focused on .go files).
  2. Plan Generation: Grok analyzes your instruction and the file list to create a step-by-step plan.
  3. Plan Review: You review the proposed plan and decide whether to proceed.
  4. Iterative Editing:
    • For each file in the plan, Grok generates the updated content.
    • You see a diff-style preview of the proposed changes for that specific file.
    • You can choose to:
      • y: Apply changes to this file and move to the next.
      • n: Skip changes for this file and move to the next.
      • a: Apply changes to this file and all remaining files in the plan without further confirmation.
  5. Completion: Once all files are processed, the agent provides a summary of the actions taken.

Safety & Best Practices

  • Clean Git State: Always run the agent on a clean git branch. This allows you to easily git reset --hard or git restore if the AI makes undesired changes.
  • Review the Plan: Pay close attention to the initial plan. If it seems off, abort and try again with a more specific instruction.
  • Incremental Approval: For complex tasks, approve files one by one (y) rather than using the "apply all" (a) option.
  • Verify Results: After the agent finishes, run your tests (make test) and linter (make lint) to ensure the changes are correct and follow project standards.
  • Specific Instructions: Provide as much context as possible in your instruction to help the agent understand the scope of the change.