Your First Project

This guide takes you from a cold launch of Magia to a working agent session on a real codebase. It assumes you have already completed Onboarding and have at least one provider installed and authenticated.

1. Open Magia

Launch Magia from your Applications folder or click the menu bar icon. The main window opens with the session sidebar on the left. If no sessions exist yet, you will see an empty state with a New Session prompt.

2. Create a workspace for your project

Workspaces group all sessions that belong to the same project. Creating one up front keeps the sidebar organized as your session history grows.

1. Click the + button at the top of the session sidebar and choose New Workspace, or open Settings → General → Workspaces and click New Workspace.
2. Enter a name — for example, my-app.
3. Click Add Directory and select your project root (e.g., ~/code/my-app).
4. Click Save.

The workspace now appears as a tab at the top of the session sidebar. All sessions you create inside ~/code/my-app will be filed under it automatically.

If you skip this step, Magia will still create a workspace automatically the first time you open a session in that directory. The auto-created workspace is identical to a manually created one and can be renamed at any time.

3. Create a session

1. Press Cmd+N or click New Session in the sidebar.
2. In the Working Directory field, type or browse to your project root.
3. Select a Provider — choose Claude Code if you installed it during onboarding.
4. Click Start Session.

The session opens in the main panel. The chat input bar appears at the bottom, the editor panel fills the center, and the terminal is available below it.

4. Explain the project to the agent

Before asking the agent to make changes, orient it to your codebase. A short contextual prompt avoids the agent spending its first turn just reading directory listings.

Type something like:

This is a TypeScript Node.js API server. The entry point is src/index.ts.
It uses Express for routing and Prisma for the database. The main business
logic lives in src/services/. Tests are in tests/ and use Vitest.

Please explore the codebase and give me a brief overview of the architecture.

Press Enter to send. The agent starts immediately. As it runs, you will see tool cards appear inline in the chat — each file read, directory listing, and search is shown as a collapsible card so you can follow exactly what the agent is doing.

5. Let the agent explore the code

Watch the tool cards as they arrive:

• Read cards show the file path and a preview of the content the agent fetched.
• Bash cards show shell commands (like find or grep) and their output.
• Think blocks (if extended thinking is enabled) show the agent’s internal reasoning as collapsible sections.

Once the agent finishes its exploration turn, it returns a summary. Read it and use the context to formulate your next request.

6. Ask the agent to make a change

Now that the agent understands the project, ask it to implement something concrete:

Add an endpoint POST /users/:id/deactivate that sets the user's status
to "inactive" in the database and returns the updated user object.
Follow the same pattern as the existing endpoints in src/routes/users.ts.

The agent will read the existing route file, plan the change, then write the new code. You will see an Edit tool card as it modifies src/routes/users.ts (and any related files).

7. Review diffs in the editor

When the agent writes a file, the editor panel shows the diff before you accept it.

1. Click the file name in the tool card, or look at the editor panel — it will open the modified file automatically.
2. The diff overlay highlights added lines in green and removed lines in red.
3. Use the toggle in the file action bar to switch between Unified and Side-by-side diff views.
4. The git gutter in the editor shows colored bars for every changed line relative to HEAD — green for additions, amber for modifications.

If the change looks correct, leave it as-is. The file has already been written to disk. If you want to revert, use /rewind in the chat to roll back to the state before the agent’s last edit, or use git directly in the terminal.

8. Run tests in the terminal

Press `Cmd+“ (backtick) to open the integrated terminal. It starts in your project directory automatically.

Run your test suite:

npx vitest run

If a test fails, copy the error output and paste it into the chat:

The test tests/routes/users.test.ts is failing with this error:

[paste error output here]

Please fix it.

The agent will read the failing test, identify the issue, and apply a fix. Repeat the test run to confirm it passes.

9. What’s next?

• Pin this session — right-click it in the sidebar and choose Pin so it always appears at the top.
• Fork the conversation — use /fork to branch the session at any point and explore a different approach without losing your current history.
• Add more directories — use /add-dir in the chat to give the agent access to a second repo (e.g., a shared library) within the same session.
• Configure a CLAUDE.md — create a CLAUDE.md at your project root to give the agent permanent instructions about your codebase conventions. Use /memory in the chat to manage it.