thought flow (plugin)

draught down some notes (with context) that don't belong as actual TODOs in your VCS.

Installation

lazy.nvim

Minimal setup (uses defaults):

{
  "nhomble/thought-flow.nvim",
  dependencies = { "MunifTanjim/nui.nvim" },
  opts = {}
}

With custom configuration:

{
  "nhomble/thought-flow.nvim",
  dependencies = { "MunifTanjim/nui.nvim" },
  config = function()
    require("thought-flow").setup({
      -- your custom config here
      annotations = {
        text = "▪",
        color = "#808080"
      }
    })
  end
}

Usage

The plugin provides user commands for easy access:

• :ThoughtFlowCapture - Capture a thought at the current cursor position
• :ThoughtFlowReview - Review all captured thoughts in a menu
• :ThoughtFlowRemoveLine - Remove thought at current cursor line
• :ThoughtFlowClear - Clear all thoughts

You can bind these to keymaps in your config:

vim.keymap.set('n', '<leader>tc', ':ThoughtFlowCapture<CR>', { desc = "Capture thought" })
vim.keymap.set('n', '<leader>tv', ':ThoughtFlowReview<CR>', { desc = "Review thoughts" })
vim.keymap.set('n', '<leader>td', ':ThoughtFlowRemoveLine<CR>', { desc = "Delete thought" })
vim.keymap.set('n', '<leader>tD', ':ThoughtFlowClear<CR>', { desc = "Clear all thoughts" })

Menu Actions (in Review mode):

• <Space> - Show full thought text in popup (supports visual mode, yank, search)
• <CR> - Navigate to file/line number where thought was captured
• d - Delete the selected thought
• j/k or arrow keys - Navigate thoughts
• / - Search forward through thoughts
• ? - Search backward through thoughts
• n - Jump to next search match
• N - Jump to previous search match
• <Esc> or <C-c> - Close menu

Notes:

• Long thoughts are automatically truncated with "..." in the menu list
• Orphaned thoughts (file or line no longer exists) are marked with [!] prefix
• You can still view orphaned thoughts with <Space>, but <CR> will show an error

Status Line Integration

You can display your thought count in your status line. The plugin provides a statistics() function that returns thought statistics.

Lualine:

require('lualine').setup({
  sections = {
    lualine_x = {
      function()
        local stats = require('thought-flow').statistics()
        local count = stats.global_count
        return count > 0 and ("▪ " .. count) or ""
      end,
      color = { fg = '#808080' },
    }
  }
})

Heirline (AstroNvim):

-- In lua/plugins/heirline.lua
return {
  "rebelot/heirline.nvim",
  opts = function(_, opts)
    local status = require("astroui.status")
    opts.statusline[#opts.statusline + 1] = status.component.builder({
      provider = function()
        local stats = require('thought-flow').statistics()
        local count = stats.global_count
        return count > 0 and ("▪ " .. count) or ""
      end,
      hl = { fg = "gray" },
    })
    return opts
  end,
}

Native statusline:

vim.o.statusline = vim.o.statusline .. '%{luaeval("(function() local s = require(\\'thought-flow\\').statistics(); return s.global_count > 0 and (\\'▪ \\' .. s.global_count) or \\'\\'  end)()")}'

The statistics() function returns a table with:

• global_count - Total number of thoughts across all files

API

capture

capture your thought

require("thought-flow").capture()

review

review your thoughts

require("thought-flow").review()

clear

clear your thoughts

require("thought-flow").clear()

Configuration

The plugin must be configured by calling setup() (shown in Installation above). Available options with their defaults:

require("thought-flow").setup({
  path = vim.fn.stdpath("data") .. "/thought-flow.json",
  ui = {
    prompt = "> ",
    max_thought_display_width = 50,  -- Truncate long thoughts in menu
  },
  notifications = {
    error = function(msg)
      vim.notify(msg, vim.log.levels.ERROR, { title = "thought-flow" })
    end,
  },
  annotations = {
    text = "▪",
    namespace = "thought-flow-namespace",
    color = "#808080"
  },
  orphaned = {
    indicator = "[!] ",  -- Prefix for orphaned thoughts
    color = "#ff0000"    -- Color for orphaned indicator (future use)
  },
  json = {
    decode = function(s) return vim.json.decode(s) end,
    encode = function(o) return vim.json.encode(o) end,
  },
  autocmd = {
    group = "thought-flow",
    pattern = "*",
  },
})

See config.lua for more details.