# How to Debug Craft Agents Using Log Files and CRAFT_DEBUG

> Learn to debug Craft Agents efficiently using log files and the CRAFT_DEBUG environment variable. Enable detailed logging for comprehensive agent tracing and issue resolution.

- Repository: [Craft Ai Agents/craft-agents-oss](https://github.com/craft-ai-agents/craft-agents-oss)
- Tags: how-to-guide
- Published: 2026-07-03

---

**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`](https://github.com/craft-ai-agents/craft-agents-oss/blob/main/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`](https://github.com/craft-ai-agents/craft-agents-oss/blob/main/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`](https://github.com/craft-ai-agents/craft-agents-oss/blob/main/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`](https://github.com/craft-ai-agents/craft-agents-oss/blob/main/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:

```bash
craft-agents --debug start

```

This triggers `enableDebug()` during CLI initialization in [`apps/cli/src/index.ts`](https://github.com/craft-ai-agents/craft-agents-oss/blob/main/apps/cli/src/index.ts), setting the internal state before your agents begin execution.

### Environment Variable Method

Set `CRAFT_DEBUG` before invoking the binary:

```bash
export CRAFT_DEBUG=1
craft-agents start

```

Windows PowerShell users should use:

```powershell
$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:

```bash
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`](https://github.com/craft-ai-agents/craft-agents-oss/blob/main/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`](https://github.com/craft-ai-agents/craft-agents-oss/blob/main/packages/shared/src/version/manifest.ts) demonstrates typical usage:

```typescript
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`](https://github.com/craft-ai-agents/craft-agents-oss/blob/main/packages/shared/src/utils/debug.ts) — The `debug()` function and state management
- **Electron Main Logger**: [`apps/electron/src/main/logger.ts`](https://github.com/craft-ai-agents/craft-agents-oss/blob/main/apps/electron/src/main/logger.ts) — File persistence and formatting logic
- **Renderer Shim**: [`apps/webui/src/shims/electron-log.ts`](https://github.com/craft-ai-agents/craft-agents-oss/blob/main/apps/webui/src/shims/electron-log.ts) — Browser-to-Electron logging adapter
- **CLI Entry Point**: [`apps/cli/src/index.ts`](https://github.com/craft-ai-agents/craft-agents-oss/blob/main/apps/cli/src/index.ts) — Argument parsing and initial activation
- **Usage Examples**: [`packages/shared/src/version/manifest.ts`](https://github.com/craft-ai-agents/craft-agents-oss/blob/main/packages/shared/src/version/manifest.ts), [`packages/shared/src/version/install.ts`](https://github.com/craft-ai-agents/craft-agents-oss/blob/main/packages/shared/src/version/install.ts), and [`packages/shared/src/utils/large-response.ts`](https://github.com/craft-ai-agents/craft-agents-oss/blob/main/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`](https://github.com/craft-ai-agents/craft-agents-oss/blob/main/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`](https://github.com/craft-ai-agents/craft-agents-oss/blob/main/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.