# Agent

Agent Mode is Invoke's primary AI assistant mode. It gives the AI full access to your project—reading files, writing code, searching your codebase, and running terminal commands—to help you build faster.

## Overview

Agent Mode is the **default mode** when you start Invoke. It's designed for everyday coding tasks.

| Attribute    | Value                             |
|--------------|-----------------------------------|
| **Icon**     | ∞ (Infinity)                      |
| **Color**    | Theme color (blue)                |
| **Best for** | Code generation, debugging, refactoring, Q&A |
| **Shortcut** | `Shift+Tab` to cycle modes        |

## What Agent Can Do

In Agent Mode, the AI has access to powerful tools to help you:

### File Operations

- **Read Files** — View any file in your project with optional line ranges
- **Write File** — Create new files or completely rewrite existing ones
- **Edit File** — Make targeted changes using find-and-replace
- **Scan Folder** — List directory contents recursively or shallow
- **File Tree** — Display your project structure

### Search & Analysis

- **Search Files** — Full-text pattern search across your codebase
- **Grep Files** — Regular expression search with context
- **Memory** — Save and retrieve project-specific notes and context

### Development

- **Terminal** — Execute shell commands (requires your approval)
- **MCP Tools** — Access external tools via Model Context Protocol
- **Web Search** — Search the internet for information
- **Subagents** — Delegate to specialized analysis agents

## How to Use Agent Mode

### Activate Agent Mode

Agent Mode is active by default. If you're in another mode, click the **Mode Selector** in the input area and choose **Agent**, or press `Shift+Tab` to cycle through modes.

### Ask your question or describe your task

Type naturally in the chat input. Be specific about what you need:

```
Help me refactor the authentication logic in @src/auth/login.ts
```

```
Find all places where we handle API errors and show me the patterns used
```

```
Create a new utility function that validates email addresses
```

### Review AI actions

As the AI works, you'll see each tool it uses:

- **File reads** show the content retrieved
- **Searches** display matching results with context
- **Code changes** appear as diffs you can review
- **Terminal commands** require your approval before running

### Approve or apply changes

- Click **Apply** to accept code changes
- Click **Run** to approve terminal commands
- Click **Skip** to reject an action

## Terminal Command Approval

For security, Agent Mode requires your approval before running terminal commands.

When the AI wants to run a command, you'll see:

- The **command text** it wants to execute
- **Skip** button — Reject this command
- **Run** button — Execute the command
- **Run & Allowlist** — Run and auto-approve this command in the future

Always review terminal commands before approving. Check the full command text (hover for details if truncated).

### Allowlisting Commands

For commands you trust and use frequently (like `npm test` or `git status`), use **Run & Allowlist**. These commands will run automatically in the future without prompting.

## Visual Indicators

While the AI is working, you'll see:

| Indicator         | Meaning                     |
|-------------------|-----------------------------|
| Spinning loader    | Tool is executing           |
| Green checkmark    | Tool completed successfully  |
| Red alert          | Tool encountered an error    |
| Expandable card    | Click to see full tool input/output |

Each tool call displays:

- Tool name and icon
- Input parameters (what the AI requested)
- Results or output (when complete)
- Timestamp

## Best Practices

### Be Specific

Instead of vague requests, provide context:

Less effective|More effective
---|---
```
Fix my code
```
```
Fix the null pointer exception in @src/utils/parser.ts
where we access user.profile without checking if user exists
```

### Use File Mentions

Type `@` to mention specific files or folders. This gives the AI direct context:

Review @src/components/Button.tsx for accessibility issues

Search for API calls in @src/services/

### Enable Extended Thinking

For complex analysis tasks, toggle **Extended Thinking** in the input area. The AI will take more time but produce more thorough results.

## When to Use Agent Mode

### Code Generation

Writing new features, components, or utilities

### Debugging

Finding and fixing bugs with AI assistance

### Refactoring

Improving code structure and patterns

### Code Review

Getting feedback on your implementations

### Learning

Understanding unfamiliar codebases or concepts

### Automation

Running build scripts, tests, and deployments