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
npx skills add lynx-community/skills --skill lynx-debug-info-remapping -a claude-codeWhat 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_indexto 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.jsonto resolve1356: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-code2Manually: put the files in place
~/.claude/skills/lynx-debug-info-remapping/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/lynx-debug-info-remapping/
1Skills CLI (Vercel)
npx skills add lynx-community/skills --skill lynx-debug-info-remapping -a codex2Manually: put the files in place
.agents/skills/lynx-debug-info-remapping/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add lynx-community/skills --skill lynx-debug-info-remapping -a cursor2Manually: put the files in place
.cursor/skills/lynx-debug-info-remapping/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install lynx-community/skills skills/lynx-debug-info-remapping2Manually: put the files in place
.github/skills/lynx-debug-info-remapping/SKILL.md1Skills CLI (Vercel)
npx skills add lynx-community/skills --skill lynx-debug-info-remapping -a gemini-cli2Platform CLI
gemini skills install https://github.com/lynx-community/skills --path skills/lynx-debug-info-remappingManually: put the files in place
.devin/skills/lynx-debug-info-remapping/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add lynx-community/skills --skill lynx-debug-info-remapping -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
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