skills.rest
Lingtai-AI
Lingtai-AIOFFICIAL
Explore all skills by this author →
GitHub

dev-guide-debug-troubleshoot

Diagnose and recover LingTai agent process, memory, mail, and tool failures.

692|60|Updated Mar 15, 2026
Search Tags:#escalation#Troubleshooting#agent debugging#heartbeat#mail delivery#lingtai#memory recovery
One-click install
npx skills add https://github.com/Lingtai-AI/lingtai --skill dev-guide-debug-troubleshoot
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: dev-guide-debug-troubleshoot
Source: https://github.com/Lingtai-AI/lingtai/tree/main/tui/internal/preset/skills/lingtai-dev-guide/reference/debug-troubleshoot
Command: npx skills add https://github.com/Lingtai-AI/lingtai --skill dev-guide-debug-troubleshoot

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

Long-lived LingTai agents can become unresponsive, crash, lose memory after a molt, fail to deliver mail, or hit tool timeouts, and this reference provides a structured decision tree and recovery procedures for each failure class.

Core Features & Use Cases

  • Process Diagnosis: Identify whether a peer is busy, stuck, asleep, or suspended using heartbeat files, then interrupt or revive it with system tools.
  • Memory Recovery: Restore working state after a molt by reloading pad, codex, and lingtai layers, and follow a prioritized checklist when context is nearly full.
  • Communication & Tool Fixes: Resolve pigeon delivery failures, bounced addresses, broken schedules, tool timeouts, missing MCP tools, and truncated output.
  • Use Case: A spawned avatar never appears and the parent stops responding; use the network health-check script to scan all heartbeats, find the stale process, and escalate with evidence to the parent.

Quick Start

Ask the agent to diagnose why a LingTai peer is unresponsive and walk through the recovery steps for its state.

Frequently Asked Questions about dev-guide-debug-troubleshoot

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I check if a LingTai agent is alive or crashed?▼

Check the agent's heartbeat file at .lingtai/<name>/.agent.heartbeat. A timestamp under 5 minutes old means it is busy, a stale one means stuck or crashed, and a missing file means no agent runs at that address.

How to recover LingTai agent memory after a molt?▼

Reload layers in order: psyche(pad, load), codex(filter), psyche(lingtai, load), then email(check). If the pad is empty, rebuild it by exporting codex entries and appending them with psyche(pad, edit).

Why is my LingTai pigeon message not delivered?▼

Delivery fails when the address contains @ (routing to IMAP instead of internal mail), send is used instead of reply, the recipient directory is misspelled, or the recipient is suspended. Verify with email(check, folder=sent) and the recipient's inbox directory.

What is the difference between asleep and suspended LingTai agents?▼

Asleep agents still run their heartbeat and listener, so incoming email wakes them. Suspended agents have a dead process and require system(cpr) with karma privileges before they can process any mail.

Why does a LingTai tool call time out or truncate output?▼

The default 30-second bash timeout kills long tasks, and single reads of large files hit return limits. Raise the timeout parameter, redirect long output to a file, and read it back in offset/limit chunks.

Related Skills

Explore More Software Engineering Skills→
Lingtai-AILingtai-AI
621

tutorial-guide

Guide learners through a 12-lesson tutorial on Lingtai with live exploration.

Official
Advanced
AX661sAX661s

Self-Analyze

Analyze outputs to identify root causes and create improvement plans.

Community
Advanced
aget-frameworkaget-framework

aget-check-sessions

Monitor sessions directory health by validating structure, file counts, naming, and disk usage.

Official
Basic
FRIKKernFRIKKern
6

doey-respawn-me

Write an atomic respawn request to restart the Claude process with fresh context.

Community
Intermediate