Troubleshooting
Provider not detected
Section titled “Provider not detected”Symptom: The onboarding screen says no providers are installed, or a provider that is installed does not appear in Settings.
| Check | Action |
|---|---|
Binary not in $PATH | Open a new terminal and run which claude (or gemini, codex). If nothing is returned, install the CLI tool or add it to $PATH. |
App inherits a minimal $PATH | Magia enriches $PATH at runtime by searching Homebrew, nvm, Volta, fnm, and common install locations. Confirm the binary is in one of those locations. |
| Manual path override needed | Go to Settings → Providers, find the provider, and set a custom binary path. |
| Hooks not yet configured | After a fresh install, complete the onboarding wizard so Magia can inject hooks into the provider settings file. |
Hooks not working
Section titled “Hooks not working”Symptom: Sessions complete but no events appear in the session view, or the session status never updates.
| Check | Action |
|---|---|
| Hooks not configured | Go to Settings → Providers and click Re-configure hooks for the affected provider. |
| Hooks outdated | If a Magia update changed the hook format, check_hooks_outdated will return true. Re-running hook configuration from Settings will update them. |
| Socket not listening | The hook listener connects via a Unix socket in $TMPDIR/magia-{uid}/. Check that the socket file (hooks-prod.sock in production) exists. If not, quit Magia and relaunch. |
| Multiple Magia instances | Running a dev worktree and the production build simultaneously is supported — each uses a different socket name. Hooks from a session started in one instance will not appear in the other. |
| Provider config directory non-standard | If you use a non-default Claude config directory (e.g. a multi-account setup), ensure the correct account is selected in Settings → Providers. |
Session stuck / not responding
Section titled “Session stuck / not responding”Symptom: An agent session appears to be running but produces no new output. The spinner keeps spinning.
| Check | Action |
|---|---|
| Process still alive | In the session sidebar, check whether a “kill session” button appears. If the underlying process has died silently, the UI may take up to 5 seconds to detect it (PID health-check interval). |
| Watchdog timeout | Magia has a configurable watchdog. After watchdogTimeoutSecs (default: 15) of silence, a warning is shown. You can adjust this in Settings → General. |
| Waiting for permission | The agent may be waiting for you to approve a tool use. Check the chat view for a pending permission request. |
| Increase the timeout | If the model is slow, increase watchdogTimeoutSecs in Settings → General. |
| Kill and retry | Use the Kill session button in the session sidebar, then start a new session. |
Terminal not starting
Section titled “Terminal not starting”Symptom: The embedded terminal shows a blank screen or immediately exits.
| Check | Action |
|---|---|
| Shell not found | The default shell is read from $SHELL. If $SHELL is not set or the binary does not exist, the terminal will fail. Go to Settings → Terminal and set a shell path manually (e.g. /bin/zsh). |
| Working directory invalid | Magia opens the terminal in the session’s working directory. If that directory has been deleted or is on an unmounted volume, the PTY will fail to start. |
| Environment variable conflict | A broken $PATH or invalid $TERM can prevent the shell from starting. Open a normal terminal and check your shell init files (~/.zshrc, ~/.bashrc). |
Voice input not working
Section titled “Voice input not working”Symptom: The microphone button does nothing, transcription fails, or the wrong language is detected.
| Check | Action |
|---|---|
| Voice input disabled | Enable voice input in Settings → Voice. |
| Whisper model not downloaded | Go to Settings → Voice and download a model. The base model is a good starting point. |
| Microphone permission not granted | macOS requires microphone permission. Open System Settings → Privacy & Security → Microphone and ensure Magia is allowed. |
| Wrong audio device | If you have multiple input devices, go to Settings → Voice and select the correct microphone. |
| Language detection wrong | If transcription quality is poor, set a specific language in Settings → Voice instead of using "auto". |
| Parakeet model missing | If sttEngine is "parakeet" and the model is not downloaded, transcription will silently fail. Switch to "whisper" or download the Parakeet model from Settings → Voice. |
Factory reset
Section titled “Factory reset”A factory reset deletes all Magia data, removes hook configuration from provider settings files, uninstalls the CLI, and restarts the app to the onboarding screen.
Steps:
- Open Settings → General → Danger Zone.
- Click Factory Reset.
- Confirm the prompt.
Magia will:
- Uninstall the
magiaCLI symlink. - Remove hooks and OTel config from all Claude Code accounts.
- Remove Gemini hooks.
- Delete the app data directory (
~/Library/Application Support/sh.magia.app/). - Delete the app cache directory (
~/Library/Caches/sh.magia.app/). - Delete WebKit data (
~/Library/WebKit/sh.magia.app/). - Delete log files (
~/Library/Logs/sh.magia.app/). - Restart to the onboarding screen.
Where to find logs
Section titled “Where to find logs”Application logs (macOS)
Section titled “Application logs (macOS)”| Log | Location |
|---|---|
| Magia application log | ~/Library/Logs/sh.magia.app/ |
| Production builds (Console.app) | Open Console.app, filter by sh.magia.app |
Development builds
Section titled “Development builds”In dev mode, log output goes to the terminal where pnpm dev:worktree is running. The log level is set to Info in debug builds.
WebKit / frontend logs
Section titled “WebKit / frontend logs”Open the Magia window, then open Settings → General → Developer Tools (requires Developer Mode). This opens the WebKit web inspector where you can see JavaScript console output.
Session transcripts (raw JSONL)
Section titled “Session transcripts (raw JSONL)”Each session stores its raw events in a .jsonl file inside the provider’s session directory (e.g. ~/.claude/projects/…/). These can be inspected directly with any JSON viewer.
How to report a bug
Section titled “How to report a bug”Before filing a bug, check the GitHub Issues list to see if it has already been reported.
When filing a new issue, include:
- Magia version (visible in Settings → About or the window title bar in dev mode).
- macOS / OS version.
- Provider and model being used.
- Steps to reproduce the problem.
- What you expected to happen vs. what actually happened.
- Relevant log output from
~/Library/Logs/sh.magia.app/(redact any sensitive content). - Whether the issue reproduces after a fresh install or factory reset.
Getting help
Section titled “Getting help”- GitHub Discussions — questions, ideas, and general help: github.com/magiash/magia/discussions
- GitHub Issues — confirmed bugs and feature requests: github.com/magiash/magia/issues