agent-hq-electron-config

name: agent-hq-electron-config description: Configure Agent HQ Electron crash mitigations + diagnostics via repo .env (added after 2026-01-22 renderer crash).

Agent HQ Electron Config

[Created by Codex: 019be57f-73d6-75a3-86f1-1ea758dd94df 2026-01-22]

Why this exists

On 2026-01-22, Agent HQ crashed because the Electron renderer process died with SIGTRAP (exit code 5). These .env flags exist so you can:

Toggle mitigation behavior without code edits
Increase log detail when debugging incidents like that one

Configurable (repo root `.env`)

Logging destination (required)

AGENT_HQ_ELECTRON_LOG_DIR — JSONL logs written here (timestamped filenames). Required; Electron will fail fast if missing.

Crash mitigation flags (optional, 0/1)

AGENT_HQ_ELECTRON_DISABLE_HARDWARE_ACCELERATION — Calls app.disableHardwareAcceleration() before app.whenReady().
AGENT_HQ_ELECTRON_RESTART_ON_RENDERER_CRASH — If the main window renderer dies, destroys the window and recreates it after a short delay.

Verbose logging (optional, 0/1)

AGENT_HQ_ELECTRON_VERBOSE_LOGGING — Adds extra context (memory/uptime metadata, extra crash fields like GPU feature status).

Usage

Edit repo root .env
Restart Agent HQ Electron
Inspect the newest JSONL file in AGENT_HQ_ELECTRON_LOG_DIR

Handy commands

# Tail the newest Agent HQ Electron log file (macOS / zsh)
LATEST="$(ls -t ~/centralized-logs/agent-hq2/*.jsonl | head -n 1)" && tail -f "$LATEST"

Notes

macOS crash dumps live in: ~/Library/Logs/DiagnosticReports/ (look for Electron Helper (Renderer)-*.ips).