debug

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.

Gandalf Debugging

This guide covers debugging the native subprocess agent execution system.

Architecture Overview

The host process spawns dist/agent-runner.js as a subprocess and exchanges data via IPC files in data/ipc/{group}.

Log Locations

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

Enabling Debug Logging

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:

• Agent input summaries
• Subprocess stdout/stderr
• IPC task handling

Common Issues

1. "Claude Code process exited with code 1"