agentleFS
standardbeaglestandardbeagle/agnt/.claude/skills/daemon-debug/SKILL.md

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

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
  1. Distinctive:

    Use this skill when diagnosing why processes aren't starting, proxies are missing, ports are occupied, or the autostart flow isn't working.

    line 8
  2. Very specific:

    Do running processes have urls populated?

    line 29
  3. Very specific:

    How to test: Check process output for the URL line, then verify the matcher pattern (with {url} removed) matches as a regex substring.

    line 56
  4. Distinctive:

    If URL was detected but proxy wasn't created:

    line 69
  5. Very specific:

    If it doesn't, next session's Register returns stale entries via LoadOrStore

    line 112
  6. Distinctive:

    When debugging on WSL:

    line 133
  7. Very specific:

    Use platform.ShouldUseWindowsShell(path) to determine which side owns the process

    line 137

≈ “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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

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).sock

Decode base64 JSON responses. Check:

  • Are expected processes listed?
  • What state are they in? (running / failed / etc.)
  • Do running processes have urls populated?
  • Are any warnings present (rogue processes)?

2. Check Config

# Read the project config
cat /path/to/project/.agnt.kdl

For 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 serverActual outputCorrect matcher
dotnetNow listening on: http://localhost:6111"Now listening on: {url}"
ViteLocal: http://localhost:5173/"Local:\\s+{url}"
Next.js- Local: http://localhost:3000"Local:\\s+{url}"
FlaskRunning 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 process

5. Check Event System

If URL was detected but proxy wasn't created:

  • Was the proxyEvents channel full? (Check daemon debug log for "channel full" warnings)
  • Did handleURLDetected find 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:

  1. URL matcher doesn't match actual output → fix matcher in .agnt.kdl
  2. No fallback-port configured → add it as safety net
  3. Event channel was full → health check should catch this
  4. 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:

  1. Previous run wasn't cleaned up (daemon restart, crash)
  2. 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:

  1. Session 1 starts 3 scripts → 3 registry entries
  2. User exits (session disconnects)
  3. CleanupSessionResources must remove ALL registry entries for the project
  4. If it doesn't, next session's Register returns stale entries via LoadOrStore
  5. 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.kdl

Fix: 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:

  1. Session reconnection triggered re-autostart
  2. 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.GOOS is "linux" — use platform.IsWSL() instead
  • Processes may be Linux-side or Windows-side depending on project path
  • Port checks may need both ss (Linux) and netstat.exe (Windows)
  • Use platform.ShouldUseWindowsShell(path) to determine which side owns the process

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.