Skip to main content
skill CX Codex

lynx-debug-info-remapping — Claude Code skill: install

lynx-debug-info-remapping maps Lynx function_id:pc_index error locations back to source lines with debug-info.json. Use it when a main-thread stack points into bytecode.

Apache-2.0 325 installs ★ 28 updated 2026-11-22

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add lynx-community/skills --skill lynx-debug-info-remapping -a claude-code
Open on GitHub

What lynx-debug-info-remapping does

This skill reads Lynx main-thread stack traces, extracts function_id:pc_index pairs, and maps them to source line:column positions. It uses the external debug-info.json file and can return a stack trace with replaced coordinates and nearby source context.

The package includes scripts/index.mjs. The script runs with node and takes the debug-info path, function_id, and pc_index as arguments. In an rspeedy project, the relevant files are usually under dist/.rspeedy/main/. If a build has no .rspeedy directory, run DEBUG='rspeedy,rsbuild' rspeedy build first. Background-thread stacks do not need this remapping, so the skill is for main-thread backtraces.

What it helps with

  • map function_id:pc_index to a source line
  • decode an error from main-thread.js
  • turn a Lynx stack into source coordinates
  • produce a clickable remapped stack trace
  • locate an error through debug-info.json

Example prompts for the agent

  • Decode this main-thread backtrace and map every position with debug-info.json.
  • Use dist/.rspeedy/main/debug-info.json to resolve 1356:13.
  • Show the updated stack with source context from main-thread.js.

How to install lynx-debug-info-remapping

1Skills CLI (Vercel)

npx skills add lynx-community/skills --skill lynx-debug-info-remapping -a claude-code

2Manually: put the files in place

~/.claude/skills/lynx-debug-info-remapping/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/lynx-debug-info-remapping/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about lynx-debug-info-remapping

How do I install lynx-debug-info-remapping in Claude Code?

Run npx skills add lynx-community/skills --skill lynx-debug-info-remapping -a claude-code, then check ~/.claude/skills/lynx-debug-info-remapping/SKILL.md.

What does lynx-debug-info-remapping do?

It converts Lynx function_id:pc_index locations from a main-thread stack into source coordinates using debug-info.json. It can also present the stack with the mapped positions.

What is required to decode a Lynx error?

Provide the error location or full backtrace and the path to debug-info.json. If rspeedy build produced no .rspeedy directory, run DEBUG='rspeedy,rsbuild' rspeedy build.

Source text

SKILL.md · Apache-2.0
---
name: lynx-debug-info-remapping
description: Remap the function_id:pc_index to the original source code position by provided debug info json file.
---

# Debug Info Remapping

## Description

In Lynx, main thread script is encoded to bytecode and uses an external debugging information scheme. Under this scheme, the row and column numbers in the runtime error messages are not the actual row and column numbers. The row and column numbers need to be deciphered from the external `debug-info.json` file.

debug-info.json format is as follows:

```json
{
  "lepusNG_debug_info": {
    "function_info": [
      {
        "function_id": 1,
        "function_name": "App",
        "line_col": [
          { "line": 1, "column": 1 },
          { "line": 2, "column": 1 },
          { "line": 3, "column": 1 }
        ]
      }
    ]
  }
}
```

## When to Apply

This skill is useful when you want to remap the `function_id:pc_index` to the original source code position.

When the user encounters a runtime error message with function_id:pc_index, along with `main-thread.js` and `debug-info.json` in the error message, for example:

```
main-thread.js exception: App render failed at main thread backtrace:
    at App (file:///main-thread.js:1356:13)
    at doRender (file:///main-thread.js:1002:12)
    at call (native)
    at render (file:///main-thread.js:466:52)
    at _renderToString (file:///main-thread.js:1001:569)
    at renderToString (file:///main-thread.js:998:191)
    at renderMainThread (file:///main-thread.js:766:45)
    at renderPage (file:///main-thread.js:853:69)
```

Where `function_id:pc_index` is `1356:13`.

## Workflow

### 1. Ask the User for the `function_id:pc_index`

User should provide the `function_id:pc_index` in the error message. Or give you the full backtrace.

You should check if it is a main-thread backtrace. Since background thread backtrace does not need remapping.

### 2. Find the Corresponding Position in debug-info.json

Ask the user for the `debug-info.json` path. For example in a rspeedy project with `main` entry it will locate at:

- `main-thread.js`: `$PROJECT_DIR/dist/.rspeedy/main/main-thread.js`
- `debug-info.json`: `$PROJECT_DIR/dist/.rspeedy/main/debug-info.json`

If the user uses `rspeedy build` and there is no `.rspeedy` folder, remind them to build the project with `DEBUG='rspeedy,rsbuild' rspeedy build`.

### 3. Run the remapping script

Set `SKILL_DIR` to the directory containing this `SKILL.md` and `DEBUG_INFO` to the path of `debug-info.json`. Run the bundled script for each `function_id:pc_index` pair.

```bash
node "$SKILL_DIR/scripts/index.mjs" "$DEBUG_INFO" "$function_id" "$pc_index"
```

### 4. Output the Remapped Position

The remapping script will output the remapped position in the format of `line:column`.

You should output the remapped position for each `function_id:pc_index` pair.

Replace the `function_id:pc_index` pair in the stack trace with the remapped position and show the remapped stack trace.

### 5. Show the Remapped Stack Trace

If you can reach the `main-thread.js` file, show the remapped stack trace with the remapped positions source code.

The final output should be something like this:

```log
main-thread.js exception: App render failed at main thread backtrace:
    at App (./dist/.rspeedy/main/main-thread.js:9368:56)
    at doRender (./dist/.rspeedy/main/main-thread.js:7237:44)
    at call (native)
    at render (./dist/.rspeedy/main/main-thread.js:3706:72)
    at _renderToString (./dist/.rspeedy/main/main-thread.js:7177:78)
    at renderToString (./dist/.rspeedy/main/main-thread.js:7067:91)
    at renderMainThread (./dist/.rspeedy/main/main-thread.js:5423:113)
    at renderPage (./dist/.rspeedy/main/main-thread.js:6199:46)

   ╭─[5:55]
 3 │ export function App() {
 4 │   if (__MAIN_THREAD__) {
 5 │     throw new Error('App render failed at main thread');
   ·                                                      ─┬
   ·                                                       ╰── main-thread.js exception: App render failed at main thread backtrace
 6 │   }
 7 │
   ╰────

   ... (the same for other callstacks such as doRender, call, render, _renderToString, renderToString, renderMainThread, renderPage here)

Files used:

  - Debug Info: ./dist/.rspeedy/main/debug-info.json
  - Source File: ./dist/.rspeedy/main/main-thread.js
```

The `./dist/.rspeedy/main/main-thread.js:9368:56` will make sure it is clickable in the editor/terminal.

© lynx-community · Apache-2.0 · lynx-community/skills

Similar skills

All skills for Agent setup: memory, context, orchestration →

From the same set14

The whole set →
lynx-typescript lynx-typescript configures TypeScript for Lynx and ReactLynx projects, providing patterns for event types, global properties, and custom native components. CX Codex +1 459installs lynx-trace-analysis lynx-trace-analysis — a skill for Claude Code, Cursor, Codex and other agents that brings Lynx trace expertise into the conversation. Covers startup metrics (FCP, FMP, TTI), frame drops, render pipeline bottlenecks, and memory leaks. CX Codex +1 400installs lynx-trace-record lynx-trace-record teaches AI agents to record Lynx performance traces via the trace_record CLI. Captures startup rendering, memory snapshots, and JS engine profiles. CX Codex +1 388installs lynx-ui A skill for building with lynx-ui: it picks the component, checks the public API in the repo's reference files and keeps the agent from inventing props. CX Codex +1 326installs habitat-usage habitat-usage — a skill for Claude Code, Codex, Cursor and other platforms that configures Habitat to sync multi-repo dependencies and external assets via .habitat/DEPS and hab sync. CX Codex +1 253installs lynx-check-css-support lynx-check-css-support is a Claude Code skill that checks CSS property and value support across Lynx backends using bundled data. CX Codex +1 201installs vanilla-lynx vanilla-lynx is a Claude Code skill that writes, reviews, and explains Vanilla Lynx code using Element PAPI. It targets build-free .lynxml files or Rspeedy application projects. CX Codex +1 201installs lynx-api-docs lynx-api-docs — a skill for Claude Code and Codex that routes Lynx engine docs during TSX or TTML development. Prevents AI from assuming browser defaults. CX Codex +1 183installs

Project sponsors

Companies that keep this analytics open