Logs and diagnostics
Where Agent Grid stores its data on disk and what to capture when filing a bug.
When something goes wrong, the first thing to know is where Agent Grid keeps its state. Agent Grid 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/Agent Grid/ - Windows —
%APPDATA%\Agent Grid\ - Linux —
~/.config/Agent Grid/
A dev build of Agent Grid suffixes the directory with -dev (for example Agent Grid-dev/) so a development run never shares state with a packaged install. If you're running both, expect two directories.
Inside this directory Agent Grid persists app state — including the recent-projects list (recent-projects.json) and the paired-device store used by the mobile bridge.
Single-instance lock
Agent Grid 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 Agent Grid 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 Agent Grid is enough — the reaper sweeps them on boot.
Logs
Exact log filenames and rotation behaviour aren't documented in this brief. Logs are written under the userData directory described above, but the precise paths depend on the build. If you're filing a bug, zip the whole userData directory (minus credentials, see Security and privacy) or ask the maintainers which file to grab.
When reporting an issue, include:
- The exact Agent Grid 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 Agent Grid fully and either move or delete the userData directory listed above. Agent Grid 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.