code-trace.nvim

CodeTrace is a Neovim comprehension layer on top of LSP. LSP answers "where is X defined" and "what calls X"; CodeTrace asks a coding-agent CLI for a compact map of a symbol's role, callers, effects, consumers, and warnings.

It shells out to codex exec by default with a read-only sandbox and schema-validated JSON output. Successful traces are cached by git HEAD, repo-relative file, line, symbol, and mode.

Requirements

• Neovim 0.12+
• git
• codex on PATH, or another compatible headless agent command

Installation

With Neovim's built-in package manager:

vim.pack.add({
  { src = 'https://github.com/YOUR-USER/code-trace.nvim', version = 'main' },
})

require('code-trace').setup()

For local development, add the checkout to runtimepath before calling setup():

vim.opt.runtimepath:prepend(vim.fs.joinpath(vim.env.HOME, 'code', 'code-trace.nvim'))
require('code-trace').setup()

Usage

• <leader>gt / :CodeTrace: map the symbol under the cursor with local, single-package scope.
• <leader>gT / :CodeTraceWide: map the symbol under the cursor with wider cross-package scope.
• <leader>gs / :CodeTraceShow: reopen the last map with the cursor restored.
• :CodeTraceForce: bypass the cache for a fresh local trace.
• :CodeTraceClearCache: delete cached maps.

Inside the floating map:

• <CR> jumps to the file and line under the cursor.
• <Tab> and <S-Tab> cycle interactive rows.
• r reruns local scope without cache.
• R reruns wide scope without cache.
• q or <Esc> closes the map.

Configuration

require('code-trace').setup({
  agent_cmd = 'codex',
  cache_dir = vim.fn.stdpath('cache') .. '/codetrace',
  reasoning_local = 'medium',
  reasoning_wide = 'high',
  timeout_local_ms = 180000,
  timeout_wide_ms = 600000,
  keymaps = {
    trace_local = '<leader>gt',
    trace_wide = '<leader>gT',
    show_last = '<leader>gs',
  },
})

Set keymaps = false to register only commands and call the Lua API from your own mappings.

The older vim.g.codetrace_* globals are still honored when a setup option is not provided:

• vim.g.codetrace_agent_cmd
• vim.g.codetrace_cache_dir
• vim.g.codetrace_reasoning_local
• vim.g.codetrace_reasoning_wide
• vim.g.codetrace_timeout_local_ms
• vim.g.codetrace_timeout_wide_ms

Lua API

local code_trace = require('code-trace')

code_trace.trace_local()
code_trace.trace_wide()
code_trace.trace('local', true)
code_trace.show_last()
code_trace.clear_cache()

Cache

Maps are cached under stdpath('cache')/codetrace/cache/<sha256>.json by default. The key includes git HEAD, so committed changes, branch switches, and rebases invalidate old maps automatically. Uncommitted edits can still return a stale map; use r, R, :CodeTraceForce, or :CodeTraceClearCache when needed.