Per Project Async Tasks in Nvim

As someone who tries to never leave the terminal, an ongoing gripe for me is starting up background tasks—say a Docker Compose server—without using up all of my screen space. For this, I found Overseer.nvim to be a really useful tool. But, as with the issue with many of the big and powerful nvim plugins, there are a lot of features that I don’t care for at all, which can make it hard to integrate into a workflow that I want.

So I spent the weekend doing a pretty extensive configuration of how to get Overseer to do what I want, and thought it might be useful to share.

The Goals

• Ability to run tasks in the background and display the output in a floating terminal
  
• Have saved tasks and runnable scripts per repo
  
• Be able to run a one-off task, then save it to run again

The first goal is completed simply by having Overseer installed, which you can do by including this in your config

call plug#begin()
Plug 'stevearc/dressing.nvim'
Plug 'nvim-telescope/telescope.nvim'
Plug 'stevearc/overseer.nvim'
call plug#end()

lua require('overseer').setup({})

For the 2nd and the third, I made a file called .overseer.lua in my root repo and outlined some task templates that I want to store:

-- .overseer.lua
return {
    {
        name = "Tidy Refs",
        builder = function(_)
            local cmd_str = table.concat({
                "npm install -g bibtex-tidy",
                "bibtex-tidy -m --curly --numeric --align=13 --duplicates=key no-escape --sort-fields --remove-empty-fields --no-remove-dupe-fields sort=-year,key --wrap=80 References/_references.bib",
            }, " && ")
            return {
                cmd = { "sh", "-c", cmd_str },
                components = { "default" },
                name = 'Tidy Refs'
            }
        end,
    },

    {
        name = "Build Site",
        builder = function(_)
            local cmd_str = table.concat({
                "pip install matplotlib numpy catppuccin beautifulsoup4 pandas Requests lxml",
                [[R -e 'install.packages(c("jsonlite","patchwork", "xgboost", "remotes"))']],
                [[R -e 'remotes::install_github("albert-ying/catppuccin")']],
                "quarto preview"
            }, " && ")
            return {
                cwd = "Website",
                cmd = { "sh", "-c", cmd_str },
                components = { "default" },
                name = 'Build Website'
            }
        end,
    },

}

Now the question becomes, how can I get overseer to read from this file?

Integrating Overseer

Luckily for me, overseer.nvim has a good system for importing tasks from files,
so it’s a simple function and autocommand to read the file and load the
templates on nvim start.

function load_project_overseer_templates()
    local file = vim.fn.getcwd() .. "/.overseer.lua"
    local ok, templates = pcall(dofile, file)
    if ok and type(templates) == "table" then
        for _, tpl in ipairs(templates) do
            require("overseer").register_template(tpl)
        end
        print("[Overseer] Loaded project templates from .overseer.lua")
    end
end

vim.api.nvim_create_autocmd("VimEnter", {
    callback = load_project_overseer_templates,
})

The harder thing is to be able to save tasks dynamically. I want to do this because I really like the OverseerBuild command, so being able to use that and then save them is really useful.

After a lot of trial and error, I was able to make an action inside Overseer that means when I hit S on a task in the task list.

require('overseer').setup({
    actions = {
        ["Save as template"] = {
      desc = "Save minimal task template with name, cwd, and cmd to .overseer.lua",
      condition = function(task)
        return task.serialize ~= nil
      end,
      run = function(task)
      -- grab the task information
        local def = task:serialize()

        -- Minimal fields: name, cwd, cmd only
        local minimal = {
          name = def.name,
          cwd = def.cwd,
          cmd = def.cmd,
        }

        -- function to extract the info  from the serialisation
        local function serialize(tbl, indent)
          indent = indent or 0
          local pad = string.rep("  ", indent)
          local chunks = {"{\n"}
          for k, v in pairs(tbl) do
            if v ~= nil then
              local key = type(k) == "string" and string.format("%s", k) or tostring(k)
              local value
              if type(v) == "string" then
                value = string.format("%q", v)
              elseif type(v) == "table" then
                if vim.tbl_islist(v) then
                  local parts = {}
                  for _, item in ipairs(v) do
                    table.insert(parts, string.format("%q", item))
                  end
                  value = "{ " .. table.concat(parts, ", ") .. " }"
                else
                  value = serialize(v, indent + 1)
                end
              else
                value = tostring(v)
              end
              table.insert(chunks, string.format("%s  %s = %s,\n", pad, key, value))
            end
          end
          table.insert(chunks, pad .. "}")
          return table.concat(chunks)
        end
        
        --- format the definition into a good format
        local block = string.format([[
{
  name = %q,
  builder = function()
    return %s
  end,
},
]], minimal.name or "Task", serialize(minimal))

        local path = vim.fn.getcwd() .. "/.overseer.lua"

        -- Read existing file or create new
        local lines = {}
        local file = io.open(path, "r")
        if file then
          for line in file:lines() do
            table.insert(lines, line)
          end
          file:close()
        else
          lines = { "return {", block, "}" }
        end

        -- Find closing brace to insert before
        local insert_index = nil
        for i = #lines, 1, -1 do
          if vim.trim(lines[i]) == "}" then
            insert_index = i
            break
          end
        end
        if not insert_index then
          vim.notify("No closing } found in .overseer.lua", vim.log.levels.ERROR)
          return
        end

        table.insert(lines, insert_index, block)

        file = io.open(path, "w")
        if not file then
          vim.notify("Failed to write to .overseer.lua", vim.log.levels.ERROR)
          return
        end
        file:write(table.concat(lines, "\n") .. "\n")
        file:close()

        vim.notify("✅ Task saved (name, cwd, cmd only) to .overseer.lua", vim.log.levels.INFO)
        load_project_overseer_templates()

      end,
        },
})