Greg Gauthier
cd47686679
- 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.
50 lines
2.7 KiB
Markdown
50 lines
2.7 KiB
Markdown
# 🤖 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).
|
|
|
|
```bash
|
|
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.
|