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 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 Go to Trace Point (first item) to jump to that location (same as double-click).
7. Right-click a node and choose Copy Label 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 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.

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, and the IDE syncs the agent's trace-point changes as they are written. 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

Agent Skill Installation

Python required: skill ops are Python scripts, so Python 3 must be on your PATH (python3 or python).

Option 1: Install from a ZIP file

Extract the zip by hand, or run the Linux/macOS commands, or run the Windows PowerShell commands.

1. Download code-trace-tree-skill-1.3.5.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/

Or skip the manual extract and install from the command line (use one OS below):

Example below is Claude Code (~/.claude/skills/). Replace .claude with your agent from the table (for example .cursor, .copilot, .agents, or .gemini).

Linux & macOS

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

Project-local: unzip into .claude/skills/ (or your agent’s project-local path from the table) instead of the global folder.

Windows PowerShell

Same as the Linux/macOS commands, for Windows. Replace .claude with your agent from the table.

Invoke-WebRequest -Uri "https://github.com/saidake/code-trace-tree-vscode/releases/download/v1.3.5/code-trace-tree-skill-1.3.5.zip" -OutFile "code-trace-tree-skill-1.3.5.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.3.5.zip" -DestinationPath "$HOME\.claude\skills" -Force
Remove-Item "code-trace-tree-skill-1.3.5.zip"

Project-local: extract into .claude\skills\ (or your agent’s project-local path from the table).

Option 2: Install with npx (if you have Node.js)

If you already have Node.js, you can install the skill with npx. Pass -g for all projects; omit it for this project only. On Windows, add --copy if symlinks are not available. 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

Or 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.

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

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

How to use the skill

The agent loads global or project-local skills (including the installed code-trace-tree). Use it in your agent chat:

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

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: https://github.com/saidake/code-trace-tree-skill (copy in skills/code-trace-tree/ for zip packaging)

License

This project is licensed under the MIT License.