Skip to content
Magia

Quick Start

This guide walks you through the basics after you have completed onboarding.

1. Launch Magia

Section titled “1. Launch Magia”

Open Magia from your Applications folder or the macOS menu bar icon. On first launch, Magia runs the onboarding flow — see Onboarding for a step-by-step guide.

2. Create a Session

Section titled “2. Create a Session”

Sessions are the primary unit of work. Each session is an isolated conversation with an AI agent that has access to a project directory.

  1. Click New Session in the left sidebar (or press Cmd+N).
  2. Choose a working directory — this is the root of the project the agent will work in.
  3. Select a provider (Claude Code, Gemini CLI, or Codex CLI) if you have more than one installed.

The session opens in the main view.

3. The UI Layout

Section titled “3. The UI Layout”

Magia is split into three areas:

AreaDescription
Left sidebarLists all sessions — running, paused, and archived. Pinned sessions appear at the top.
Main panelThe active session. Contains the conversation history, tool call output, and the input area at the bottom.
Right panelContext panel showing file diffs, code snippets, and live metrics for the active session (toggle with the icon in the top bar).

The integrated terminal is embedded within each session so you can run commands without leaving the app.

4. Send Your First Prompt

Section titled “4. Send Your First Prompt”

Type a prompt in the input area at the bottom of the session and press Enter (or Shift+Enter for a new line).

Example:

Explain the structure of this codebase and identify the main entry points.

The agent starts responding immediately. As it works, you will see tool calls appear inline — file reads, writes, searches, and terminal commands are all visible as they happen.

5. Watch Tool Calls

Section titled “5. Watch Tool Calls”

Each tool call is displayed as a collapsible block in the conversation. You can expand any tool call to see its input and output. This lets you follow exactly what the agent is doing in real time.

If Magia detected your provider during onboarding and hooks were configured, cost and token metrics appear in the session header as the agent runs.

6. Start an Agent from the Terminal

Section titled “6. Start an Agent from the Terminal”

If you installed the magia CLI during onboarding, you can open any directory directly:

Terminal window
cd ~/my-project
magia . --provider claude

Magia opens the directory as a new session and launches the agent automatically.

What’s Next?

Section titled “What’s Next?”