saidake/code-trace-tree-vscode/code-trace-tree

Code Trace Tree

Build and display code workflows as nested trees of line, file, and directory trace points. Use the provided Python scripts to operate the hybrid storage used by Code Trace Tree IDE plugins, then ask the IDE to reload.

Only edit or sync traces when the user explicitly asks (for example: generate topic-related nodes, add a tip at a line, rebind after edits). Do not auto-sync every turn. Never delete existing trace points (including ones rebind reports as "invalid") unless the user explicitly asks to remove them.

How to use this skill

Read this SKILL.md only. Do not list, search, or explore this skill's scripts/ or references/ folders, and do not open script source to learn the API. Invoke the documented Python commands by absolute path.

Open scripts/ or references/ only if you hit a critical problem while using the skill (script missing or crashing, storage corrupt, or an error this file does not cover).

Chat replies: Script stdout and tree JSON are long. Do not paste them into the user-visible message. Summarize the result (created/skipped counts, names, errors).

Skill scripts location

Helper scripts live under <Agent Skill Path>/code-trace-tree/scripts/.

Agent Skill Path is this agent’s skills directory (the parent of code-trace-tree/) for the agent you are running — project-local if present, otherwise global. It ends at skills, not at code-trace-tree. Paths match `npx skills`. The table lists common examples; other listed agents work the same.

On Windows, ~ is %USERPROFILE%. Resolve Agent Skill Path once per session. Invoke scripts with absolute paths via python (or python3 if that is what is on PATH). Keep the process CWD in the IDE project (do not cd into the skill folder). Direct invocations: Trace Tree OPs. On PowerShell, also see Windows PowerShell.

Trace Tree OPs

All skill script calls. Substitute the absolute Agent Skill Path for THIS agent. Keep the process CWD in the IDE project (do not cd into the skill folder). On PowerShell, see Windows PowerShell.

• resolve_storage.py
• create_tree.py
• trace_tree.py
• request_refresh.py
• request_refresh_profile.py
• request_refresh_settings.py
• select_trace_points.py

resolve_storage.py

Resolve the project id and bound global XML. If storage is missing, create it (Case C). If .idea/code-trace-tree.project.id exists but XML is gone, recreates XML with that same projectId. Does not create/overwrite the .idea id file. Mutating create_tree and trace_tree add / ensure / move / delete / rename / rebind also create storage automatically. trace_tree search does not auto-create.

Usage

python "<Agent Skill Path>/code-trace-tree/scripts/resolve_storage.py" [project_path]

Optional Parameters:

• [project_path]: Path used to discover the IDE project root (default: CWD). Pass the project root so XML <path> is correct.

Return value

Stdout is JSON (indent=2, UTF-8). Errors print ERROR: … on stderr.

{
  "created": false,
  "project_root": "<abs>",
  "global_dir": "<OS Config Dir>/code-trace-tree",
  "project_id": "<uuid or null>",
  "storage_xml": "<abs xml path>"
}

created is true when a new XML was written. Exit 0 on success; 1 if the project root cannot be found.

Example:

python "<Agent Skill Path>/code-trace-tree/scripts/resolve_storage.py"
python "<Agent Skill Path>/code-trace-tree/scripts/resolve_storage.py" /path/to/project

create_tree.py

Create a nested trace-point tree in one call. Ensures only the payload roots (and children of roots that already exist). Once a node is created, its descendants are added (no per-child ensure). Do not search if not needed — this script already ensures existing nodes. Use search when you need ids (select/move/delete/rename) or to inspect. LINE locators are the same as trace_tree.py (file + line + content). Ignore line-content occurrence (occurrenceIndex / totalOccurrences) — the script calculates it. Prefer --tree-file on PowerShell.

Optional --parent-id attaches the payload under an existing node (that parent is resolved, not ensured).

Usage

python "<Agent Skill Path>/code-trace-tree/scripts/create_tree.py" --tree-file tree.json
python "<Agent Skill Path>/code-trace-tree/scripts/create_tree.py" tree.json
python "<Agent Skill Path>/code-trace-tree/scripts/create_tree.py" --tree '<json>'

Required Parameters (exactly one tree source):

• --tree-file <path>: JSON file (- = stdin). Prefer this over --tree.
• --tree <json>: JSON string.
• Positional <path>: same as --tree-file.

Parameters (shared; all optional):

• --project <path>: Project path (default: CWD).
• --profile <name>: Profile name override (default: <activeProfileName>).
• --dry-run: Do not write XML or refresh.
• --no-refresh: Skip the IDE refresh signal.
• --parent-id <uuid>: Existing parent; repeat rootward → immediate parent. Omit for profile root.
• --parent <json>: Existing parent path JSON (do not combine with --parent-id).

Tree JSON (one node object, or an array of node objects). Every node uses the same shape, including children (description on every node, not only the root):

{
  "file": "src/A.java",
  "line": 10,
  "content": "void methodA() {",
  "name": "methodA",
  "description": "",
  "type": "LINE",
  "children": [
    {
      "file": "src/B.java",
      "line": 40,
      "content": "void methodB() {",
      "name": "methodB",
      "description": "",
      "type": "LINE",
      "children": [
        {
          "file": "src/C.java",
          "line": 20,
          "content": "void methodC() {",
          "name": "methodC",
          "description": "",
          "type": "LINE"
        },
        {
          "type": "FILE",
          "file": "src/Util.java",
          "name": "Util",
          "description": ""
        }
      ]
    }
  ]
}

Fields (every node, including children): file (required); type (LINE | FILE | DIRECTORY; omit to infer: line/content → LINE, else path on disk); LINE needs line + content; name / description / children optional. Do not include occurrenceIndex / totalOccurrences. children is an array of the same objects.

Return value

Stdout is JSON (indent=2, UTF-8). skipped: true on a node means ensure found it; that node's children are still ensured. created: true means add; descendants of that node were added without ensure.

{
  "action": "create_tree",
  "profile": "<profile-name>",
  "storage_xml": "<abs>",
  "parentId": "<uuid or empty>",
  "created": 3,
  "skipped": 1,
  "ids": ["<uuid>", …],
  "roots": [ { "skipped": false, "created": true, "node": <node-object>, "children": [ … ] } ],
  "refreshed": true
}

Exit 0 on success.

Example:

python "<Agent Skill Path>/code-trace-tree/scripts/create_tree.py" --tree-file tree.json
python "<Agent Skill Path>/code-trace-tree/scripts/create_tree.py" --parent-id "$PARENT_ID" --tree-file tree.json

trace_tree.py

Search, add, ensure, move, delete, rename, and rebind nodes. Ignore line-content occurrence (occurrenceIndex / totalOccurrences) — never pass those fields; the script calculates them.

Usage

python "<Agent Skill Path>/code-trace-tree/scripts/trace_tree.py" <subcommand> [flags…]
python "<Agent Skill Path>/code-trace-tree/scripts/trace_tree.py" [shared-flags] <subcommand> [flags…]

Shared flags (--project, --profile, --dry-run, --no-refresh) may appear before or after the subcommand. Omit --project when CWD is already inside the IDE project (scripts walk upward to find .vscode / .idea / .git, or other common project markers). Default profile: <activeProfileName>.

LINE locators: stored tip is [file, line, full-trimmed-line]. --line is required. The script checks the trimmed text at that line, stores the full trimmed line (a substring --content is expanded), then sets occurrenceIndex / totalOccurrences by scanning the file. Duplicate trimmed lines in one file are distinct because --line picks which copy. Ignore occurrence: do not read, pass, or compute occurrenceIndex / totalOccurrences. On PowerShell, protect quoted --content with --% (see Windows PowerShell) or use a substring tip plus --line. Never wrap the CLI in a helper that uses a parameter named $Args.

add vs ensure: add always creates a new UUID (same as the IDE plugin). Use it for a second node on the same line with a different label or parent. ensure is get-or-create: same identity → "skipped": true (exit 0). For LINE, identity is file + trimmed lineContent + the copy selected by --line (the script stores occurrence; do not pass it). FILE/DIRECTORY identity is path + type. --trace-name, description, and parent are not identity.

Generating a tree: prefer create_tree.py. Do not search if not needed — the script ensures existing nodes and adds new subtrees. Use search when you need ids for select/move/delete/rename or to inspect. For a single node, use ensure (get-or-create; no search required) or add (always a new UUID).

Parent path: prefer repeated --parent-id from rootward ancestor → immediate parent. Omit for root on add / ensure. Do not combine --parent-id with --parent. Bare strings inside --parent JSON are UUIDs only, not traceName labels.

method A def
  method B call
    method C call   ← add (or ensure if B already existed) with --parent-id idA --parent-id idB

Rebind after disk edits: Agents do not edit through the IDE editor, so live line shifting does not apply. After any turn that modified project source, run rebind (optionally --file for touched paths) before relying on locators or select/navigate. Rebind repairs lineNumber from trimmed lineContent and recomputes occurrences. The "invalid" array means those LINE locators were not found — leave those nodes in the tree; do not delete them unless the user asked to remove them.

For many mutating calls, use --no-refresh on each, then one request_refresh.py at the end.

Required Subcommand:

• <subcommand>: search | add | ensure | move | delete | rename | rebind