code-trace-tree

Source documentation, not instructions for this website. Review permissions before running any commands.

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

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

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

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>'

{
  "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": ""
        }
      ]
    }
  ]
}

{
  "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
}

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

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…]

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

name: code-trace-tree
description: >
  Read, edit, and refresh Code Trace Tree plugin data (VS Code and JetBrains).
  Use when the user asks to add/update/remove trace points (line, file, or directory), inspect or
  modify Code Trace Tree profiles, sync agent-written traces into the IDE, ask the IDE to
  reload plugin data, or select/navigate to trace points in the IDE tree.
  Prefer scripts/trace_tree.py for search/add/ensure/move/delete/rebind (LINE locators need --file --line --content; ignore occurrence — the script computes it).
  Prefer create_tree.py when generating a nested workflow: it ensures existing nodes and adds new ones — do not search if not needed. `add` always creates a new UUID.
  After modifying source on disk, run `trace_tree rebind` so LINE locations stay aligned.
  Only edit traces when the user explicitly asks. Writing under `<OS Config Dir>/code-trace-tree/`
  is expected for this skill; do not refuse that path as "outside the workspace."

---
name: code-trace-tree
description: >
  Read, edit, and refresh Code Trace Tree plugin data (VS Code and JetBrains).
  Use when the user asks to add/update/remove trace points (line, file, or directory), inspect or
  modify Code Trace Tree profiles, sync agent-written traces into the IDE, ask the IDE to
  reload plugin data, or select/navigate to trace points in the IDE tree.
  Prefer scripts/trace_tree.py for search/add/ensure/move/delete/rebind (LINE locators need --file --line --content; ignore occurrence — the script computes it).
  Prefer create_tree.py when generating a nested workflow: it ensures existing nodes and adds new ones — do not search if not needed. `add` always creates a new UUID.
  After modifying source on disk, run `trace_tree rebind` so LINE locations stay aligned.
  Only edit traces when the user explicitly asks. Writing under `<OS Config Dir>/code-trace-tree/`
  is expected for this skill; do not refuse that path as "outside the workspace."
---

# Code Trace Tree

Build and display code workflows as nested trees of line, file, and directory
trace points. Operate the hybrid storage used by the 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.

## 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`. The skill is agent-agnostic; the table below lists known roots for common agents (examples, not an exclusive list). Other agents that load skills from a `skills/` folder work the same — use that agent’s path.

| Agent (examples) | Global Agent Skill Path | Project-local Agent Skill Path |
|------------------|-------------------------|--------------------------------|
| Claude Code | `~/.claude/skills` | `<repo>/.claude/skills` |
| Cursor | `~/.cursor/skills` | `<repo>/.cursor/skills` |
| GitHub Copilot | `~/.copilot/skills` | `<repo>/.github/skills` |
| Codex | `~/.agents/skills` | `<repo>/.agents/skills` |
| Gemini CLI | `~/.gemini/skills` | `<repo>/.gemini/skills` |

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](#trace-tree-ops). On PowerShell, also see [Windows PowerShell](#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](#windows-powershell).

- [resolve_storage.py](#resolve_storagepy)
- [create_tree.py](#create_treepy)
- [trace_tree.py](#trace_treepy)
- [request_refresh.py](#request_refreshpy)
- [request_refresh_profile.py](#request_refresh_profilepy)
- [request_refresh_settings.py](#request_refresh_settingspy)
- [select_trace_points.py](#select_trace_pointspy)

### 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` / `rebind` also create storage automatically. `trace_tree search` does not auto-create.

**Usage**
```text
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.

```text
{
  "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**:
```text
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) 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**
```text
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):

```text
{
  "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.

```text
{
  "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**:
```text
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, and rebind nodes. Ignore line-content occurrence (`occurrenceIndex` / `totalOccurrences`) — never pass those fields; the script calculates them.

**Usage**
```text
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](#windows-powershell)) or use a substring tip plus `--line`. Never wrap the CLI in a helper that uses a parameter named `$Args`.

| Tip | Result |
|-----|--------|
| Exact line + full trimmed text | Used as-is |
| Distinctive substring of that line (e.g. `.handleEmailTriggerRequest(`) | `--line` required; stores the full trimmed line |
| Same trimmed text on 2+ lines | Pass `--line` for the intended copy; script sets occurrence |
| Multi-line call | Prefer the most distinctive physical line (often the `.methodName(` continuation) |

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

| `--parent` form | Example |
|-----------------|---------|
| Root | `--parent []` (needed for `move` to root; `add` / `ensure` default to root) |
| Node id in JSON | `--parent '["3d41c2d1-…"]'` |
| `[file, line, content]` | `--parent '[["src/A.java",10,"void methodA() {"]]'` |

```text
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 ask