Skip to main content

​
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 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. You can open Cosmos at 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.

Core concepts

How Experts, Environments, and Sessions fit together.

Environments

The machine an Expert runs on during a Session.

​
Start a session

1

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

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

Revisit past Sessions

Select Sessions to see every Session you can access. Open one to pick up the conversation where you left off.

​
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.
While the agent is working you can keep typing. Your next message is queued and sent when the current turn finishes.
Example
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.
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.

​
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.
Pinned Sessions are scoped to your account. They appear in your sidebar only — pinning a Session doesn’t change what your teammates see.
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.
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.

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