Code Trace Tree

---

Let AI agents help you build and display code workflows as nested trace points (lines, files, and directories) so you can follow the flow and jump back to source anytime. Double-click any trace point to navigate to its source, with support for multiple trace levels.

By default, add trace points from the editor right-click menu. Install the Agent Skill so a coding agent can search, add, move, and rebind traces, and notify the IDE when you ask (for example Claude Code, Cursor, or Gemini CLI).
This plugin does not include an AI agent; install your preferred agent separately, then install the Code Trace Tree skill. Once installed, the agent can auto-load it when relevant.

Preview

How to use

1. Open the Code Trace Tree tool window (right side of the IDE).
2. Use the Profile selector under the toolbar to switch trees, add a profile (+), or delete one from the dropdown.
3. In the editor, right-click a line in a project file and choose:
   • Create a Root Trace Point — start a new line-level trace tree (selects the new node; does not jump)
   • Create a Trace Point (Under Selected) — add a child under the selected node(s) in the tree (new node is selected)
   • Update the selected code trace point — move the selected tree node(s) to the current line
   • Go to the Trace Point in the tree panel (Only matching) — selects and reveals matching node(s) for the current line; does nothing when none match
4. In the Project tool window, right-click a file or directory inside the project and choose:
   • Create a Root Trace Point — add a file or directory node at the root
   • Create a Trace Point (Under Selected) — add that file/directory under the selected tree node(s)
5. Single-click a node to select it; double-click to jump to that location (line, file, or Project View for directories).
6. Right-click a node and choose Go to Trace Point (first item) to jump to that location (same as double-click).
7. Right-click a node and choose Copy Label (or use Ctrl/Cmd+C) to copy its display text, e.g. test233 (TestControllerWebFlux.java:54).
8. Right-click a line trace point and choose Show Line Content to view its saved trimmed line text.
9. Use the tool window toolbar to expand/collapse, Recheck Trace Availability, Remove Invalid Trace Points, reorder, highlight, prompt for name on create, or edit descriptions. Import/Export live under Advanced Settings.

TIPS: Prefer creating line trace points on text that is unique in that file (or uncommon), not generic lines like } or return;. Empty lines are not allowed. The plugin stores occurrence counts to re-find the line after it moves; unique content rebinds more reliably. Opening a file re-checks line traces in that file so highlights and validity stay aligned. Use Recheck Trace Availability in the toolbar to recheck every line, file, and directory trace.

Agent Skill

This plugin does not ship an AI agent. Install your preferred coding agent, then install the Code Trace Tree skill. Once installed, the agent can auto-load it when your request is relevant. The skill is general — any agent that can load skill folders can use it.

Example agents:

• Claude Code
• Cursor
• GitHub Copilot (agent skills)
• Codex
• Gemini CLI

The skill lets the agent:

• Resolve the bound global storage XML for the project
• Search, add, move, and delete trace points
• Rebind line locations after source edits on disk
• Ask the IDE to reload / refresh plugin data
• Select or navigate to nodes in the Code Trace Tree tool window

Python required: the main skill ops (trace_tree search / add / move / delete / rebind) run trace_tree.py, so Python 3 must be on your PATH (python3 or python). Resolve / refresh / select helper scripts are plain shell or batch and do not need Python.

Agent Skill Installation

Option 1: Install with npx (Recommended)

Requires Node.js (npx). Pass -g for all projects; omit it for this project only. On Windows, add --copy if symlinks are not available. This installs from the dedicated skill repo (small clone, default branch). If the skill is already installed, remove it first — npx skills add does not overwrite an existing skill.

npx skills remove code-trace-tree -g
npx skills add saidake/code-trace-tree-skill -g

Explicit, non-interactive install for the agent you currently use (Cursor example):

npx -y skills remove code-trace-tree --agent cursor --global --yes
npx -y skills add saidake/code-trace-tree-skill --skill code-trace-tree --agent cursor --global --copy --yes

Set --agent to your current agent, for example cursor, claude-code, github-copilot, codex, or gemini-cli.

Try without installing (Codex example; same --agent values):

npx skills use saidake/code-trace-tree-skill@code-trace-tree --agent codex

Option 2: Install from a ZIP file

1. Download code-trace-tree-skill-1.3.3.zip from the GitHub Release (one zip works across agents).
2. Delete any existing code-trace-tree folder in the skills directory for your agent (table below), then extract the zip into that directory. The zip contains one code-trace-tree folder (with SKILL.md inside). Global = all projects; project-local = this repo only.

Done when the skills directory contains code-trace-tree/SKILL.md (not the zip file, and not an extra nested code-trace-tree/code-trace-tree folder).

Agent (examples)	Global	Project-local
Claude Code	~/.claude/skills/	.claude/skills/
Cursor	~/.cursor/skills/	.cursor/skills/
GitHub Copilot	~/.copilot/skills/	.github/skills/
Codex	~/.agents/skills/	.agents/skills/
Gemini CLI	~/.gemini/skills/	.gemini/skills/

How to use the skill

Installing the skill makes it available to the agent:

• Project-local — npx..., omit -g, or extract the zip into the project skills folder
• Global — npx..., pass -g, or extract the zip into the global skills folder

If the IDE is open on this project, it loads the agent’s trace point changes in real time (no manual reload).

Examples:

Help me generate some simple trace points related to the current topic.

Add simple trace points along the call path of method `test`.

Storage

Trace data is stored in a shared global folder:

• Windows: %LOCALAPPDATA%\code-trace-tree
• macOS: ~/Library/Application Support/code-trace-tree
• Linux: $XDG_CONFIG_HOME/code-trace-tree or ~/.config/code-trace-tree

Each project uses <projectId>.xml in that folder (legacy <FolderName>.xml files from older releases are still resolved and renamed when found). The IDE may cache the id in .idea/code-trace-tree.project.id. Agents use path mode: prefer an existing .idea id (recreate that XML if missing), else path match, else Case C create with <path> only (never write the .idea id). The IDE binds via path match + storage-ready (signal body = project path). Highlight colors are a global preference (settings.xml in that folder), shared across projects and IDEs (defaults #FFFFC8 light, #236C60 dark).

Development

• JDK 21
• Open the project root in IntelliJ IDEA and import as a Gradle project
• Run the Run Plugin configuration (or :main:runIde) to launch a sandbox IDE
• Shared agent skill: https://github.com/saidake/code-trace-tree-skill (copy in skills/code-trace-tree/ for zip packaging)

Contributing

If you would like to contribute to the code base or fix an issue, please see CONTRIBUTING.md.