Onboarding

When you launch Magia for the first time it runs an 8-step onboarding flow. This page explains what each step does and why it matters.

Step 1 — Welcome

The welcome screen introduces Magia and gives you a single Get Started button. No configuration happens here.

Step 2 — Detecting AI Agents

Magia scans your system for supported AI coding agent CLIs:

Agent	CLI command	Install
Claude Code	claude	npm install -g @anthropic-ai/claude-code
Gemini CLI	gemini	npm install -g @google/gemini-cli
Codex CLI	codex	npm install -g @openai/codex

For each agent Magia checks:

• Detected — binary found and authenticated. Ready to use.
• No credentials — binary found but not logged in. You will see the command to run (e.g. claude login).
• Not found — binary not on PATH. You can expand the row to see install instructions, or click Specify location to point Magia to a non-standard binary path.

You can skip any agent. Magia will warn you if none are detected, since most features require at least one agent.

Step 3 — CLI Path Fallback (conditional)

This step is only shown when at least one agent was not found automatically. It lets you enter a custom binary path for each missing agent and verify it before continuing.

If all agents were detected in step 2, this step is skipped automatically.

Step 4 — Hooks

Hooks are the mechanism that connects your AI agent to Magia. When hooks are configured, Magia receives real-time events from the agent — every tool call, cost update, token count, and session lifecycle event flows through a local Unix socket to the Magia app.

This step is only shown for agents that support hooks (currently Claude Code and Gemini CLI). If neither is installed, it is skipped.

Clicking Configure performs three actions:

1. Hooks — injects magia-hook-handler as a hook handler in the agent’s configuration file. For Claude Code this modifies ~/.claude/settings.json. The hook handler is a small Rust binary bundled with Magia that forwards event JSON to the app over a local socket.
2. Telemetry — configures OpenTelemetry export from the agent to Magia’s local OTLP receiver so metrics (tokens, latency, cost) are collected.
3. Status Line — adds a status line entry to the agent’s configuration so session context is visible in terminal output.

None of these changes send data outside your machine. The hook handler only writes to a local socket file at $TMPDIR/magia-{uid}/.

You can skip this step. If you do, Magia will still detect running sessions but will not show live metrics or tool call details.

To reconfigure hooks later, go to Settings → Providers and click Configure next to any provider.

Step 5 — Privacy & Telemetry

Magia collects two categories of anonymous data:

Crash Reporting (via Sentry, EU region)

• Sent: stack traces, OS version, app version, device type
• Never sent: code, file contents, conversation history, personal data

Usage Analytics (via PostHog, EU instance)

• Sent: feature usage, button clicks, session duration, installed providers
• Never sent: code, file contents, conversation history, personal data

Both are active only in official builds distributed via GitHub Releases. If you build Magia from source without setting the SENTRY_DSN and VITE_POSTHOG_KEY environment variables, all telemetry is disabled.

You can change these settings any time in Settings → Telemetry.

Step 6 — Terminal Integration

This step installs the magia CLI tool at /usr/local/bin/magia so you can open projects from your terminal:

magia . --provider claude

This sends a message to the running Magia app over a local socket and asks it to open the specified directory as a new session. Magia must be running for this to work.

You can skip this step. To install the CLI later, go to Settings → General.

Step 7 — Voice Input

Magia supports voice-to-text input for prompts. Enabling this downloads a speech recognition model that runs entirely on your device — no audio is sent to any server.

By default, Magia downloads the Parakeet TDT model (~670 MB). If that download fails, you can fall back to an OpenAI Whisper model with four size options:

Model	Size
Tiny	75 MB
Base	142 MB
Small	466 MB
Medium	1.5 GB

The download continues in the background after this step — Magia auto-advances after 5 seconds. You can skip voice input entirely.

To change the model or disable voice input later, go to Settings → Voice Input.

Step 8 — Ready

The final screen shows how to start using Magia:

• From your terminal — run any detected agent CLI in a directory. Magia detects the new session automatically via hooks.
• From Magia — open a project and launch an agent directly from the UI.

You can also toggle Launch at Login here to have Magia start automatically when you log in to macOS.

Click Open Magia to complete setup. Onboarding will not be shown again unless you perform a factory reset from Settings → Advanced.