Skip to content
OpenWaggle

Data and file locations

Where OpenWaggle keeps its data, logs, worktrees, sessions and temporary files on each platform.

This page lists where OpenWaggle and Pi keep their files on macOS, Windows and Linux. For the format of each configuration file, such as settings.json, mcp.json, auth.json or models.json, see Configuration files. In the paths below, ~ is your home folder, %USERPROFILE% on Windows.

App data folder

The app data folder holds the session database, app settings, logs and the other files in What is in the app data folder.

PlatformLocation
macOS~/Library/Application Support/openwaggle/
Windows%APPDATA%\openwaggle\
Linux$XDG_CONFIG_HOME/openwaggle/, which is ~/.config/openwaggle/ when XDG_CONFIG_HOME is not set

Every released channel, Stable, Beta, RC and Alpha, uses the same folder. A Dev build, such as one you run from a source checkout, uses its own folder beside it, named OpenWaggle Dev (<branch>), so it never reads or changes your installed app’s sessions, settings or credentials.

Set OPENWAGGLE_USER_DATA_DIR to use another folder. The desktop app, the Session Host and the openwaggle command all read it. See Environment variables.

What is in the app data folder

PathContents
session-host/session-host.sqliteThe session database: sessions, transcripts, the session tree, app settings, pinned sessions and their order, Hives, delegations, scheduled tasks, and each project’s private project actions and overrides
session-host/pre-cutover-openwaggle.sqliteThe recovery copy kept when an upgrade migrated an older openwaggle.db. See Recover an older session database
session-host/Also the Session Host’s ownership files and access profile credentials, and its socket. See The Session Host’s socket
logs/Log files on Windows and Linux, and on macOS when OPENWAGGLE_USER_DATA_DIR is set. See Logs
mcp/MCP secrets and sign-ins, encrypted, and the tool catalogs of your MCP servers. Each build keeps its own, because builds encrypt with different keys
extensions/<extension ID>/Global extension packages. See Build an extension
visualizations/<session ID>/The HTML of each session’s inline visualizations
session-resources/Copies of files and images listed in a session’s Sources & outputs
browser-preview-artifacts/Screenshots, recordings and annotations from the browser preview
temp-attachments/Temporary copies of attachments and prompt files
terminal-logs/Recent terminal scrollback, at most 5,000 lines and 10 MiB per terminal
action-logs/Output of project actions
preparation/Worktree setup and other preparation state, for each workspace
worktree-removal/A record of the last 20 automatic worktree removals
models/transformers/The speech model for voice input, downloaded on first use
models/session-embedding/<revision>/The session search model, about 135 MB, downloaded on first use. Each file is checked against its pinned SHA-256 hash when it is downloaded. Each model revision has its own folder
syntax-resources/Syntax themes and grammars you imported in Settings > Appearance
usage-statistics/Usage statistics recorded today and not yet sent. See When statistics are sent. Also last-known-setting.json, the Share anonymous usage statistics and error reports value the Session Host last loaded. See Error reports
session-data/The window’s browser profile: local storage, cookies and cache
shell-environment.jsonThe environment read from your login shell at the last launch, so the next launch starts faster

The sidebar’s sort order, which projects are collapsed, and the Pinned section’s sort live in the window’s local storage under session-data/, so OpenWaggle remembers them between launches. Pinned sessions and their dragged order are in the session database. OpenWaggle does not remember text filters and state chips, so an old filter never keeps sessions hidden.

Older versions kept openwaggle.db and session-host.sqlite at the top of the folder. Current versions write neither.

The session database is not a full backup. Provider credentials live in Pi’s auth.json, in environment variables or in custom provider configuration, and your project files live in your project and its worktrees.

Logs

PlatformDesktop app logSession Host log
macOS~/Library/Logs/openwaggle/~/Library/Logs/openwaggle/
Windowslogs\ in the app data folderlogs\ in the app data folder
Linuxlogs/ in the app data folderlogs/ in the app data folder

The desktop app writes openwaggle-YYYY-MM-DD.log and the Session Host writes openwaggle-host-YYYY-MM-DD.log. Each line starts with its time in UTC, such as 16:54:22.855Z, and the date in the file name is the UTC date too. With OPENWAGGLE_USER_DATA_DIR set, both logs go to logs/ in that folder.

When agent work fails, the error display can open the desktop app’s log folder. Review logs for secrets and private project details before you share them.

Pi agent folder

Pi, the agent engine inside OpenWaggle, keeps its files in ~/.pi/agent/, or in the folder PI_CODING_AGENT_DIR names. The pi command uses the same folder, so both share credentials, models and sessions.

PathContents
auth.jsonProvider API keys and sign-ins saved through Pi. Plain JSON, so protect it as a secret file
models.jsonCustom providers and models
settings.jsonPi’s settings
mcp.jsonPi’s MCP servers for all projects
waggle-presets.jsonYour Waggle presets
sessions/Pi session files, one folder per working directory

Session files move to the folder named by PI_CODING_AGENT_SESSION_DIR, or by the sessionDir setting in the project’s .pi/settings.json or Pi’s global settings.json. OpenWaggle stores its new sessions there too, so pi --resume finds them. See Pi runtime.

OpenWaggle home folder

~/.openwaggle/ holds files that every OpenWaggle build shares.

PathContents
mcp.jsonOpenWaggle’s MCP servers for all projects
mcp/The MCP Registry cache, backups of mcp.json, and mcp.log
agents/Your agent definitions
worktrees/Managed worktrees. See Managed worktrees
cache/tesseract/The text-recognition cache for image attachments

Managed worktrees

OpenWaggle creates each managed worktree outside your project, at ~/.openwaggle/worktrees/<project folder name>/<workspace ID>. A new worktree’s branch is ow/session-<workspace ID>, the same ID as its folder. It can differ from the session ID. Sessions that share a workspace use the same checkout. Worktrees made by older versions keep the names they were created with, so check Session Summary > Environment for a session’s real path and branch. See Projects and worktrees.

Temporary files

Each session gets a private scratch folder for temporary files, and an evidence folder for screenshots and other files an agent shows you or another session.

FolderLocation
Scratch<temp>/ow-scratch-<user ID>/<profile>/<session>/
Evidence<temp>/ow-scratch-<user ID>/<profile>/evidence/<session>/

<temp> is your temporary folder. On macOS and Linux it is /tmp when a path under your own temporary folder would be too long for a Unix socket, which is usual on macOS. On Windows it is %TEMP%, and the folder is named ow-scratch without a user ID. <profile> is a short code for the app data folder, so two profiles never share these folders. <session> is a short code for the session.

OpenWaggle points TMPDIR, TMP and TEMP at the scratch folder for the agent’s shell tools, and OPENWAGGLE_EVIDENCE_DIR at the evidence folder. It deletes the scratch folder when you archive or delete the session. It keeps the evidence folder after archiving, and removes it once nothing has been added to it for a week. See Hives and sessions.

The Session Host’s socket

The desktop app and the openwaggle command reach the Session Host through a local socket.

CaseLocation
macOS, Linuxsession-host/host.sock in the app data folder
Long pathowsh-<hash>/host.sock in your temporary folder, or in /tmp when that path is also too long
WindowsA named pipe, \\.\pipe\openwaggle-<code>-session-host

On macOS and Linux, the socket moves out of the app data folder when its path there would be longer than 100 bytes, which keeps it under the Unix socket path limit (104 bytes on macOS). <hash> comes from the app data folder’s path, so each profile gets its own socket. On Windows, <code> is a random code that OpenWaggle keeps in session-host/endpoint.capability, readable only by your user account.

Startup cache

OpenWaggle keeps compiled code between launches so the app starts faster. AppImage builds on Linux keep none.

PlatformLocation
macOS~/Library/Caches/OpenWaggle/compile-cache/<channel>/
Windows%LOCALAPPDATA%\OpenWaggle\Cache\compile-cache\<channel>\
Linux$XDG_CACHE_HOME/openwaggle/compile-cache/<channel>/, which is ~/.cache/openwaggle/compile-cache/<channel>/ when XDG_CACHE_HOME is not set

Installed files

PlatformAppopenwaggle command
macOS/Applications/OpenWaggle.app, or the folder OPENWAGGLE_APPLICATIONS_DIR names when you install with the script~/.local/bin/openwaggle
Linux~/.local/lib/openwaggle/OpenWaggle.AppImage, with a desktop entry in ~/.local/share/applications/openwaggle.desktop~/.local/bin/openwaggle
WindowsWhere the installer puts itRegistered by the installer

The install script saves an update channel in install-update-channel, in ~/Library/Application Support/openwaggle/ on macOS or $XDG_CONFIG_HOME/openwaggle/ (~/.config/openwaggle/) on Linux. It saves the channel OPENWAGGLE_CHANNEL names, or the default when there is no installed channel to keep. A re-run that keeps the installed app’s channel writes nothing. See Installation.

Project folders

A project can hold OpenWaggle and Pi files of its own, such as .openwaggle/settings.json, .openwaggle/actions.json, .openwaggle/mcp.json, .openwaggle/agents/, .pi/mcp.json and .pi/waggle-presets.json. Configuration files lists each one.