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

# Using Sessions

> Work with an Expert in a conversation — where you give the agent a task, watch it run and follow every turn.

## About sessions

A Session is a conversation with a specialized agent, called an Expert. The Expert supplies the instructions, model, and capabilities (e.g. integrations with Slack, Linear or Jira); the [Environment](/cosmos/environments/overview) supplies the machine where the agent reads your repositories, runs commands, and executes tools. The Session is where the two meet, and where you work with the agent on a single task.

Every message, agent turn, and tool call in that conversation belongs to the Session. A Session can be private to you or shared with your organization — see [Share a session](#share-a-session). You can open Cosmos at [cosmos.augmentcode.com](https://cosmos.augmentcode.com) in any browser, including the one on your phone; there is no separate iOS or Android app. You can also work with a Session from Slack when your administrator has connected Slack under **Settings** → **Integrations** and the Expert you're using supports it.

<CardGroup cols={2}>
  <Card title="Core concepts" icon="cube" href="/cosmos/getting-started">
    How Experts, Environments, and Sessions fit together.
  </Card>

  <Card title="Environments" icon="server" href="/cosmos/environments/overview">
    The machine an Expert runs on during a Session.
  </Card>
</CardGroup>

## Start a session

<Steps>
  <Step title="Inside the sidebar">
    **New Session** creates a new conversation and **Sessions** allow you to see all current and archived Sessions. Once opened, Recent Sessions will appear here as well. All three sit at the top of the sidebar.
  </Step>

  <Step title="Start from Home">
    You can quickly start right from Home, first choose the Expert you want, and describe your task in the prompt box at the bottom of the page.
  </Step>

  <Step title="Revisit past Sessions">
    Select **Sessions** to see every Session you can access. Open one to pick up the conversation where you left off.
  </Step>
</Steps>

## Write and send a prompt

Once inside the Session, the prompt box sits at the bottom of the window. Type your prompt in the input — it reads `Ask anything or type / for commands` when empty — and press **Enter**. Type `/` to run a slash command.

<Note>While the agent is working you can keep typing. Your next message is queued and sent when the current turn finishes.</Note>

```text Example theme={null}
Select: Cosmos Advisor
Prompt: Help me create an Environment for a Ruby on Rails project. I want to use the Ruby 3.4 and Sqlite3.
```

## Attach files and images

Give the agent more context by attaching files or images to a prompt:

* **Attach files**: select the attach control next to the composer and pick files from your machine.
* **Drag and drop**: drop files or images onto the composer.
* **Paste**: paste an image straight from your clipboard.

Attached images appear as thumbnails below your text. Remove one by hovering it and selecting the remove control.

<Note>You can attach up to 10 files and up to 10 images per message. Files can be any type, up to 4 MB each and 4 MB combined. Images can be up to 10 MB each, in PNG, JPEG, GIF, WEBP, HEIC, HEIF, or AVIF format. If an attachment is too large or unsupported, the composer shows an inline message and skips it.</Note>

## Enhance your prompt

Select the **Enhance prompt** button — the sparkle icon next to the composer — or press **⌘E** (**Ctrl+E** on Windows and Linux) to rewrite a short prompt into a fuller one grounded in your conversation and codebase. The button stays disabled until you type something. Press **⌘Z** / **Ctrl+Z** to restore your original text.

## Pin a session

Under Recent Sessions, you can click the three dot overflow menu or right click to Pin session. Pinning keeps a Session within reach at the top of the sidebar. Drag pinned Sessions to reorder them within the section. Just to the right of Pinned menu is a set of hover tools that allows you to create Folders to organize your pinned Sessions, Filter pinned Sessions, and collapse all open folders.

<Note>Pinned Sessions are scoped to your account. They appear in your sidebar only — pinning a Session doesn't change what your teammates see.</Note>

You can unpin Sessions using the same three dot overflow menu or right click to Unpin session.

## Session lifecycle

A Session's conversation is saved indefinitely — it doesn't expire. Reopen it from the **Sessions** page at any time to pick up where you left off.

The Environment behind a Session is more short-lived. It pauses after a period of inactivity, and runs for up to 24 hours at a time. When you return to a paused Session and send a message, Cosmos restarts the Environment automatically — you don't need to resume it yourself — and the status shows it starting up. Your conversation is always preserved; if an Environment has been paused for a long time, it may restart from a clean state and lose uncommitted changes in its workspace.

<Note>Sessions started by a trigger or automation may be archived automatically once the agent finishes its task. Archiving preserves the full conversation, so you can still open the Session later.</Note>

## Share a session

Every Session has a visibility:

* **Shared** — everyone in your organization can open it.
* **Private** — only you can open it. Private Sessions show a lock badge.

The default depends on how the Session started: Sessions launched from an Expert that's shared with your organization, or by a trigger or automation, default to **Shared**, while Sessions launched from a personal Expert default to **Private**.

To give specific teammates access, open the Session and select **Share** in the Session header. From the Share dialog you can search for a teammate, grant them viewer access, copy a link to the Session, and revoke access later. Sharing with individual teammates is available to the Session's owner.