Code Trace Tree

---

Trace code in a tree structure. 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.

Pair it with the Agent Skill so a coding agent can search, add, move, and rebind traces, and refresh the IDE when you ask (for example Claude Code, Cursor, or Gemini CLI).
This extension 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 activity bar view.
2. Use the Profile webview above the tree to switch trees, add a profile, or delete one.
3. In the editor, right-click a line in a workspace file and choose:
   • Create a Root Code Trace Point — start a new line-level trace tree (selects the new node; does not jump)
   • Create Code Trace Points (Under selected) — add a child under the selected node(s) in the tree (parent expands; new node is selected)
   • Update Selected Trace Points — 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 Explorer, right-click a file or directory inside the workspace and choose:
   • Create a Root File/Directory Trace Point — add a file or directory node at the root
   • Create File/Directory Trace Point (Under selected) — add that file/directory under the selected tree node(s) (parent expands automatically)
5. Single-click a node to select it; double-click to jump to that location (line, file, or Explorer for folders). Double-click restores the prior expand/collapse state if the host toggled it (brief flicker possible).
6. Right-click a node and choose Copy Label to copy its display text, e.g. test233 (TestControllerWebFlux.java:54).
7. Right-click a line trace point and choose Show Line Content to view its saved trimmed line text.
8. Use the view title-bar actions 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. Drag a node onto another to reparent it (the target expands automatically).

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 extension 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 extension 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 extension data
• Select or navigate to nodes in the Code Trace Tree view

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.

Install skill — extract locations

Download code-trace-tree-skill-1.2.9.zip from the GitHub Release (one zip works across agents). Remove any existing code-trace-tree skill folder first, then extract into your agent’s skills directory. Known paths for some agents:

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/

Install example (Claude Code, Linux & macOS)

curl -L https://github.com/saidake/code-trace-tree-vscode/releases/download/v1.2.9/code-trace-tree-skill-1.2.9.zip -o code-trace-tree-skill-1.2.9.zip
rm -rf ~/.claude/skills/code-trace-tree
mkdir -p ~/.claude/skills
unzip code-trace-tree-skill-1.2.9.zip -d ~/.claude/skills/
rm code-trace-tree-skill-1.2.9.zip

Project-local: extract into .claude/skills/ instead of ~/.claude/skills/. For other agents, use the same zip and extract into that agent’s folder from the table above.

Install example (Claude Code, Windows PowerShell)

Invoke-WebRequest -Uri "https://github.com/saidake/code-trace-tree-vscode/releases/download/v1.2.9/code-trace-tree-skill-1.2.9.zip" -OutFile "code-trace-tree-skill-1.2.9.zip"
Remove-Item -Recurse -Force "$HOME\.claude\skills\code-trace-tree" -ErrorAction SilentlyContinue
New-Item -ItemType Directory -Force -Path "$HOME\.claude\skills" | Out-Null
Expand-Archive -Path "code-trace-tree-skill-1.2.9.zip" -DestinationPath "$HOME\.claude\skills" -Force
Remove-Item "code-trace-tree-skill-1.2.9.zip"

Project-local: extract into .claude\skills\. For other agents, use the same zip and change the destination to that agent’s skills path (see the table above for examples).

How to use the skill

Installing the skill makes it available to the agent:

• Project-local — available in agent sessions for that project
• Global — available across projects for that agent

In VS Code, keep the extension open for the same project: it loads the agent’s trace point changes in real time (no manual reload).

Examples:

Help me generate some trace point nodes related to the current topic.

Add a root trace point at the login handler, then children for validation and token issue.

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

• Binding: each workspace matches a global XML by <path> (path mode).
• New projects: allocate <ProjectFolderName>.xml (or Name1.xml, …) with a UUID <projectId> on first use.
• Agents (Case C): create that global XML without .idea/code-trace-tree.project.id (IDE-agnostic).
• Legacy: <projectId>.xml and folder-named files from older releases are still resolved by scanning XML contents.
• No workspace: the empty panel asks you to open one (Profile / Description / toolbar stay hidden).
• Empty tree: an empty-state webview explains how to create a root trace point (no nodes; only the default main profile or no profiles).
• Recover UI: grey Import stored data after move/rename appears only when another stored global project still has a trace point. Clearing this workspace’s tree (including delete-all) does not keep recover UI visible for the bound file while it is empty.

Development

• Open the project root in VS Code / Cursor
• Install deps: cd main && yarn install
• Press F5 to launch an Extension Development Host
• Shared agent skill source: skills/code-trace-tree/

License

This project is licensed under the MIT License.