debug-extension
Skill5 starsChanged 22 days agoMITView on GitHub
Debug and troubleshoot the Agntree VS Code extension. Use when there are errors, the extension isn't working, or when investigating issues.
- Reads credentials
1 other project uses a version of this.
Adopted by
Most recently taken up by
- microsoft/power-platform-skillstheir own version, first seen Oct 13, 2026
Other versions1 project uses a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 1
- microsoft/power-platform-skills★ 1.2ksame name
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository4 other files it gives its agents.
- AGENTS.mdAGENTS.md
- add-featureSkill
- build-extensionSkill
- inspect-runtime-stateSkill
The file
Show its rules and text
We split this skill into the rules it gives an agent
20 rules. About 0 are common, 10 are distinctive, and 10 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈10
Distinctive · estimate
This author's own choices. Worth a look.
10
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 22
Look for TypeScript errors in the output.
- Distinctive: line 28
Run "Developer: Show Logs"
- Very specific: line 39
Check package.json activation events:
- Distinctive: line 44
Verify the extension is installed:
- Very specific: line 51
Check command is defined in package.json under contributes.commands
- Very specific: line 52
Verify menu entries have correct when clauses
- Very specific: line 53
Ensure contextValue matches the menu filter
- Distinctive: line 57
Check if repositories are stored in globalState
- Very specific: line 58
Verify getChildren() is returning items
- Distinctive: line 59
Look for errors in Extension Host logs
- Distinctive: line 63
Verify worktree path is correct
- Distinctive: line 64
Check if file patterns are matching
- Distinctive: line 65
Look for watcher disposal issues
- Distinctive: line 69
Ensure Git extension is enabled in VS Code
- Distinctive: line 70
Check if the file is tracked by git
- Very specific: line 71
Verify git.openChange command is available
- Very specific: line 75
Use this when the symptom depends on VS Code's own host state rather than on Agntree's logic: terminals restored after Reload Window versus …
- Very specific: line 201
Write user-data/User/settings.json before the first launch:
- Very specific: line 264
State writes are not flushed on demand: If you copy state.vscdb without the -wal file you can read an older value even though memory holds …
- Very specific: line 271
Never target the real profile: Use a throwaway --user-data-dir.
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Debug Extension
Troubleshoot issues with the Agntree VS Code extension.
Check Compilation Errors
# From the repository root
npm run compileLook for TypeScript errors in the output.
View Extension Logs
In VS Code:
- Open Command Palette (Cmd+Shift+P)
- Run "Developer: Show Logs"
- Select "Extension Host" from the dropdown
Or check the Output panel:
- View > Output
- Select "Extension Host" or "Agntree"
Common Issues
Extension Not Activating
Check package.json activation events:
"activationEvents": ["onStartupFinished"]Verify the extension is installed:
code --list-extensions | grep agntreeCommands Not Appearing
- Check command is defined in
package.jsonundercontributes.commands - Verify menu entries have correct
whenclauses - Ensure
contextValuematches the menu filter
Tree View Empty
- Check if repositories are stored in globalState
- Verify
getChildren()is returning items - Look for errors in Extension Host logs
File Watcher Not Working
- Verify worktree path is correct
- Check if file patterns are matching
- Look for watcher disposal issues
Git Diff Not Opening
- Ensure Git extension is enabled in VS Code
- Check if the file is tracked by git
- Verify
git.openChangecommand is available
Probe the Real Window
Use this when the symptom depends on VS Code's own host state rather than on Agntree's logic: terminals restored after Reload Window versus quit/reopen, title persistence, activation order, or anything that only reproduces in a real window. Stubs and unit tests cannot show what the workbench restores.
The pattern is a throwaway driver extension plus a runner that drives the real VS Code with an isolated profile. One launch runs one stage; a state file sequences the stages so a quit/reopen can be tested as separate processes.
Layout
/tmp/agntree-probe/
repo/ # workspace folder the probe opens
driver/ # one-file extension loaded with --extensionDevelopmentPath
package.json
extension.js
user-data/ # isolated --user-data-dir (throwaway, created by the runner)
extensions/ # isolated --extensions-dir; the installed Agntree goes here
fake-claude.sh # fake harness CLI: logs args, then sleeps
run.js # seed state, launch each stage, dump state
state.json # stage marker, survives process restarts
log.jsonl # driver log1. Load the build under test
mkdir -p /tmp/agntree-probe/user-data/extensions
EXT=$(ls -d ~/.vscode/extensions/subhashkhileri.agntree-* | tail -1)
cp -R "$EXT" /tmp/agntree-probe/user-data/extensions/agntreeThe runner recreates user-data/extensions before each run so a stale copy never hides a
freshly installed build. Never point --user-data-dir at the real profile; the probe writes
settings, seeds state, and opens windows.
2. Driver skeleton
driver/package.json:
{
"name": "agntree-probe-driver",
"publisher": "probe",
"version": "0.0.1",
"engines": { "vscode": "^1.90.0" },
"main": "./extension.js",
"activationEvents": ["onStartupFinished"]
}driver/extension.js — each launch performs one stage, then quits:
const vscode = require('vscode');
const fs = require('fs');
const OUT = process.env.PROBE_OUT;
const STATE = process.env.PROBE_STATE;
const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
const log = (entry) => fs.appendFileSync(OUT, JSON.stringify({ at: Date.now(), ...entry }) + '\n');
const readState = () => { try { return JSON.parse(fs.readFileSync(STATE, 'utf8')); } catch { return { stage: 0 }; } };
const writeState = (state) => fs.writeFileSync(STATE, JSON.stringify(state));
exports.activate = async () => {
const state = readState();
log({ kind: 'activate', stage: state.stage });
const chats = JSON.parse(process.env.PROBE_CHATS);
if (state.stage === 0) {
await sleep(3000); // let Agntree finish activating
for (const chat of chats) {
const item = { itemType: 'chat', label: chat.name, collapsibleState: 0, data: chat };
await vscode.commands.executeCommand('agntree.openChat', item);
}
await sleep(2500);
const terms = await Promise.all(
vscode.window.terminals.map(async (t) => ({
name: t.name,
pid: await t.processId,
exit: t.exitStatus?.code ?? null,
active: t === vscode.window.activeTerminal,
}))
);
log({ kind: 'snapshot', terms });
writeState({ stage: 1 });
await sleep(500);
await vscode.commands.executeCommand('workbench.action.quit'); // not reload
return;
}
if (state.stage === 1) {
await sleep(5000); // activation's background work, then snapshot
const terms = await Promise.all(
vscode.window.terminals.map(async (t) => ({ name: t.name, pid: await t.processId }))
);
log({ kind: 'snapshot', terms });
writeState({ stage: 2 });
await vscode.commands.executeCommand('workbench.action.quit');
}
};Drive the extension through its public commands (agntree.openChat, agntree.newClaudeChat,
…) and snapshot only public surfaces (window.terminals, activeTerminal, chat rows in
state). Do not import out/extension.js.
3. Launch command
CODE="/Applications/Visual Studio Code.app/Contents/MacOS/Code"
PROBE=/tmp/agntree-probe
"$CODE" \
--user-data-dir="$PROBE/user-data" \
--extensions-dir="$PROBE/user-data/extensions" \
--extensionDevelopmentPath="$PROBE/driver" \
--disable-gpu --skip-welcome --skip-release-notes --disable-workspace-trust \
--new-window "$PROBE/repo"Pass PROBE_OUT, PROBE_STATE, and any scenario data such as PROBE_CHATS in the child
environment. The runner must wait for the process to exit (with a kill timeout, e.g. 180s)
before starting the next stage.
4. Settings and a fake harness
Write user-data/User/settings.json before the first launch:
{
"agntree.harnessCommands.claude": "/tmp/agntree-probe/fake-claude.sh",
"terminal.integrated.enablePersistentSessions": true,
"workbench.startupEditor": "none",
"window.restoreWindows": "none",
"telemetry.telemetryLevel": "off",
"extensions.autoUpdate": false,
"update.mode": "none"
}fake-claude.sh answers --version, appends date pid args to a log, and sleeps, so you can
see exactly which launch and resume commands ran without a real session or model turn. Make
it executable (chmod +x) and keep it out of the repository; it is probe scaffolding.
5. Seed state
Agntree stores one JSON value under the extension id in the global state database. Seed it
with sqlite3 (schema: ItemTable(key TEXT UNIQUE, value BLOB)):
DB="$PROBE/user-data/User/globalStorage/state.vscdb"
sqlite3 "$DB" "INSERT OR REPLACE INTO ItemTable(key, value) VALUES('subhashkhileri.agntree', '<json>');"Escape single quotes in the JSON (value.replace(/'/g, "''")) before embedding it. Read the
stored shape from src/types.ts (STORAGE_KEYS) and seed the minimum: repositories, chats,
active chat, active worktree. Include every field the code path reads; a missing field usually
fails silently. Seed chats with the worktree id Agntree computes for that repository (copy it
from a real state dump or let Agntree add the repository once, then inspect) — a guessed id
makes the tree look empty and the probe misleading. repo/ should be a git repository
(git init), since the worktree and session flows assume one.
6. Inspect after each launch
Copy the databases before opening them and query the copy with immutable=1:
cp "$DB" "$PROBE/db-copy.vscdb"
cp "$DB-wal" "$PROBE/db-copy.vscdb-wal" 2>/dev/null || true
sqlite3 "file:$PROBE/db-copy.vscdb?immutable=1" \
"SELECT value FROM ItemTable WHERE key='subhashkhileri.agntree';"Workspace-scoped state (the editor grid, terminal pty state) lives in a different database:
user-data/User/workspaceStorage/<hash>/state.vscdb
memento/workbench.parts.editor # editor grid, incl. terminal title/titleSource
terminal.integrated.bufferState # pty-side titles, shellLaunchConfig, pidsFor terminal restore bugs, both sides matter: the editor grid's titleSource is what VS
Code restores, while the pty state can still show a different title. Custom titles are
titleSource: 0; 1 process, 2 sequence, 3 config.
Gotchas
- Quit and reload are different. A reload keeps ptys and PIDs; a quit revives each editor terminal as a new shell with a new PID. Test both, and test a quit twice in a row.
- State writes are not flushed on demand. If you copy
state.vscdbwithout the-walfile you can read an older value even though memory holds the new one. Copy the sidecar files or checkpoint before reading; do not diagnose a "lost write" from a stale copy. - Wait for activation, not a fixed startup assumption. The driver's own
activatecan run before Agntree's; open chats only after a short settle or until the command succeeds. - One stage per launch. Writing the stage file before quitting lets the next launch continue the scenario without any IPC beyond the filesystem.
- Never target the real profile. Use a throwaway
--user-data-dir; do not write harness data under~/.claudeor read opencode/Codex internal databases.
Reinstall Extension
# From the repository root
code --uninstall-extension agntree.agntree
npm run compile
npx @vscode/vsce package --allow-missing-repository
code --install-extension agntree-0.1.0.vsixThen reload VS Code window (Cmd+Shift+P > "Developer: Reload Window").
Debug with Breakpoints
- Open the extension project in VS Code
- Press F5 to launch Extension Development Host
- Set breakpoints in TypeScript files
- Interact with extension in the new window
- Breakpoints will trigger in the original window
Check Storage State
For the installed build, extension-host logs, stored chats, and harness session files, follow
the inspect-runtime-state skill. It derives the editor's user-data and extensions
directories at run time instead of assuming a path, and keeps every read read-only.
Reset Extension State
To clear all stored data, run in VS Code developer console:
// Get the extension context and clear globalState
// (requires modifying extension.ts temporarily)Or uninstall and reinstall the extension.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

