How to Debug Craft Agents Using Log Files and CRAFT_DEBUG

Set the CRAFT_DEBUG environment variable to 1 or pass the --debug flag to enable structured logging that writes to both the console and Electron log files (main.log and renderer.log) for comprehensive tracing of agent behavior.

Debugging distributed AI agent systems requires visibility into runtime behavior without modifying source code. The craft-ai-agents/craft-agents-oss repository provides a built-in debugging mechanism controlled by the CRAFT_DEBUG environment variable that routes structured diagnostic messages to both stdout and persistent log files. This system allows developers to trace execution flow across the CLI and Electron desktop interfaces using a unified debug() helper.

How the Debug System Works

The debugging infrastructure centers on a lightweight utility that conditionally enables logging based on environment detection. When activated, the system captures timestamped messages with module prefixes and mirrors them to Electron's logging subsystem.

Core Debug Components

The architecture consists of four interconnected components:

• debug.ts: Located at packages/shared/src/utils/debug.ts, this module exports enableDebug(), isDebugEnabled(), and the debug() logging function. When process.env.CRAFT_DEBUG === '1', the module activates and forwards messages to Electron-log when available.
• Electron-log Shim: The renderer process uses apps/webui/src/shims/electron-log.ts to redirect logging calls to console.log in browser environments, ensuring API compatibility across web and desktop builds.
• Main Process Logger: The Electron main process initializes its logger in apps/electron/src/main/logger.ts, formatting messages and persisting them to main.log.
• CLI Integration: The command-line interface parses the --debug flag in apps/cli/src/index.ts, invoking enableDebug() to activate tracing before any agent code executes.

When debugging is disabled, debug() functions as a no-op, ensuring zero runtime overhead in production environments.

Log File Locations

When running inside Electron, the system mirrors console output to persistent files:

• Main Process: main.log containing backend agent operations and Node.js context logs
• Renderer Process: renderer.log capturing UI-level debug messages from the browser context

On Linux systems, these files reside in ~/.config/CraftAgents/. Both files are automatically created by the electron-log package upon application startup.

Enabling Debug Output

Activate tracing through three methods depending on your execution context.

CLI Flag Method

Pass the --debug flag to any craft-agents command:

craft-agents --debug start

This triggers enableDebug() during CLI initialization in apps/cli/src/index.ts, setting the internal state before your agents begin execution.

Environment Variable Method

Set CRAFT_DEBUG before invoking the binary:

export CRAFT_DEBUG=1
craft-agents start

Windows PowerShell users should use:

$env:CRAFT_DEBUG = "1"
.\craft-agents.exe start

Electron Desktop App Method

Launch the packaged desktop application from a terminal with the environment variable set:

CRAFT_DEBUG=1 ./craft-agents-desktop

The UI process automatically reads process.env.CRAFT_DEBUG and activates the same debug flow, writing output to the log files.

Practical Debugging Workflow

Follow this structured approach to diagnose agent behavior:

1. Enable Tracing: Launch with CRAFT_DEBUG=1 or --debug to activate timestamped logging across all modules.
2. Reproduce the Issue: Execute the specific agent workflow or UI interaction requiring investigation.
3. Inspect Log Files: Read main.log for backend logic or renderer.log for frontend state changes using cat ~/.config/CraftAgents/main.log.
4. Correlate with Source: Search the codebase for the specific debug message string (e.g., grep "Starting version fetch") to locate the exact execution path in packages/shared/src/version/manifest.ts or similar files.
5. Iterate: Adjust configurations or code and compare log outputs between runs to verify behavioral changes.

Debug Output Example

The following pattern from packages/shared/src/version/manifest.ts demonstrates typical usage:

import { debug } from '../utils/debug.ts';

export async function getLatestVersion() {
  debug('[manifest] Starting version fetch');
  const resp = await fetch('https://example.com/manifest.json');
  if (!resp.ok) {
    debug('[manifest] Failed to fetch manifest:', resp.status);
    return null;
  }
  const data = await resp.json();
  debug('[manifest] Got version:', data.version);
  return data.version;
}

With CRAFT_DEBUG=1 enabled, this produces structured output in both console and log files:

[manifest] Starting version fetch
[manifest] Got version: 1.4.2

Key Source Files for Debugging

Explore these specific locations to understand the debugging implementation:

• Core Debug Utility: packages/shared/src/utils/debug.ts — The debug() function and state management
• Electron Main Logger: apps/electron/src/main/logger.ts — File persistence and formatting logic
• Renderer Shim: apps/webui/src/shims/electron-log.ts — Browser-to-Electron logging adapter
• CLI Entry Point: apps/cli/src/index.ts — Argument parsing and initial activation
• Usage Examples: packages/shared/src/version/manifest.ts, packages/shared/src/version/install.ts, and packages/shared/src/utils/large-response.ts — Real-world debugging instrumentation

Summary

• Set CRAFT_DEBUG=1 or use --debug to enable the internal debugging system in craft-agents-oss
• Debug output automatically routes to both console and Electron log files (main.log and renderer.log)
• The debug() helper in packages/shared/src/utils/debug.ts provides zero-cost overhead when disabled
• Log files persist in the Electron user-data directory (e.g., ~/.config/CraftAgents/ on Linux)
• Search debug messages in source code to trace execution paths without adding temporary console statements

Frequently Asked Questions

Where are Craft Agents log files stored?

Log files are written to the Electron user-data directory, which varies by operating system. On Linux, this is ~/.config/CraftAgents/ containing main.log (backend process) and renderer.log (UI process). The electron-log package manages these paths automatically based on OS conventions.

What is the difference between CRAFT_DEBUG and the --debug flag?

The --debug CLI flag is a convenience wrapper that internally sets CRAFT_DEBUG=1 and calls enableDebug() during CLI initialization in apps/cli/src/index.ts. Both methods activate the same debugging system, but the environment variable works across all execution contexts including the Electron desktop app and programmatic API usage.

Does enabling debug mode affect performance?

When CRAFT_DEBUG is not set to 1, the debug() function executes as a no-op with negligible overhead, making it safe for production builds. Only when explicitly enabled does the system allocate resources for timestamp generation, message formatting, and file I/O operations.

How do I debug only specific modules or components?

While there is no built-in namespace filter, the codebase uses bracketed prefixes (e.g., [manifest], [install]) in debug messages. Use grep or log filtering tools to isolate specific subsystems: grep "\[manifest\]" ~/.config/CraftAgents/main.log will show only manifest-related debug output.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}