> ## Documentation Index
> Fetch the complete documentation index at: https://docs.magnet.run/llms.txt
> Use this file to discover all available pages before exploring further.

# Session Lifecycle

> A walk-through of each phase in a Magnet session — from creation through agent execution to pull request creation.

## 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](/api-reference/sessions/create-session).

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.

<Tip>
  You can send follow-up messages to the agent while it's working to provide additional context or adjust direction.
</Tip>

## 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.

<Tip>
  Failed sessions still preserve their full conversation history, so you can understand what happened and retry with an adjusted prompt.
</Tip>

## Next steps

<CardGroup cols={2}>
  <Card title="Sessions Overview" icon="layer-group" href="/sessions/overview">
    High-level view of sessions and their capabilities.
  </Card>

  <Card title="Create a Session" icon="plus" href="/api-reference/sessions/create-session">
    Create sessions programmatically via the API.
  </Card>
</CardGroup>