القائمة
Debug agent execution issues. Use when things aren't working, authentication problems, or to understand the subprocess system. Covers logs, environment variables, and common issues.
التثبيت باستخدام Codex أو Claude انسخ هذا Prompt والصقه في Codex أو Claude أو مساعد آخر ليراجع صفحة Skill ويثبّتها لك.
Add Gmail integration to Gandalf. Can be configured as a tool (agent reads/sends emails when requested from WhatsApp) or as a full channel (emails can trigger the agent, schedule tasks, and receive replies). Guides through GCP OAuth setup and implements the integration.
Add voice message transcription to Gandalf using OpenAI's Whisper API. Automatically transcribes WhatsApp voice notes so the agent can read and respond to them.
Add new capabilities or modify Gandalf behavior. Use when user wants to add channels (Telegram, Slack, email input), add integrations, modify the router, or make any other customizations. This is an interactive skill that asks questions to understand what the user wants.
Run initial Gandalf setup. Use when user wants to install dependencies, authenticate WhatsApp, register their main channel, or start the background services. Triggers on "setup", "install", "configure gandalf", or first-time setup requests.
X (Twitter) integration for Gandalf. Post tweets, like, reply, retweet, and quote. Use for setup, testing, or troubleshooting X functionality. Triggers on "setup x", "x integration", "twitter", "post tweet", "tweet".
| name | debug |
| description | Debug agent execution issues. Use when things aren't working, authentication problems, or to understand the subprocess system. Covers logs, environment variables, and common issues. |
This guide covers debugging the native subprocess agent execution system.
The host process spawns dist/agent-runner.js as a subprocess and exchanges data via IPC files in data/ipc/{group}.
| Log | Location | Content |
|---|---|---|
| Main app logs | logs/gandalf.log | Host-side routing, scheduler, process spawning |
| Main app errors | logs/gandalf.error.log | Host-side errors |
| Agent run logs | groups/{folder}/logs/agent-*.log | Per-run input summary, stdout, stderr |
| Claude sessions | ~/.claude/projects/ | Claude Code session history |
Set LOG_LEVEL=debug for verbose output:
# For development
LOG_LEVEL=debug bun run dev
# For launchd service, add to plist EnvironmentVariables:
<key>LOG_LEVEL</key>
<string>debug</string>
Debug level shows:
Check the most recent agent log in groups/{folder}/logs/agent-*.log.
Common causes include:
Invalid API key · Please run /login
Fix: Ensure .env exists with either OAuth token or API key:
cat .env # Should show one of:
# CLAUDE_CODE_OAUTH_TOKEN=sk-ant-oat01-... (subscription)
# ANTHROPIC_API_KEY=sk-ant-api03-... (pay-per-use)
Symptom: Agent run log shows timeout and the process is killed.
Fix: Increase the timeout:
AGENT_TIMEOUT in .envtimeout in data/registered_groups.jsonSymptom: Agent log shows stdout/stderr truncation.
Fix: Increase AGENT_MAX_OUTPUT_SIZE in .env.
Symptom: New session ID every request.
Fix: Confirm data/sessions.json is being updated and that the process has write access to data/.
# Rebuild main app
bun run build
# Restart service
launchctl kickstart -k gui/$(id -u)/com.gandalf