diff --git a/doc/fugitive-ts.nvim.txt b/doc/fugitive-ts.nvim.txt
index 8fb052d..a825909 100644
--- a/doc/fugitive-ts.nvim.txt
+++ b/doc/fugitive-ts.nvim.txt
@@ -25,6 +25,10 @@ SETUP                                                        *fugitive-ts-setup*
       -- Enable/disable highlighting (default: true)
       enabled = true,
 
+      -- Enable debug logging (default: false)
+      -- Outputs to :messages with [fugitive-ts] prefix
+      debug = false,
+
       -- Custom filename -> language mappings (optional)
       languages = {},
 
diff --git a/lua/fugitive-ts/highlight.lua b/lua/fugitive-ts/highlight.lua
index 3c29658..c77a3fa 100644
--- a/lua/fugitive-ts/highlight.lua
+++ b/lua/fugitive-ts/highlight.lua
@@ -1,9 +1,17 @@
 local M = {}
 
+---@param msg string
+---@param ... any
+local function dbg(msg, ...)
+  local formatted = string.format(msg, ...)
+  vim.notify('[fugitive-ts] ' .. formatted, vim.log.levels.DEBUG)
+end
+
 ---@param bufnr integer
 ---@param ns integer
 ---@param hunk fugitive-ts.Hunk
-function M.highlight_hunk(bufnr, ns, hunk)
+---@param debug? boolean
+function M.highlight_hunk(bufnr, ns, hunk, debug)
   local lang = hunk.lang
   if not lang then
     return
@@ -22,19 +30,29 @@ function M.highlight_hunk(bufnr, ns, hunk)
 
   local ok, parser_obj = pcall(vim.treesitter.get_string_parser, code, lang)
   if not ok or not parser_obj then
+    if debug then
+      dbg('failed to create parser for lang: %s', lang)
+    end
     return
   end
 
   local trees = parser_obj:parse()
   if not trees or #trees == 0 then
+    if debug then
+      dbg('parse returned no trees for lang: %s', lang)
+    end
     return
   end
 
   local query = vim.treesitter.query.get(lang, 'highlights')
   if not query then
+    if debug then
+      dbg('no highlights query for lang: %s', lang)
+    end
     return
   end
 
+  local extmark_count = 0
   for id, node, _ in query:iter_captures(trees[1]:root(), code) do
     local capture_name = '@' .. query.captures[id]
     local sr, sc, er, ec = node:range()
@@ -50,6 +68,11 @@ function M.highlight_hunk(bufnr, ns, hunk)
       hl_group = capture_name,
       priority = 200,
     })
+    extmark_count = extmark_count + 1
+  end
+
+  if debug then
+    dbg('hunk %s:%d applied %d extmarks', hunk.filename, hunk.start_line, extmark_count)
   end
 end
 
diff --git a/lua/fugitive-ts/init.lua b/lua/fugitive-ts/init.lua
index 9bc5d7a..8bd4977 100644
--- a/lua/fugitive-ts/init.lua
+++ b/lua/fugitive-ts/init.lua
@@ -1,5 +1,6 @@
 ---@class fugitive-ts.Config
 ---@field enabled boolean
+---@field debug boolean
 ---@field languages table<string, string>
 ---@field debounce_ms integer
 
@@ -17,6 +18,7 @@ local ns = vim.api.nvim_create_namespace('fugitive_ts')
 ---@type fugitive-ts.Config
 local default_config = {
   enabled = true,
+  debug = false,
   languages = {},
   debounce_ms = 50,
 }
@@ -27,6 +29,16 @@ local config = vim.deepcopy(default_config)
 ---@type table<integer, boolean>
 local attached_buffers = {}
 
+---@param msg string
+---@param ... any
+local function dbg(msg, ...)
+  if not config.debug then
+    return
+  end
+  local formatted = string.format(msg, ...)
+  vim.notify('[fugitive-ts] ' .. formatted, vim.log.levels.DEBUG)
+end
+
 ---@param bufnr integer
 local function highlight_buffer(bufnr)
   if not config.enabled then
@@ -39,9 +51,10 @@ local function highlight_buffer(bufnr)
 
   vim.api.nvim_buf_clear_namespace(bufnr, ns, 0, -1)
 
-  local hunks = parser.parse_buffer(bufnr, config.languages)
+  local hunks = parser.parse_buffer(bufnr, config.languages, config.debug)
+  dbg('found %d hunks in buffer %d', #hunks, bufnr)
   for _, hunk in ipairs(hunks) do
-    highlight.highlight_hunk(bufnr, ns, hunk)
+    highlight.highlight_hunk(bufnr, ns, hunk, config.debug)
   end
 end
 
@@ -77,6 +90,8 @@ function M.attach(bufnr)
   end
   attached_buffers[bufnr] = true
 
+  dbg('attaching to buffer %d', bufnr)
+
   local debounced = create_debounced_highlight(bufnr)
 
   highlight_buffer(bufnr)
diff --git a/lua/fugitive-ts/parser.lua b/lua/fugitive-ts/parser.lua
index 7ca5cb5..fec0dda 100644
--- a/lua/fugitive-ts/parser.lua
+++ b/lua/fugitive-ts/parser.lua
@@ -6,16 +6,27 @@
 
 local M = {}
 
+---@param msg string
+---@param ... any
+local function dbg(msg, ...)
+  local formatted = string.format(msg, ...)
+  vim.notify('[fugitive-ts] ' .. formatted, vim.log.levels.DEBUG)
+end
+
 ---@param filename string
 ---@param custom_langs? table<string, string>
+---@param debug? boolean
 ---@return string?
-local function get_lang_from_filename(filename, custom_langs)
+local function get_lang_from_filename(filename, custom_langs, debug)
   if custom_langs and custom_langs[filename] then
     return custom_langs[filename]
   end
 
   local ft = vim.filetype.match({ filename = filename })
   if not ft then
+    if debug then
+      dbg('no filetype for: %s', filename)
+    end
     return nil
   end
 
@@ -25,6 +36,11 @@ local function get_lang_from_filename(filename, custom_langs)
     if ok then
       return lang
     end
+    if debug then
+      dbg('no parser for lang: %s (ft: %s)', lang, ft)
+    end
+  elseif debug then
+    dbg('no ts lang for filetype: %s', ft)
   end
 
   return nil
@@ -32,8 +48,9 @@ end
 
 ---@param bufnr integer
 ---@param custom_langs? table<string, string>
+---@param debug? boolean
 ---@return fugitive-ts.Hunk[]
-function M.parse_buffer(bufnr, custom_langs)
+function M.parse_buffer(bufnr, custom_langs, debug)
   local lines = vim.api.nvim_buf_get_lines(bufnr, 0, -1, false)
   ---@type fugitive-ts.Hunk[]
   local hunks = {}
@@ -65,7 +82,10 @@ function M.parse_buffer(bufnr, custom_langs)
     if filename then
       flush_hunk()
       current_filename = filename
-      current_lang = get_lang_from_filename(filename, custom_langs)
+      current_lang = get_lang_from_filename(filename, custom_langs, debug)
+      if debug and current_lang then
+        dbg('file: %s -> lang: %s', filename, current_lang)
+      end
     elseif line:match('^@@.-@@') then
       flush_hunk()
       hunk_start = i