MantisBT plugin for Neovim.

Features

• Supports multiple MantisBT hosts
• Built with nui.nvim and nui-components
• Cross-platform (Linux, macOS, Windows)

Issues List

• Open as a centered floating window or a native split panel (layout), toggleable at runtime with <C-s>
• Smart split placement: split_position = 'auto' docks on the right on landscape screens and the bottom on portrait
• Single instance: re-opening the list focuses the existing panel instead of stacking duplicates
• Auto-refreshes on a configurable interval, preserving your cursor row and selection
• Configurable issue properties and column widths
• Pagination for large result sets
• Filter by all, assigned, reported, monitored, or unassigned issues
• Assign issues to users
• Create and delete issues
• Open issues directly in your browser
• Update status, priority, severity, category, and summary
• Add notes to existing issues
• Monitor/unmonitor issues (monitored issues show a 👁 indicator in the list)
• Toggle grouped/ungrouped view (group by project)
• Priority emojis with customizable icons
• Selection and batch operations

Batch Operations

• Select individual issues or select all on current page
• Batch change status, priority, severity, category
• Batch assign users to multiple issues
• Batch delete issues

Create Issue

• Assign user
• Set category, priority, severity, and reproducibility
• Add summary and description

View Issue

• Inspect full issue details including custom fields
• Browse and add notes with optional time tracking
• Delete notes
• Review issue history

Requirements

• Neovim 0.9.0 or higher
• MantisBT server with REST API enabled (v2.0+)

Installation

This plugin relies on the following external dependencies:

• nvim-lua/plenary.nvim
• MunifTanjim/nui.nvim
• grapp-dev/nui-components.nvim

Using lazy.nvim

{
  'whleucka/mantis.nvim',
  dependencies = {
    'nvim-lua/plenary.nvim',
    'MunifTanjim/nui.nvim',
    'grapp-dev/nui-components.nvim',
  },
  config = function()
    require('mantis').setup({
      hosts = {
        {
          name = "My MantisBT",
          url = "https://mantis.example.com",
          env = "MANTIS_API_TOKEN",
        },
      },
    })
  end,
}

Using packer.nvim

use {
  'whleucka/mantis.nvim',
  requires = {
    'nvim-lua/plenary.nvim',
    'MunifTanjim/nui.nvim',
    'grapp-dev/nui-components.nvim',
  },
}

Configuration

To use mantis.nvim, you need to configure your MantisBT hosts. Each host entry should include:

• name (optional): Display name for the host
• url (required): Base URL of your MantisBT instance (without /api/rest)
• token or env (required): Either a hardcoded API token or the name of an environment variable containing the token

Getting an API Token

1. Log in to your MantisBT instance
2. Go to My Account -> API Tokens
3. Create a new token with appropriate permissions
4. Copy the token and store it securely

Example Configuration

require('mantis').setup({
  hosts = {
    {
      name = "Work MantisBT",
      url = "https://mantis.company.com",
      env = "WORK_MANTIS_TOKEN", -- Reads from environment variable
    },
    {
      name = "Personal MantisBT",
      url = "https://my.mantisbt.org",
      token = "your-api-token-here", -- Hardcoded token (less secure)
      default = true, -- Skip host selection and always use this host
    },
  },
})

default = true — when a host is marked as default, the host selection prompt is skipped and that host is used directly, even if multiple hosts are configured.

Hosts that read their token from an environment variable (env) are only shown in the selection list when that variable is actually set; otherwise they are silently dropped.

Default Configuration

{
  debug = false,
  hosts = {},
  add_note = {
    ui = {
      width = 60,
      height = 10,
      max_width = 80,
      max_height = 20,
    },
    keymap = {
      quit = "q",
      submit = "<M-CR>",
    }
  },
  create_issue = {
    ui = {
      width = 80,
      height = 21,
      max_width = 120,
      max_height = 30,
    },
    keymap = {
      quit = "q",
      submit = "<M-CR>",
    }
  },
  view_issue = {
    ui = {
      width = 80,
      height = 30,
      max_width = 120,
      max_height = 40,
    },
    keymap = {
      quit = "q",
      refresh = "r",
      add_note = "N",
      delete_note = "dn",
      scroll_down = "j",
      scroll_up = "k",
      page_down = "<C-d>",
      page_up = "<C-u>",
      goto_top = "gg",
      goto_bottom = "G",
    }
  },
  view_issues = {
    default_filter = 'all', -- 'all', 'assigned', 'reported', 'monitored', 'unassigned'
    limit = 42, -- issues per page
    -- Silently re-fetch the list on this interval (seconds); 0/false disables.
    -- Preserves cursor row and selection.
    auto_refresh_interval = 120,
    -- Window layout: 'float' (centered popup) or 'split' (docked panel).
    layout = 'float',
    -- Where the docked panel sits when layout = 'split'.
    --   'auto'  -> 'right' on landscape screens, 'bottom' on portrait
    --   'right' | 'left' | 'bottom' -> force a side
    split_position = 'auto',
    split_size = 0.40, -- fraction of the screen the panel occupies
    -- Cell height:width ratio used to infer orientation for 'auto'
    -- (terminal cells are ~twice as tall as wide).
    split_cell_aspect = 2.0,
    ui = {
      -- window size for the float layout (percentages like "90%" or numbers)
      width = "90%",
      height = "80%",
      max_width = 180,
      max_height = 50,
      -- column widths (summary is calculated dynamically to fill remaining space)
      columns = {
        priority = 1,
        id = 7,
        severity = 10,
        status = 24,
        category = 12,
        summary = nil, -- auto-calculated based on available width
        updated = 10
      }
    },
    keymap = {
      next_page = "L",
      prev_page = "H",
      add_note = "N",
      create_issue = "C",
      delete_issue = "D",
      open_issue = "o",
      assign_issue = "a",
      change_summary = "S",
      change_status = "s",
      change_severity = "V",
      change_priority = "p",
      change_category = "c",
      monitor = "m",
      filter = "F",
      toggle_group = "<C-g>",
      toggle_layout = "<C-s>",
      help = "?",
      refresh = "r",
      quit = "q",
      -- Selection
      toggle_select = "<Space>",
      select_all = "<C-a>",
      clear_selection = "<C-x>",
      -- Batch operations
      batch_status = "bs",
      batch_priority = "bp",
      batch_severity = "bv",
      batch_category = "bc",
      batch_assign = "ba",
      batch_delete = "bD",
    }
  },
  issue_filter_options = {
    'all',
    'assigned',
    'reported',
    'monitored',
    'unassigned',
  },
  priority_emojis = {
    complete  = "✅",
    immediate = "🔥",
    urgent    = "⚠️",
    high      = "🔺",
    low       = "🔻",
    normal    = "🔵",
    default   = "🟣",
  },
  -- Indicator shown beside issues you are monitoring. Defaults to the 👁 emoji;
  -- set a Nerd Font glyph (e.g. "" / nf-fa-eye) if your font renders it better.
  monitor_icon = "👁️",
}

Usage

Commands

Command	Description
:MantisIssues	Open the issues view
:MantisIssue <id>	View a specific issue by ID
:MantisSelectHost	Switch between configured hosts

Keymaps (Issues View)

Key	Action
?	Toggle help
<CR>	View issue details
o	Open issue in browser
C	Create new issue
N	Add note to issue
D	Delete issue
a	Assign issue
s	Change status
p	Change priority
V	Change severity
c	Change category
S	Change summary
m	Toggle monitoring an issue (monitored issues show a 👁 indicator)
F	Filter issues
<C-g>	Toggle group by project
<C-s>	Toggle float/split layout
r	Refresh
L	Next page
H	Previous page
q	Quit

Selection

Key	Action
<Space>	Toggle select issue
<C-a>	Select all issues on page
<C-x>	Clear selection

Batch Operations

Key	Action
bs	Batch change status
bp	Batch change priority
bv	Batch change severity
bc	Batch change category
ba	Batch assign user
bD	Batch delete issues

Keymaps (Issue View)

Key	Action
j / k	Scroll down/up
<C-d> / <C-u>	Page down/up
gg / G	Go to top/bottom
N	Add note
dn	Delete note
r	Refresh
q	Quit

Keymaps (Add Note)

Key	Action
<M-CR>	Submit
q	Quit

Keymaps (Create Issue)

Key	Action
<M-CR>	Submit
q	Quit

Troubleshooting

"Environment variable not set" error

Make sure the environment variable specified in your env config is set before starting Neovim:

export MANTIS_API_TOKEN="your-token-here"
nvim

API errors

• Verify your MantisBT URL is correct (should not include /api/rest)
• Check that your API token has the required permissions
• Ensure your MantisBT server has the REST API enabled

Connection issues

• Check your network connection
• Verify the MantisBT server is accessible
• If using HTTPS, ensure SSL certificates are valid

Screenshots

View issues (split)

View issues (float)

View issue

Create issue

License

MIT