> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/yetone/avante.nvim/llms.txt
> Use this file to discover all available pages before exploring further.

# Lua API

> Complete Lua API reference for Avante.nvim

Avante.nvim provides a comprehensive Lua API for programmatic control and integration.

## Module: `avante`

Main module accessible via `require('avante')`.

### setup(opts)

Initialize Avante.nvim with configuration options.

**Parameters:**

* `opts` (table|nil) - Configuration options (see [Configuration Schema](/api/config-schema))

**Example:**

```lua theme={null}
require('avante').setup({
  provider = "claude",
  behaviour = {
    auto_suggestions = true,
    auto_set_keymaps = true,
  },
})
```

**Source:** lua/avante/init.lua:489-572

***

### get(current)

Get the current sidebar, selection, and suggestion instances for the active tab.

**Parameters:**

* `current` (boolean|nil) - If `false`, doesn't update the global current state (default: `true`)

**Returns:**

* `sidebar` (avante.Sidebar) - Current sidebar instance
* `selection` (avante.Selection) - Current selection instance
* `suggestion` (avante.Suggestion) - Current suggestion instance

**Example:**

```lua theme={null}
local sidebar, selection, suggestion = require('avante').get()
if sidebar then
  print("Sidebar is open:", sidebar:is_open())
end
```

**Source:** lua/avante/init.lua:378-390

***

### toggle()

Toggle the Avante sidebar visibility.

**Returns:**

* `boolean` - `true` if sidebar is now open, `false` if closed

**Example:**

```lua theme={null}
require('avante').toggle()
```

**Source:** lua/avante/init.lua:417-430

***

### toggle\_sidebar(opts)

Toggle sidebar with options.

**Parameters:**

* `opts` (AskOptions|nil) - Options for sidebar behavior

**Example:**

```lua theme={null}
require('avante').toggle_sidebar({
  ask = true,
  win = { position = "right" },
})
```

**Source:** lua/avante/init.lua:417-430

***

### is\_sidebar\_open()

Check if the sidebar is currently open.

**Returns:**

* `boolean` - `true` if sidebar is open

**Example:**

```lua theme={null}
if require('avante').is_sidebar_open() then
  print("Sidebar is visible")
end
```

**Source:** lua/avante/init.lua:432-436

***

### open\_sidebar(opts)

Open the Avante sidebar.

**Parameters:**

* `opts` (AskOptions|nil) - Options for opening

**Example:**

```lua theme={null}
require('avante').open_sidebar({
  ask = true,
  question = "How can I optimize this?",
})
```

**Source:** lua/avante/init.lua:439-446

***

### close\_sidebar()

Close the Avante sidebar.

**Example:**

```lua theme={null}
require('avante').close_sidebar()
```

**Source:** lua/avante/init.lua:448-452

***

### toggle.debug()

Toggle debug mode on/off.

**Example:**

```lua theme={null}
require('avante').toggle.debug()
```

**Source:** lua/avante/init.lua:454-458

***

### toggle.selection()

Toggle selection mode on/off.

**Example:**

```lua theme={null}
require('avante').toggle.selection()
```

**Source:** lua/avante/init.lua:460-464

***

### toggle.suggestion()

Toggle auto-suggestions on/off.

**Example:**

```lua theme={null}
require('avante').toggle.suggestion()
```

**Source:** lua/avante/init.lua:466-479

***

### register\_acp\_client(client\_id, client)

Register an ACP (Agent Client Protocol) client for cleanup on exit.

**Parameters:**

* `client_id` (string) - Unique identifier for the client
* `client` (any) - ACP client instance

**Example:**

```lua theme={null}
local client = MyACPClient:new()
require('avante').register_acp_client("my-client", client)
```

**Source:** lua/avante/init.lua:31-34

***

### unregister\_acp\_client(client\_id)

Unregister an ACP client.

**Parameters:**

* `client_id` (string) - Unique identifier for the client

**Example:**

```lua theme={null}
require('avante').unregister_acp_client("my-client")
```

**Source:** lua/avante/init.lua:37-41

***

### cleanup\_all\_acp\_clients()

Cleanup all registered ACP clients (called automatically on exit).

**Example:**

```lua theme={null}
require('avante').cleanup_all_acp_clients()
```

**Source:** lua/avante/init.lua:43-54

***

## Module: `avante.api`

API module accessible via `require('avante.api')`.

### ask(opts)

Ask AI about code or start a chat session.

**Parameters:**

* `opts` (AskOptions|string|nil) - Options or question string

**AskOptions fields:**

* `question` (string|nil) - Question to ask
* `win` (table|nil) - Window options (similar to `nvim_open_win`)
* `ask` (boolean|nil) - Enable ask mode (default: `true`)
* `floating` (boolean|nil) - Use floating window for input
* `new_chat` (boolean|nil) - Start new chat session
* `without_selection` (boolean|nil) - Don't include current selection
* `sidebar_pre_render` (function|nil) - Callback before rendering
* `sidebar_post_render` (function|nil) - Callback after rendering
* `project_root` (string|nil) - Override project root
* `show_logo` (boolean|nil) - Show Avante logo

**Example:**

```lua theme={null}
local api = require('avante.api')

-- Simple question
api.ask({ question = "Explain this function" })

-- New chat session
api.ask({ new_chat = true })

-- With custom window position
api.ask({
  question = "Optimize this code",
  win = { position = "left" },
})

-- Floating input
api.ask({ floating = true })
```

**Source:** lua/avante/api.lua:132-186

***

### zen\_mode()

Open Avante in zen mode (full-screen chat experience).

**Example:**

```lua theme={null}
require('avante.api').zen_mode()
```

**Source:** lua/avante/api.lua:118-127, 129

***

### edit(request, line1, line2)

Edit selected code block with AI assistance.

**Parameters:**

* `request` (string|nil) - Editing instruction
* `line1` (integer|nil) - Start line (from visual selection)
* `line2` (integer|nil) - End line (from visual selection)

**Example:**

```lua theme={null}
local api = require('avante.api')

-- Edit with instruction
api.edit("Add error handling", 10, 20)

-- Edit with prompt (opens input window)
api.edit()
```

**Source:** lua/avante/api.lua:191-200

***

### refresh(opts)

Refresh Avante windows to sync with current buffer.

**Parameters:**

* `opts` (AskOptions|nil) - Refresh options

**Example:**

```lua theme={null}
require('avante.api').refresh()
```

**Source:** lua/avante/api.lua:209-228

***

### focus(opts)

Switch focus between sidebar and code window.

**Parameters:**

* `opts` (AskOptions|nil) - Focus options

**Example:**

```lua theme={null}
require('avante.api').focus()
```

**Source:** lua/avante/api.lua:231-255

***

### build(opts)

Build Avante.nvim dependencies.

**Parameters:**

* `opts` (table|nil) - Build options
  * `source` (boolean) - Build from source (default: `false`)

**Example:**

```lua theme={null}
local api = require('avante.api')

-- Build using pre-built binaries
api.build()

-- Build from source
api.build({ source = true })
```

**Source:** lua/avante/api.lua:47-104

***

### switch\_provider(target)

Switch the active AI provider.

**Parameters:**

* `target` (string) - Provider name (e.g., "claude", "openai", "gemini")

**Example:**

```lua theme={null}
require('avante.api').switch_provider("claude")
```

**Source:** lua/avante/api.lua:33

***

### switch\_selector\_provider(target\_provider)

Switch the selector provider (e.g., telescope, fzf\_lua).

**Parameters:**

* `target_provider` (string) - Selector provider name

**Example:**

```lua theme={null}
require('avante.api').switch_selector_provider("telescope")
```

**Source:** lua/avante/api.lua:15-21

***

### switch\_input\_provider(target\_provider)

Switch the input provider (native, dressing, snacks).

**Parameters:**

* `target_provider` (string) - Input provider name

**Example:**

```lua theme={null}
require('avante.api').switch_input_provider("snacks")
```

**Source:** lua/avante/api.lua:24-30

***

### select\_model()

Open the model selector UI.

**Example:**

```lua theme={null}
require('avante.api').select_model()
```

**Source:** lua/avante/api.lua:257

***

### select\_history()

Open the chat history selector.

**Example:**

```lua theme={null}
require('avante.api').select_history()
```

**Source:** lua/avante/api.lua:259-273

***

### add\_buffer\_files()

Add all open buffers to the selected files list.

**Example:**

```lua theme={null}
require('avante.api').add_buffer_files()
```

**Source:** lua/avante/api.lua:275-283

***

### add\_selected\_file(filepath)

Add a specific file to the chat context.

**Parameters:**

* `filepath` (string) - Path to the file

**Example:**

```lua theme={null}
require('avante.api').add_selected_file("/path/to/file.lua")
```

**Source:** lua/avante/api.lua:285-295

***

### remove\_selected\_file(filepath)

Remove a file or directory from the chat context.

**Parameters:**

* `filepath` (string) - Path to the file or directory

**Example:**

```lua theme={null}
require('avante.api').remove_selected_file("/path/to/file.lua")
```

**Source:** lua/avante/api.lua:297-318

***

### stop()

Stop the current AI request.

**Example:**

```lua theme={null}
require('avante.api').stop()
```

**Source:** lua/avante/api.lua:320

***

### get\_suggestion()

Get the current suggestion instance.

**Returns:**

* `avante.Suggestion|nil` - Current suggestion instance

**Example:**

```lua theme={null}
local suggestion = require('avante.api').get_suggestion()
if suggestion and suggestion:is_visible() then
  print("Suggestion is active")
end
```

**Source:** lua/avante/api.lua:203-206

***

## API Summary

### Main Module (`avante`)

| Function                          | Description             |
| --------------------------------- | ----------------------- |
| `setup(opts)`                     | Initialize plugin       |
| `get(current)`                    | Get current instances   |
| `toggle()`                        | Toggle sidebar          |
| `is_sidebar_open()`               | Check sidebar state     |
| `open_sidebar(opts)`              | Open sidebar            |
| `close_sidebar()`                 | Close sidebar           |
| `toggle.debug()`                  | Toggle debug mode       |
| `toggle.selection()`              | Toggle selection mode   |
| `toggle.suggestion()`             | Toggle auto-suggestions |
| `register_acp_client(id, client)` | Register ACP client     |
| `unregister_acp_client(id)`       | Unregister ACP client   |
| `cleanup_all_acp_clients()`       | Cleanup all ACP clients |

### API Module (`avante.api`)

| Function                           | Description              |
| ---------------------------------- | ------------------------ |
| `ask(opts)`                        | Ask AI or start chat     |
| `zen_mode()`                       | Full-screen chat mode    |
| `edit(request, line1, line2)`      | Edit code with AI        |
| `refresh(opts)`                    | Refresh windows          |
| `focus(opts)`                      | Switch focus             |
| `build(opts)`                      | Build dependencies       |
| `switch_provider(target)`          | Switch AI provider       |
| `switch_selector_provider(target)` | Switch selector UI       |
| `switch_input_provider(target)`    | Switch input UI          |
| `select_model()`                   | Open model selector      |
| `select_history()`                 | Open history selector    |
| `add_buffer_files()`               | Add all buffers          |
| `add_selected_file(filepath)`      | Add file to context      |
| `remove_selected_file(filepath)`   | Remove file from context |
| `stop()`                           | Stop AI request          |
| `get_suggestion()`                 | Get suggestion instance  |