hledger-nvim

March 4, 2026 · View on GitHub

hledger plain text accounting support for Neovim — powered by the hledger language server.

Automatic LSP setup, workspace graph visualization, and full IDE features including completion, validation, formatting, navigation, and inlay hints.

Also available for VS Code.

Features

All features are provided by the hledger-lsp language server. This plugin handles setup and provides Neovim-specific UI:

LSP Integration — automatic hledger-lsp configuration via nvim-lspconfig
Completion — accounts, payees, commodities, tags, and context-aware suggestions
Validation — 15+ configurable rules (balance, undeclared items, date ordering, etc.)
Formatting — decimal-point alignment, commodity formatting, configurable indentation
Navigation — go to definition, find references, document/workspace symbols
Inlay Hints — inferred amounts, running balances, and cost conversions
Workspace Graph — :HledgerGraph floating window with fuzzy filtering and file preview

Prerequisites

Install the hledger-lsp language server:

npm install -g hledger-lsp

Verify it is in your PATH: hledger-lsp --version

Installation

lazy.nvim

{
  "ptimoney/hledger-nvim",
  ft = { "hledger", "journal" },
  dependencies = {
    "neovim/nvim-lspconfig",
  },
  config = function(_, opts)
    require("hledger").setup(opts)
  end,
}

Configuration

The setup function accepts a table with the following keys:

cmd: (table) The command to start the LSP server. Defaults to { "hledger-lsp", "--stdio" }.
lsp_opts: (table) Options passed to lspconfig.hledger_lsp.setup(). Use this to set on_attach, capabilities, and settings.
keymap: (string|false) Keybinding for :HledgerGraph. Defaults to "<leader>hg". Set to false to disable the default keybinding.

Example Configuration

{
  "ptimoney/hledger-nvim",
  ft = { "hledger", "journal" },
  dependencies = { "neovim/nvim-lspconfig" },
  opts = {
    -- Keymap for :HledgerGraph (default: "<leader>hg")
    -- Set to false to disable, or customize to your preference
    keymap = "<leader>hg",  -- or false to disable, or "<C-g>" etc.

    lsp_opts = {
      settings = {
        hledgerLanguageServer = {
          inlayHints = {
            showRunningBalances = true,
          },
          validation = {
            undeclaredAccounts = true,
          },
        },
      },
    },
  },
  config = function(_, opts)
    require("hledger").setup(opts)
  end,
}

For a complete list of available settings (validation, formatting, completion, etc.), see the language server configuration guide.

Default Settings Reference

Full configuration with all defaults (click to expand)

{
  "ptimoney/hledger-nvim",
  ft = { "hledger", "journal" },
  dependencies = { "neovim/nvim-lspconfig" },
  opts = {
    -- Keymap configuration
    keymap = "<leader>hg",  -- Default: opens workspace graph with <leader>hg
                            -- Set to false to disable default keybinding

    lsp_opts = {
      settings = {
        hledgerLanguageServer = {
          validation = {
            balance = true,
            missingAmounts = true,
            undeclaredAccounts = true,
            undeclaredPayees = false,
            undeclaredCommodities = true,
            undeclaredTags = false,
            dateOrdering = true,
            balanceAssertions = true,
            emptyTransactions = true,
            invalidDates = true,
            futureDates = true,
            emptyDescriptions = true,
            formatMismatch = true,
            includeFiles = true,
            circularIncludes = true,
            markAllUndeclaredInstances = true,
          },

          -- Severity levels for undeclared items
          --   "error" | "warning" | "information" | "hint"
          severity = {
            undeclaredAccounts = "warning",
            undeclaredPayees = "warning",
            undeclaredCommodities = "warning",
            undeclaredTags = "information",
          },

          -- Include directive behavior
          include = {
            followIncludes = true,
            maxDepth = 10,
          },

          -- Workspace settings
          workspace = {
            enabled = true,
            eagerParsing = true,
            autoDetectRoot = true,
          },

          -- Completion filtering (only show declared items)
          completion = {
            onlyDeclaredAccounts = true,
            onlyDeclaredPayees = true,
            onlyDeclaredCommodities = true,
            onlyDeclaredTags = true,
          },

          -- Formatting options
          formatting = {
            indentation = 4,
            maxCommodityWidth = 4,
            maxAmountIntegerWidth = 12,
            maxAmountDecimalWidth = 3,
            minSpacing = 2,
            decimalAlignColumn = 52,
            assertionDecimalAlignColumn = 70,
            signPosition = "after-symbol",
            showPositivesSign = false,
          },

          -- Inlay hints (showRunningBalances is off by default as
          --              otherwise it can be very busy)
          inlayHints = {
            showInferredAmounts = true,
            showRunningBalances = false,
            showCostConversions = true,
          },

          -- Code lens (default to false)
          codeLens = {
            showTransactionCounts = false,
          },

          -- General settings
          maxNumberOfProblems = 1000,
          hledgerPath = "hledger",  -- Path to hledger executable
        },
      },
    },
  },
  config = function(_, opts)
    require("hledger").setup(opts)
  end,
}

Commands and Keybindings

Commands

Command	Description
`:HledgerGraph`	Open the workspace graph in a floating window

Default Keybindings

Key	Description
`<leader>hg`	Open workspace graph (customizable via `keymap` option)

Workspace Graph Window

Key	Action
`Enter`	Open selected file
`/`	Filter files (fuzzy search)
`za`	Toggle fold
`q` / `Esc`	Close window

Requirements

Neovim >= 0.9.0
hledger-lsp installed and in PATH
nvim-lspconfig

Project	Description
hledger-lsp	Language server powering this plugin
hledger-vscode	VS Code extension with the same language server
hledger	The plain text accounting tool

Contributing

Found a bug or have a feature request?

Plugin issues (Neovim UI, setup, keybindings): hledger-nvim issues
Server issues (parsing, validation, formatting, completion): hledger-lsp issues

Contributions are welcome — please feel free to submit a Pull Request.

License

MIT