Agentic vs Legacy Modes

​

Mode Overview

​

Configuring Modes

require('avante').setup({
  ---@type "agentic" | "legacy"
  mode = "agentic",  -- Default mode
  
  -- ... other configuration
})

​

Agentic Mode Deep Dive

​

When to Use Agentic Mode

• Complex refactoring: Multi-file changes with automatic file reading and editing
• Feature implementation: Building complete features that span multiple files
• Code exploration: AI can autonomously search and analyze your codebase
• Debugging: AI can read error logs, check diagnostics, and propose fixes
• Rapid prototyping: Quick iterations with autonomous file creation and modification

​

How Agentic Mode Works

1. Planning: AI analyzes your request and plans necessary actions
2. Tool execution: AI calls tools like view, str_replace, bash, etc.
3. Iteration: AI can chain multiple tool calls to complete complex tasks
4. Completion: AI signals completion with attempt_completion tool

-- Example: Available tools in agentic mode
tools = {
  "view",              -- Read file contents
  "str_replace",       -- Edit files with string replacement
  "create",            -- Create new files
  "insert",            -- Insert code at specific lines
  "bash",              -- Execute shell commands
  "grep",              -- Search for patterns
  "glob",              -- Find files by pattern
  "get_diagnostics",   -- Get LSP diagnostics
  "attempt_completion", -- Signal task completion
  -- ... and more
}

​

Tool Permissions

{
  behaviour = {
    auto_approve_tool_permissions = true,  -- Default
  },
}

{
  behaviour = {
    auto_approve_tool_permissions = false,
  },
}

{
  behaviour = {
    auto_approve_tool_permissions = {"bash", "str_replace"},
  },
}

​

Fast Apply Mode

{
  behaviour = {
    enable_fastapply = true,  -- Enable Fast Apply
  },
  providers = {
    morph = {
      model = "morph-v3-large",  -- Specialized apply model
    },
  },
}

• Code changes apply at 2500-4500+ tokens/second
• 96-98% accuracy with specialized apply models
• Seamless workflow without noticeable delays

​

Legacy Mode Deep Dive

​

When to Use Legacy Mode

• Code review: When you want to carefully examine each suggestion
• Learning: Understanding AI’s reasoning before applying changes
• Simple edits: Quick, focused changes that don’t require autonomy
• Sensitive code: When working on critical systems requiring manual approval
• Explanations: Getting detailed code explanations without automatic changes

​

How Legacy Mode Works

1. Ask: You ask a question or request changes
2. Response: AI provides suggestions in the chat sidebar
3. Review: You review the suggested code in the diff view
4. Apply: You manually apply changes using keybindings

-- Key bindings for legacy mode
-- In sidebar:
-- A - Apply all suggestions
-- a - Apply suggestion at cursor
-- co - Choose ours (keep current code)
-- ct - Choose theirs (apply suggested code)

​

Diff Application

• Visual diff: Side-by-side comparison of current vs suggested code
• Conflict markers: Git-style conflict markers for manual resolution
• Selective application: Choose specific changes to apply

{
  behaviour = {
    auto_apply_diff_after_generation = false,  -- Default in legacy
  },
  diff = {
    autojump = true,
    override_timeoutlen = 500,
  },
}

​

Comparing the Modes

User Request → AI Planning → Tool Execution → More Tools → Completion
                  ↓              ↓               ↓            ↓
               Analysis    Read/Edit Files   Validation   Done

User Request → AI Response → User Reviews → User Applies
                  ↓               ↓              ↓
              Suggestion    Diff View      Manual Apply

-- You: "Refactor the authentication module to use JWT"

-- AI autonomously:
-- 1. Reads auth.lua to understand current implementation
-- 2. Creates jwt_handler.lua with new JWT logic
-- 3. Edits auth.lua to use new JWT handler
-- 4. Updates config.lua to include JWT settings
-- 5. Runs tests to verify changes
-- 6. Reports completion

-- You: "Refactor this function to use async/await"

-- AI responds with:
-- "Here's the refactored version using async/await:"
-- [Shows code diff]

-- You:
-- - Review the diff
-- - Press 'A' to apply all changes
-- - Or manually select specific changes

​

Mode-Specific Tools

​

Agentic Mode Only

-- Tools enabled only in agentic mode:
- str_replace    -- String-based file editing
- create         -- Create new files
- insert         -- Insert code at lines
- write_to_file  -- Write entire files
- undo_edit      -- Undo previous edits
- edit_file      -- Fast Apply editing (if enabled)

​

Available in Both Modes

-- Tools available in all modes:
- view           -- Read file contents
- bash           -- Execute commands (with permissions)
- grep           -- Search patterns
- glob           -- Find files
- get_diagnostics -- LSP diagnostics

​

Switching Modes

-- Runtime mode switching
require('avante.config').override({
  mode = "legacy",  -- or "agentic"
})

​

Best Practices

​

For Agentic Mode

1. Start with auto-approval off: Learn what tools do before auto-approving
2. Use with version control: Always have uncommitted work backed up
3. Review tool logs: Check what the AI actually did
4. Set appropriate permissions: Balance speed with control
5. Use prompt logging: Enable prompt_logger.enabled = true for debugging

​

For Legacy Mode

1. Provide explicit context: Add relevant files manually with @file
2. Review diffs carefully: Check all changes before applying
3. Use conflict markers: Take advantage of Git-style conflict resolution
4. Apply incrementally: Test changes one at a time for safer iterations
5. Leverage chat history: Build up context over multiple exchanges

​

Next Steps