daemon-debug
Skill22 starsChanged 11 months agoApache-2.0View on GitHub
Diagnose autostart, proxy, and process issues — why things aren't starting, connecting, or recovering
In this repository7 other files it gives its agents.
- AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- daemon-health-checkSkill
- flake-triageSkill
- messaging-queueSkill
- searchSkill
- security-boundary-reviewSkill
The file
We split this skill into the rules it gives an agent
7 rules. About 0 are common, 3 are distinctive, and 4 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈3
Distinctive · estimate
This author's own choices. Worth a look.
4
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 8
Use this skill when diagnosing why processes aren't starting, proxies are missing, ports are occupied, or the autostart flow isn't working.
- Very specific: line 29
Do running processes have urls populated?
- Very specific: line 56
How to test: Check process output for the URL line, then verify the matcher pattern (with {url} removed) matches as a regex substring.
- Distinctive: line 69
If URL was detected but proxy wasn't created:
- Very specific: line 112
If it doesn't, next session's Register returns stale entries via LoadOrStore
- Distinctive: line 133
When debugging on WSL:
- Very specific: line 137
Use platform.ShouldUseWindowsShell(path) to determine which side owns the process
≈ “Common” is an estimate: at least 1 in 5 of the 372,429 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
Daemon Debugging
Use this skill when diagnosing why processes aren't starting, proxies are missing, ports are occupied, or the autostart flow isn't working.
Diagnostic Checklist
Work through these in order. Each step either finds the problem or rules out a category.
1. Verify Daemon State
# Is the daemon running?
agnt daemon status
# What processes does the daemon know about?
printf 'PROC LIST\n;;\n' | socat - UNIX-CONNECT:/tmp/devtool-mcp-$(id -u).sock
# What proxies exist?
printf 'PROXY LIST\n;;\n' | socat - UNIX-CONNECT:/tmp/devtool-mcp-$(id -u).sockDecode base64 JSON responses. Check:
- Are expected processes listed?
- What state are they in? (running / failed / etc.)
- Do running processes have
urlspopulated? - Are any warnings present (rogue processes)?
2. Check Config
# Read the project config
cat /path/to/project/.agnt.kdlFor each proxy with script set:
- Does the linked script exist in
scripts {}? - Does the script have
url-matchers? Do they match actual output format? - Does the proxy have
fallback-port? (safety net if URL detection fails)
3. Verify URL Detection
URL detection is the #1 failure point for script-linked proxies.
Common URL matcher mismatches:
| Dev server | Actual output | Correct matcher |
| dotnet | Now listening on: http://localhost:6111 | "Now listening on: {url}" |
| Vite | Local: http://localhost:5173/ | "Local:\\s+{url}" |
| Next.js | - Local: http://localhost:3000 | "Local:\\s+{url}" |
| Flask | Running on http://127.0.0.1:5000 | "Running on {url}" |
How to test: Check process output for the URL line, then verify the matcher pattern (with {url} removed) matches as a regex substring.
4. Check Port Bindings
# Linux: what's listening on expected ports?
ss -tlnp | grep -E ':(6111|6112|3000|5173)\b'
# Compare against daemon's tracked processes
# If port is occupied by a PID the daemon doesn't own → rogue process5. Check Event System
If URL was detected but proxy wasn't created:
- Was the
proxyEventschannel full? (Check daemon debug log for "channel full" warnings) - Did
handleURLDetectedfind the matching proxy config? (Check for "Proxy X matches script Y" in debug log) - Was the proxy already created under a different ID? (Event-driven IDs include host-port suffix)
6. Check Session Log
The session log (the startup output the developer sees) should show:
[starting]/[started]for each script[proxy_starting]/[proxy_started]for each proxy[dependency_ready]or[dependency_wait]for dependencies
Missing entries indicate the step was silently skipped.
Common Failure Modes
Proxy Never Created
Symptoms: Process running, no proxy in PROXY LIST
Causes:
- URL matcher doesn't match actual output → fix matcher in
.agnt.kdl - No
fallback-portconfigured → add it as safety net - Event channel was full → health check should catch this
- Process started but URL was in first output batch that was scanned before URLTracker was wired up
Rogue Process on Port
Symptoms: Process shows as "failed" but port is in use by unmanaged PID Causes:
- Previous run wasn't cleaned up (daemon restart, crash)
- Another tool started on the same port
Fix:
proc {action: "restart", process_id: "..."}kills rogue and restarts
Process "Failed" But Actually Compiling
Symptoms: Process killed during long compilation Root cause: Stall detection misidentified compilation output as stall Fix: Error output IS activity — AlertScanner classifications must reset stall timer
Stale Status Bar Indicators
Symptoms: Status bar shows indicators for scripts that were removed from .agnt.kdl
Root cause: Script registry entries survived session disconnect
How it happens:
- Session 1 starts 3 scripts → 3 registry entries
- User exits (session disconnects)
CleanupSessionResourcesmust remove ALL registry entries for the project- If it doesn't, next session's
Registerreturns stale entries viaLoadOrStore - Status bar renders indicators for all registry entries, not just current config
Diagnosis:
# Check script registry vs config
printf 'SCRIPT LIST\n;;\n' | socat - UNIX-CONNECT:/tmp/devtool-mcp-$(id -u).sock
# Compare count against scripts in .agnt.kdlFix: The registry is ephemeral — rebuilt from .agnt.kdl each session. CleanupSessionResources removes entries when the last session disconnects. If stale entries appear, check that cleanup is running (look for "cleared script registry" in debug log).
Multiple Autostart Cycles
Symptoms: Session log shows autostart running twice for same project Causes:
- Session reconnection triggered re-autostart
- Multiple clients connecting to same daemon Impact: Second cycle may fail if ports already bound by first cycle's processes
Cross-Platform Notes
When debugging on WSL:
runtime.GOOSis"linux"— useplatform.IsWSL()instead- Processes may be Linux-side or Windows-side depending on project path
- Port checks may need both
ss(Linux) andnetstat.exe(Windows) - Use
platform.ShouldUseWindowsShell(path)to determine which side owns the process
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.

