Augment Vim & Neovim Plugin

[!IMPORTANT] Project status: maintenance mode

• Inline code completions have been sunset and no longer function.
• The plugin is in maintenance mode: the Augment team takes care of bug fixes and security patches.
• Small feature requests will be considered.

A Quick Tour

Augment's Vim/Neovim plugin provides multi-turn chat conversations specially tailored to your codebase. The plugin is designed to work with any modern Vim or Neovim setup, and features the same underlying context engine that powers our VSCode and IntelliJ plugins.

Once you've installed the plugin, tell Augment about your project by adding workspace folders to your config file, and then sign-in to the Augment service. To ask questions about your codebase or request specific changes, use the :Augment chat command to start a chat conversation.

Note: Inline code completions have been sunset and are no longer available, even where older documentation or options still reference them.

Getting Started

1. Sign up for a free trial of Augment at augmentcode.com.

2. Ensure you have a compatible editor version installed. Both Vim and Neovim are supported, but the plugin may require a newer version than what is installed on your system by default.

   • For Vim, version 9.1.0 or newer.

   • For Neovim, version 0.10.0 or newer.

3. Install Node.js, version 22.0.0 or newer, which is a required dependency.

4. Install the plugin

   • Manual installation (Vim):

     git clone https://github.com/augmentcode/augment.vim.git \
         ~/.vim/pack/augment/start/augment.vim
     

   • Manual installation (Neovim):

     git clone https://github.com/augmentcode/augment.vim.git \
         ~/.config/nvim/pack/augment/start/augment.vim
     

   • Vim Plug:

     Plug 'augmentcode/augment.vim'
     

   • Lazy.nvim:

     { 'augmentcode/augment.vim' },
     

5. Add workspace folders to your config file. This is really essential to getting the most out of augment! See the Workspace Folders section for more information.

6. Open Vim and sign in to Augment with the :Augment signin command.

Basic Usage

The following commands are provided:

:Augment status        " View the current status of the plugin
:Augment signin        " Start the sign in flow
:Augment signout       " Sign out of Augment
:Augment log           " View the plugin log
:Augment chat          " Send a chat message to Augment AI
:Augment chat-input    " Compose a chat message in a floating window (Neovim only)
:Augment chat-new      " Start a new chat conversation
:Augment chat-toggle   " Toggle the chat panel visibility
:Augment help          " List the available commands, or `:Augment help ` for details

Workspace Folders

Workspace folders help Augment understand your codebase better by providing additional context. Adding your project's root directory as a workspace folder allows Augment to take advantage of context from across your project, rather than just the currently open file, improving the accuracy and style of chat responses.

You can configure workspace folders by setting g:augment_workspace_folders in your vimrc:

let g:augment_workspace_folders = ['/path/to/project', '~/another-project']

Workspace folders can be specified using absolute paths or paths relative to your home directory (~). Adding your project's root directory as a workspace folder helps Augment generate responses that match your codebase's patterns and conventions.

Note: This option must be set before the plugin is loaded.

After adding a workspace folder and restarting vim, the output of the :Augment status command will include the syncing progress for the added folder.

If you want to ignore particular files or directories from your workspace, you can create a .augmentignore file in the root of your workspace folder. This file is treated similar to a .gitignore file. For example, to ignore all files within the node_modules directory, you can add the following lines to your .augmentignore file:

node_modules/

For more information on how to use the .augmentignore file, see the documentation.

Augment also excludes ignored files and directories from its filesystem watcher, so adding large directories like node_modules/ to .augmentignore reduces the number of file watches Augment registers with the operating system. If the system file-watch limit is reached (for example fs.inotify.max_user_watches on Linux), Augment logs a warning (visible via :Augment log) and continues syncing the directories it is already watching.

Chat

Augment chat supports multi-turn conversations using your project's full context. Once a conversation is started, subsequent chat exchanges will include the history from the previous exchanges. This is useful for asking follow-up questions or getting context-specific help.

You can interact with chat in two ways:

1. Direct command with message:

   :Augment chat How do I implement binary search?
   

2. With selected text:

   • Select text in visual mode

   • Type :Augment chat followed by your question about the selection

The response will appear in a separate chat buffer with markdown formatting.

Floating chat input (Neovim only)

The :Augment chat-input command opens a centered floating window with a markdown scratch buffer where you can compose a chat message before sending it. This is handy for writing longer, multi-line prompts. The window opens in insert mode, and its title shows the available keys:

• (insert or normal mode) or (normal mode) submits the message
• (normal mode) or (insert or normal mode) cancels

Like :Augment chat, it is range-aware: invoking it from visual mode (or with a range) includes the selected text in the chat request once you submit.

If an input window is already open, running the command again refocuses it rather than opening a new one, so you won't lose what you've typed if focus moves away.

This command requires Neovim's floating window support. In Vim it falls back to the standard input() prompt used by :Augment chat, with no change to existing behavior. The plugin does not define a default mapping for it, so map it yourself if you'd like a shortcut, for example:

nnoremap ai :Augment chat-input
vnoremap ai :Augment chat-input

To start a new conversation, use the :Augment chat-new command. This will clear the chat history from your context.

Use the :Augment chat-toggle command to open and close the chat panel. When the chat panel is closed, the chat conversation will be preserved and can be reopened with the same command.

Completions (sunset)

Inline code completions have been sunset and no longer function. The completion-related options and mappings (such as augment#Accept(), g:augment_disable_tab_mapping, and g:augment_disable_completions) remain in the plugin for backwards compatibility, but they no longer have any effect.

FAQ

Q: How can I check whether the plugin is working?

A: You may want to first check the output of the :Augment status command. This command will show the current status of the plugin, including whether you're signed in and whether your workspace folders are synced. If you're not signed in, you'll need to sign in using the :Augment signin command. If those are not indicating a problem, you can check the plugin log using the :Augment log command. This will show any errors that may have occurred.

Q: Can I create shortcuts for the Augment commands?

A: Absolutely! You can create mappings for any of the Augment commands. For example, to create a shortcut for the :Augment chat* commands, you can add the following to your vimrc:

nnoremap ac :Augment chat
vnoremap ac :Augment chat
nnoremap an :Augment chat-new
nnoremap at :Augment chat-toggle

Q: My workspace is taking a long time to sync. What should I do?

A: It may take a while to sync if you have a very large codebase that has not been synced before. It's also not uncommon to inadvertenly include a large directory like node_modules/. You can use :Augment status to see the progress of the sync. If the sync is making progress but just slow, it may be worth checking if you have a large directory that you don't need to sync. You can add these directories to your .augmentignore file to exclude it from the sync. If you're still having trouble, please file a github issue with a description of the problem and include the output of :Augment log.

Licensing and Distribution

This repository includes two main components:

1. Vim Plugin: This includes all files in the repository except dist folder. These files are licensed under the MIT License.
2. Server (dist folder): This file is proprietary and licensed under a Custom Proprietary License.

For details on usage restrictions, refer to the LICENSE.md file.

Reporting Issues

We encourage users to report any bugs or issues directly to us. Please use the Issues section of this repository to share your feedback.

For any other questions, feel free to reach out to Augment Support.