The Rust backend is compiled into a single native binary (the Tauri application). It owns all system-level resources: processes, file handles, sockets, and the database. The frontend has no direct access to any of these — everything is mediated through Tauri commands and events.
Magia uses Tokio as its async runtime (features: process, io-util, sync, time, rt, net). Blocking work (filesystem scans, database writes, PTY operations) is offloaded to tokio::task::spawn_blocking to avoid stalling the async executor.
| Module | Description |
|---|
agent | Spawns agent CLI processes, manages running agents (SharedAgentManager), handles permission requests (SharedPermissionManager), start_permission_listener Unix socket |
hooks | Receives hook events from agent processes over a Unix socket, normalises them into AgentEvent structs, maintains the live sessions map (SharedLiveSessions) |
session_cache | In-memory + on-disk cache of all discovered sessions (ActiveSession); incremental sync, PID health checks, dead session cleanup |
discovery | Scans provider session directories (Claude, Gemini, Codex) and project metadata; extracts first prompts, models, costs; submodules: types, provider, project, session, commands |
transcript | Reads and streams JSONL transcript files for past sessions |
observer | Background LLM calls to generate session titles and summaries from transcripts |
reflector | Background process that distills long-term memory observations from session data |
| Module | Description |
|---|
pty | PTY lifecycle management using portable-pty; creates PTY pairs, spawns processes inside them, bridges PTY I/O to Tauri events |
ide_server | WebSocket server that implements the Claude Code IDE protocol; allows VS Code / other editors to connect and receive session events |
| Module | Description |
|---|
provider_manager | Registry of all supported provider CLIs; detects installed binaries, manages provider state |
provider_config | Reads and writes provider configuration files (e.g. ~/.claude/settings.json) |
provider_account | Provider account management (connect, disconnect, list) |
provider_permissions | Tool permission model per provider account |
provider_instructions | Custom system prompt / instruction injection per provider |
claude_compat | Claude Code CLI compatibility layer (session format, hook protocol) |
codex_compat | OpenAI Codex CLI compatibility layer |
gemini_compat | Google Gemini CLI compatibility layer |
llm | Low-level LLM HTTP client; submodules: binary, cli, provider, spawn, types |
| Module | Description |
|---|
watchers | WatcherManager (provider config files), ActiveSessionWatcher (hook-driven, watches active session working dirs), ProviderSessionWatcher (Gemini + Codex session dirs), ThemeWatcher (~/.magia/themes/) |
projects | Project directory management and metadata |
workspaces | Named workspaces (groups of project paths) |
files | File read/write commands exposed to the frontend |
search | Full-text search across session transcripts and files |
symbols | Symbol extraction (ctags-style) for the context extractor |
git | Git integration — branch info, status, diff |
resources | Static resource access (bundled assets) |
| Module | Description |
|---|
lsp | Language Server Protocol client — bridges LSP responses to the frontend editor |
keybindings | Persists and loads user keybinding customisations |
| Module | Description |
|---|
otel | gRPC OpenTelemetry collector (Unix socket, with HTTP/TCP fallback); stores metrics in SharedMetricsStore |
audit_log | Structured audit log for user-facing events |
stats | Per-session and per-project statistics aggregation |
costs | Token cost calculation for different models |
event_normalizer | Normalises raw provider events into a unified AgentEvent shape |
| Module | Description |
|---|
stt | Speech-to-text pipeline: audio capture → Whisper inference via whisper-rs |
parakeet | Alternative STT backend using ONNX Runtime (ort) and the Parakeet model |
parakeet_manager | Manages Parakeet model download and lifecycle |
model_manager | Generic model download and cache management |
| Module | Description |
|---|
settings | Reads and writes settings.json; exposes SharedAppSettings (Arc-wrapped, async-Mutex) |
db | SQLite connection management, WAL mode configuration, and refinery migration runner |
paths | Central path resolution — all app directories go through this module |
cli | Unix socket listener for CLI commands from magia-hook-handler and the magia CLI binary |
cli_install | Installs / uninstalls the magia symlink in ~/.local/bin or /usr/local/bin |
themes | Custom theme loading from ~/.magia/themes/ |
plugins | MCP plugin management (install, enable, disable, list) |
fonts | System font enumeration for the editor |
extensions | Extension / plugin marketplace integration |
hook_registry | Registry of user-defined Claude Code hooks |
tray | System tray icon and menu management |
tray_panel | Floating tray panel window (mini session launcher) |
| Module | Description |
|---|
auth | OAuth flow orchestration (GitHub App + Google OAuth) |
api_client | HTTP client wrapper for the Magia API (MAGIA_API_URL) |
cloud | Cloud feature gate (is_cloud_build()) |
license | License entitlement checks |
| Module | Description |
|---|
ipc | Cross-platform local socket abstraction (interprocess crate); Unix file sockets on macOS/Linux, named pipes on Windows |
All background services are started by start_background_sync(), which is called by the frontend after onboarding is complete. The function is protected by an atomic flag and is safe to call multiple times.
Services start in this order:
- Hook listener — Unix socket that receives lifecycle events from agent CLIs.
- CLI listener — Unix socket for commands from the
magia CLI and magia-hook-handler binary.
- Permission listener — Unix socket for tool permission requests from agents.
- OTel gRPC collector — gRPC server on a Unix socket; falls back to HTTP/TCP if the socket cannot be created.
- File watchers —
WatcherManager, ActiveSessionWatcher, ProviderSessionWatcher, ThemeWatcher.
- Session cache sync — initial incremental sync runs immediately; periodic sync runs on a configurable interval (default 10 minutes, minimum 1 minute).
- IDE integration server — WebSocket server for the Claude Code VS Code extension.
- Observer — background LLM title/summary generation.
- Reflector — background memory distillation.
- Claude status polling — fetches the Claude.ai status page periodically.
- PID health check — runs every 5 seconds; marks sessions with dead PIDs as historical.
- Orphaned session cleanup — runs every 60 seconds (after a 30-second initial delay); removes sessions whose JSONL files no longer exist.
The database lives at {data_dir}/magia.db. It is opened in WAL mode with a 5-second busy timeout and NORMAL synchronous mode. This allows the magia-hook-handler process to write to the same database concurrently without blocking the main process.
Schema migrations are managed by refinery and embedded at compile time from the src-tauri/migrations/ directory:
| Migration | Description |
|---|
V1__initial_schema.sql | Core tables: sessions, projects |
V2__add_icon_image.sql | Project icon storage |
V3__add_include_subdirs.sql | Subdirectory inclusion flag on projects |
V4__add_git_repos.sql | Git repository metadata |
src-tauri/src/bin/magia-hook-handler.rs is a separate binary (magia-hook-handler) that is installed as a Claude Code hook. When the agent CLI fires a hook event, it executes magia-hook-handler, which serialises the event and delivers it to the main Magia process via the hook Unix socket. This design keeps the hook path lightweight and avoids spawning a new Magia process for every event.
