AgentGridAgentGrid Docs
Troubleshooting

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. If you use Settings → Observability → Local Langfuse, the managed Langfuse clone also lives under this tree (see Observability with Langfuse).

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.jsonl and <userData>/crash-log/electron.log. The JSONL journal retains the most recent 200 crash events.
  • Terminal-backed panes: <project>/.agent-grid/terminals/<pane-id>-<id>.log (one file per terminal start). What a full-screen program such as vim shows is left out of the log, so a file you open in it is not written to disk. Before the log is written, AgentGrid masks well-known key formats (such as private keys, sk- and AWS access keys), values assigned to names containing TOKEN, KEY, SECRET, PASSWORD or similar, connection-string passwords, and up to 64 values of 16 or more characters from .env files in the terminal's starting folder (numbers and true/false-style values aren't masked). A password printed on its own isn't recognized, so review logs before sharing them. Logs untouched for 7 days are deleted when a new terminal starts.
  • Browser screenshots: <project>/.agent-grid/screenshots/, kept 30 days by default; see Screenshot retention.
  • Voice calls: click the history button in a pane's header, or choose Call history from the workspace explorer's filter menu, 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.

AgentGrid also keeps a privacy-filtered diagnostics journal under <userData>/diagnostics/, including pane crashes. It's only sent to us while Share usage data is on (Settings → Advanced → Privacy); see Security and privacy.

On the phone, Diagnostics stay with the account you're signed in as. Switching accounts does not show or copy the previous account's computer ids and logs.

Export diagnostics

To send us that journal yourself, open the tray menu (on macOS, right-click AgentGrid's Dock icon) and choose Export diagnostics…. You don't need to be signed in, and the main window doesn't need to be open. AgentGrid saves a single AgentGrid-diagnostics-<date>.json file where you choose. See System tray and daemon.

Record a performance trace

If AgentGrid feels slow, choose View → Record Performance Trace…, reproduce the slowdown, then choose View → Stop Performance Trace. The trace is saved to your Downloads folder as agentgrid-trace-<time>.json, and AgentGrid shows it in your file manager. Attach it to your bug report.

Crashes on startup

If the window crashes over and over, AgentGrid stops reloading it and shows AgentGrid keeps crashing, with where the crash details were saved. Restarting the app usually fixes this.

If the app crashes several times in a row while starting, the next launch asks about Sessions paused after repeated startup crashes. Choose Keep sessions closed to start without restoring your Coordinator and team lead sessions. Their history is kept, so you can bring them back later from File → Reopen Saved Sessions. Choose Reopen sessions to try restoring them straight away.

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 your exported diagnostics and:

  1. The exact AgentGrid version (visible in the About menu and in package.json).
  2. Your OS and architecture (uname -a on macOS/Linux, winver on Windows).
  3. The CLI versions of claude, codex, and agy if the issue involves agent panes.
  4. 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.

On this page

Ask AI

Ask a question about AgentGrid. Answers come from these docs, with links to the pages they use.

AI answers can be wrong. Check the linked pages.