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

# Sessions Overview

> Understand how Magnet sessions work — from creation to completion, including real-time streaming and pull request integration.

## What is a session?

A **session** is the core unit of work in Magnet. It represents a single AI coding task: a prompt given to Claude Code, executed in an isolated cloud sandbox, with full conversation history and optional repository integration.

Sessions are scoped to your workspace and attributed to the user who created them.

## How sessions work

<Steps>
  <Step title="Create a session">
    Start a session from the Magnet UI or the API. Provide a prompt describing what you want the agent to do, and optionally link a GitHub repository.
  </Step>

  <Step title="Agent executes">
    Claude Code runs in an isolated sandbox. It can read and write files, run shell commands, search the codebase, and make git commits — all streamed to you in real time.
  </Step>

  <Step title="Review the results">
    When the agent finishes, it opens a pull request with its changes. Review the diff in Magnet or directly on GitHub.
  </Step>
</Steps>

## Session status

Every session has a status that tells you where it is in its lifecycle:

| Status        | Meaning                                                                                          |
| ------------- | ------------------------------------------------------------------------------------------------ |
| **Active**    | The session is in progress — the sandbox is starting, cloning the repo, or the agent is working. |
| **Completed** | The agent finished successfully. If a repo was linked, a PR is usually open.                     |
| **Failed**    | Something went wrong during execution. Check the session for error details.                      |

## Repository integration

Sessions can optionally be linked to a GitHub repository:

* **Cloning** — the sandbox clones the repo at the branch you specify
* **Branching** — the agent creates a working branch for its changes
* **Pull requests** — when done, the agent opens a PR against the base branch
* **Status tracking** — PR status is synced back to the session

## Real-time streaming

While a session is running, you can watch the agent work in real time. The Magnet UI streams:

* **Agent thinking** — Claude's reasoning as it plans its approach
* **Code changes** — file edits and new files as they're written
* **Tool usage** — shell commands, file searches, and other actions
* **Progress updates** — status changes as the session moves through its phases

## Next steps

<CardGroup cols={2}>
  <Card title="Session Lifecycle" icon="arrows-spin" href="/sessions/lifecycle">
    Detailed walk-through of each phase from creation to completion.
  </Card>

  <Card title="Sessions API" icon="code" href="/api-reference/sessions/list-sessions">
    Create and manage sessions programmatically.
  </Card>
</CardGroup>