Logs and diagnostics
Where AgentGrid stores its data on disk and what to capture when filing a bug.
When something goes wrong, the first thing to know is where AgentGrid keeps its state. AgentGrid is an Electron app, so its data lives in the standard per-OS Electron userData directory.
App data directory
Electron writes everything under the Chromium userData directory for the app id sh.agentgrid.app. By OS the default is:
- macOS —
~/Library/Application Support/AgentGrid/ - Windows —
%APPDATA%\AgentGrid\ - Linux —
~/.config/AgentGrid/
A dev build of AgentGrid suffixes the directory with -dev (for example AgentGrid-dev/) so a development run never shares state with a packaged install. If you're running both, expect two directories.
Inside this directory AgentGrid persists app state — including the recent-projects list (recent-projects.json) and the paired-device store used by the mobile bridge.
Single-instance lock
AgentGrid holds a single-instance lock against its userData directory at launch. A second copy that tries to boot against the same directory will exit instead of starting a parallel session. If the app refuses to start, confirm there isn't already a copy running (check the tray / dock / Activity Monitor / Task Manager).
The lock is per-userData, so a packaged build and a dev build (with the -dev suffix) can both run at once.
Stale-child reaper
At launch AgentGrid runs a stale-child reaper that SIGTERMs orphan PTY children left behind by a previous run that crashed. If you see leftover claude, codex, or shell processes after a hard exit, simply restarting AgentGrid is enough — the reaper sweeps them on boot.
Logs
AgentGrid writes different diagnostics close to the state they describe:
- Renderer and Electron process crashes:
<userData>/crash-log/crash-events.jsonland<userData>/crash-log/electron.log. The JSONL journal retains the most recent 200 crash events. - Terminal-backed panes:
<project>/.agent-grid/terminals/<pane-id>.log. - Browser screenshots:
<project>/.agent-grid/screenshots/, with retention controlled under Settings -> Browsers. - Voice calls: open Settings -> Call History, select a call, and use the reveal action to locate its transcript and summary.
Electron crash minidumps remain local; crash reporting is configured not to upload them.
Review logs before sharing them. Terminal and call logs can contain commands, output, local paths, or spoken transcript text. Do not zip the whole userData directory: it also contains account and device state that is unrelated to a normal bug report.
When reporting an issue, include:
- The exact AgentGrid version (visible in the About menu and in
package.json). - Your OS and architecture (
uname -aon macOS/Linux,winveron Windows). - The CLI versions of
claude,codex, andagyif the issue involves agent panes. - A reproduction — what you spawned, what you ran, what you expected, what you saw.
Resetting state
If app state becomes corrupted, quit AgentGrid fully and either move or delete the userData directory listed above. AgentGrid will re-create it on next launch. You'll lose your recent-projects list and paired mobile devices, but settings and project folders on disk are untouched.