App Directories

Magia follows platform-native directory conventions via Tauri’s path API. The app data and cache directories are determined by the bundle identifier baked into the binary at compile time.

Production build (official releases)

Bundle identifier: sh.magia.app

Purpose	Path (macOS)
App data directory	`~/Library/Application Support/sh.magia.app/`
App cache directory	`~/Library/Caches/sh.magia.app/`
Logs	`~/Library/Logs/sh.magia.app/`
WebKit cache	`~/Library/WebKit/sh.magia.app/`
Sockets (Unix domain)	`$TMPDIR/magia-{uid}/`

Development build (worktrees)

Bundle identifier: sh.magia.dev

Purpose	Path (macOS)
App data directory	`~/Library/Application Support/sh.magia.dev/`
App cache directory	`~/Library/Caches/sh.magia.dev/`
Logs	`~/Library/Logs/sh.magia.dev/`
WebKit cache	`~/Library/WebKit/sh.magia.dev/`
Sockets (Unix domain)	`$TMPDIR/magia-{uid}/`

Development builds use a separate identifier so that running a worktree alongside the production app does not corrupt production data.

Files within the data directory

File / Directory	Purpose
`settings.json`	All user settings (see Settings Reference)
`workspaces.json`	Workspace definitions
`project-profiles.json`	Legacy project profiles (superseded by workspaces)
`sessions.db`	SQLite database (projects, metrics, sessions)
`memory/`	Per-project memory (observations, reflections, cursors, stats)
`memory/{project-encoded}/observations/`	Raw observation JSONL files
`memory/{project-encoded}/cursor.json`	Observation read cursor for the project
`memory/{project-encoded}/stats.json`	Token/cost stats aggregated from memory

The {project-encoded} segment is a URL-encoded or hash representation of the project’s root path.

Files within the cache directory

File	Purpose
`sessions-cache.json`	Incremental session cache (title, first-prompt, cost summary per session). Safe to delete — rebuilt automatically on next launch.

Unix sockets (IPC)

All sockets live in $TMPDIR/magia-{uid}/ (e.g. /var/folders/…/magia-501/ on macOS). Each running Magia instance uses a unique suffix to allow multiple instances to coexist.

Socket	Production name	Dev name
Hook listener	`hooks-prod.sock`	`hooks-{port}.sock`
CLI listener	`cli-prod.sock`	`cli-{port}.sock`
Permission listener	`permissions.sock`	`permissions.sock`
OTel gRPC collector	`otel-prod.sock`	`otel-{port}.sock`
Active-socket registry	`active-hook-sockets`	`active-hook-sockets`

{port} is the value of the MAGIA_DEV_PORT environment variable set by pnpm dev:worktree.

Legacy directory (`~/.magia/`)

Older versions of Magia stored data in ~/.magia/. On first launch after upgrading, Magia automatically migrates:

~/.magia/settings.json → data directory
~/.magia/workspaces.json → data directory
~/.magia/memory/ or ~/.magia/data/memory/ → data directory

The ~/.magia/ directory is never deleted during migration. You can remove it manually once you have confirmed that the new data directory is populated correctly.

Themes directory

User-installed themes are loaded from ~/.magia/themes/ (not in the OS-native app data directory). Drop a .json theme file there and it will be available in Settings → Appearance after a reload.

Other relevant paths

Path	Purpose
`~/.claude/settings.json`	Claude Code settings file — Magia injects hooks and OTel config here
`/usr/local/bin/magia`	CLI symlink installed by `Settings → CLI Integration`
`~/.nvm/`, `~/.volta/`, `~/.fnm/`	Node version manager paths searched when building the enriched `$PATH` for spawned processes

Platform notes

Linux

Purpose	Path
App data	`~/.local/share/sh.magia.app/`
App cache	`~/.cache/sh.magia.app/`
WebKit cache	`~/.cache/sh.magia.app/`
Sockets	`$TMPDIR/magia-{uid}/`

Windows

Purpose	Path
App data	`%APPDATA%\sh.magia.app\`
App cache	`%LOCALAPPDATA%\sh.magia.app\`
Sockets	Named pipes (not Unix sockets)