Session Lifecycle

​

Overview

A session goes through several phases during its lifetime. Understanding these phases helps you get the most out of Magnet and troubleshoot any issues.

​

Phase 1: Creation

Start a session from the Magnet UI or via the API. You can configure:

• Prompt — describe the task you want the agent to complete
• Repository — optionally link a GitHub repo for the agent to work in
• Base branch — the branch to base changes on (defaults to main)
• Model — which Claude model to use

Once created, the session appears in your dashboard with status Active.

​

Phase 2: Sandbox setup

Magnet provisions an isolated cloud sandbox for the session. If you linked a repository:

1. The sandbox clones your repo at the specified branch
2. GitHub credentials are automatically configured from your connected GitHub integration
3. Once ready, the agent begins working

If no repository is linked, the agent starts with an empty workspace.

​

Phase 3: Agent execution

This is the main phase where Claude Code works on your task.

​

What the agent can do

• Read files — inspect source code, configs, and documentation
• Write files — create new files or edit existing ones
• Run shell commands — execute build tools, tests, linters
• Search code — find relevant files and symbols across the codebase
• Make git commits — commit changes incrementally

​

Watching progress

The Magnet UI streams all agent activity in real time. You’ll see the agent’s thinking, code edits, and tool usage as they happen.

​

Phase 4: Completion

When the agent finishes its work:

1. If changes were made to a linked repo, the agent creates a branch and opens a pull request
2. The PR link appears in the session, and you can review the diff directly in Magnet or on GitHub
3. The session status moves to Completed

​

If something goes wrong

If an error occurs during any phase, the session status moves to Failed. Open the session to see the error details and the conversation history up to the point of failure.

​

Next steps