# 🤖 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.