github github
stars 45
issues 2
subscribers 1
forks 3



last month


A customizable Neovim plugin to run code inside the editor


Table of Contents


Using packer.nvim:

return require('packer').startup(function(use)
  use {
    requires = {
      requires = { 'nvim-lua/plenary.nvim' }
    config = function()

Using lazy.nvim:

    dependencies = {
      dependencies = { 'nvim-lua/plenary.nvim' }
    config = function()



Command lua Description
:Runner require('runner').run() Runs code in buffer
:AutoRunner require('runner').autorun() Runs code in buffer on every file save
:AutoRunnerStop require('runner').autorun_stop() Stops AutoRunner and closes the window



-- Can also be called with the buffer number where the code is:
-- require('runner').run( <buffer_number> )
-- require('runner').autorun( <buffer_number> )

-- To set a mapping
vim.keymap.set('n', '<leader><space>', require('runner').run)



Runner comes with the following defaults:

  position = 'right', -- position of the terminal window when using the shell_handler
                      -- can be: top, left, right, bottom
                      -- will be overwritten when using the telescope mapping to open horizontally or vertically

  width = 80,         -- width of window when position is left or right
  height = 10,        -- height of window when position is top or bottom

  handlers = {} -- discussed in the next section


Runner has the concept of handlers. Handlers are language specific and are little functions that run code. For example, a handler could run the project, run the tests, build the project, or even run custom project scripts.

A handler is a function that accepts a buffer number as an argument, and doesn't return anything. This buffer number is the buffer where the code to run is located. It defaults to the buffer where the run() function was called, or, if specified, is the buffer number that was passed to the run() function. Runner runs the appropriate handler based on this buffer's filetype.

Default handlers can be found here.

When setting a handler, you should pass the following arguments

Argument Description Type
filetype The filetype on which to run the given handler string
handler The handler to run when the current file matches the filetype function(bufnr)

There are 2 ways to set handlers. Both of them overwrite the handlers already set for the specified filetype.

  • setup(options)

    You can pass the handlers you want to set to the setup() function. The handlers table has the following format:

      ["filetype"] = handler


      -- Other options
      handlers = {
        lua = function(bufnr)
          vim.print('Running lua file in buffer ' .. bufnr)
          -- Run the file here
  • set_handler(filetype, handler)


    require('runner').set_handler('lua', function(bufnr)
      vim.print('Running lua file in buffer ' .. bufnr)
      -- Run the file here

NOTE: For using multiple handlers on the same filetype, see the choice helper.


This plugin exposes some helpers to make creating handlers easier. They're all available by importing them as follows:

local helper_name = require('runner.handlers.helpers').helper_name

Here is a description of each one:

  • shell_handler(command, editable)

    Runs a command in a shell by opening it in a new split window, with a terminal buffer.

    The split window's position will be determined by the position value from the config. It will be overwritten when using the telescope mapping to open horizontally or vertically.

    • select_horizontal (defaults to <C-X>): Opens the window at the bottom of the screen.

    • select_vertical (defaults to <C-V>): Opens the window at the right of the screen.

      Argument name Description Type
      command The shell command to run when the handler is called string
      editable Whether the user should be prompted to edit the command using vim.input() before running it. Useful when giving command line arguments to a script boolean (optional, defaults to false)


      local shell_handler = require('runner.handlers.helpers').shell_handler
      require('runner').set_handler('rust', shell_handler('cargo run', true))
  • command_handler(command)

    Runs a command in the Vim command mode.

    Argument name Description Type
    command The Vim command to run when the handler is called string


    local command_handler = require('runner.handlers.helpers').command_handler
    require('runner').set_handler('lua', command_handler('luafile %'))
  • choice(handlers)

    Opens a Telescope finder to allow the user to choose which handler to run.

    Argument name Description Type
    handlers The list of handlers to choose from table where the keys are the name of the handlers in the telescope finder, and where the values are the actual handlers


    local choice = require('runner.handlers.helpers').choice
    require('runner').set_handler('rust', choice({
      ['Run'] = helpers.shell_handler('cargo run'),
      ['Test'] = helpers.shell_handler('cargo test'),
      ['Custom'] = helpers.shell_handler('cargo ', true),

Advanced handlers configurations

For creating dynamic handlers like one for each npm or cargo script, you can write your own handler function that generates the other handlers, gives them to the choice handler, and runs it itself. See Node.js example.


This project uses StyLua for enforcing code style, and has a pre-commit hook setup for running it automatically. runner.nvim also has a Github Action that runs the linter on every Pull request. If a check doesn't pass on a specific Pull request, please lint the code and commit it again.

For running them locally, you have to have them installed on your system:

Some useful commands

  • Install the pre-commit hook

    pre-commit install
  • Check for StyLua errors

    stylua --check lua/
  • Fix StyLua errors

    stylua lua/

    Licensed under the MIT license.