Sessions

Open a session to work with one agent. Atlas records the conversation as a session, including its file reads, commands and edits.

This page is about working with an agent. To message your teammates, see Team chat.

Start or resume a session

Choose New session at the top of the sidebar, or press ⌘N, to start a session. It opens in the main column. To run a second session beside it, press ⌘T then A, which opens one in the surfaces pane.

When you reopen a session, Atlas paints the transcript from disk while the agent reconnects.

Atlas Agent needs an organization that is synced to your account and has AI access. If the composer says so instead of letting you type, see AI access & spend.

Find your sessions in the sidebar

The sidebar lists your sessions across every project in the organization, newest activity first, with each row's project, branch and status. ⌘⇧. or ⌘⌥J shows or hides it. Search for a session with Search sessions at the top of the sidebar.

• The project picker at the very top narrows the list to one project. It shows All projects or the chosen project's name, and stays set until you change it. Sessions the chosen project is attached to are listed too, marked attached. Its menu lists the organization's projects, with a search field once there are more than six; right-click a project, or click its gear, to open its settings. It also holds Add project, Import sessions from agents… and, at the bottom, the organization (see Organizations). The magnifier beside it opens the command palette. A project shows its own icon wherever it appears, the favicon or app icon Atlas finds in its folder, or a coloured two-letter tile when it has none.
• Search below it finds a session by title, project, attached project or branch. Use the arrow keys to move through the results and Enter to open one.
• Pinned sessions stay at the top. Drag a pinned session to reorder it, drag it down into the list to unpin it, or drag a session up onto the pinned ones to pin it.
• Unread sessions are marked when an agent finishes a turn you haven't seen.
• Snoozed sessions move to the Snoozed shelf, above Settled, until the time you picked, then come back to the list marked Woke. The shelf is collapsed until you open it and shows its count; each row there shows how long until it wakes, and Wake brings it back now. Undo in the notice after snoozing puts the session back as it was, without the Woke mark.

A session with attached projects shows their initials stacked after its project's badge, two at most and … past that; their names are in the badges' tooltip.

A session with linked pull requests shows the first one's state and number, then +2 for two more. Hover the badge to list every one with its state and checks, and click one to open it. Search finds a session by its pull request's number or title too.

Rest the pointer on a session for a moment to see its project, the projects attached to it with their access, agent and model, branch and pull request, whether it is shared with the team, and how many comments it has. Use ↑ and ↓ to move between sessions and Enter to open one.

Hover a session to Snooze or Settle it. Right-click it for everything else:

• Pin or Unpin
• New session on its branch. For a session in a worktree, the new session starts in that worktree. Otherwise Atlas checks the branch out in the project first, and refuses if the project has uncommitted changes or an agent is working there, in Atlas or in a terminal, offering to start on the current branch instead.
• Settle or Unsettle
• Snooze, for a preset time or a custom one, or Wake session on a snoozed one
• Rename
• Mark unread or Mark read
• Filter by its project
• Link a pull request…, and Unlink pull request once one is linked
• Copy its title, path, branch or session ID
• Open in your editor
• Project settings
• Delete

Settle a session

Settle a session when you are done with it for now. Hover it and choose Settle, or press ⌘⌥S on the open one. It moves to the Settled shelf at the bottom of the sidebar and the next session opens; Undo in the notice brings it back. Sending a message to a settled session moves it back to the list. Atlas also settles sessions that have been idle for 3 days, but never one that is running or waiting for you. A session that wakes from a snooze, or that you unpin, gets the full 3 days again before it is settled. Change the number of days, or turn it off, with Settle idle sessions after in Settings → Sessions.

The Settled shelf is collapsed until you open it. It has its own search, and Show more pages through older sessions. A settled session that is open or running stays visible even while the shelf is collapsed.

Bring in sessions from your agents

Open the project picker at the top of the sidebar and choose Import sessions from agents… to pull in sessions an agent kept on its own, such as ones you ran in a terminal. Imported sessions land on the Settled shelf.

Atlas asks each installed agent for its session list. An agent that cannot list its sessions still appears, grayed out, with the reason.

Choose and switch agents

Choose the agent from the composer, or press ⌥/ to cycle through them. A new session starts on the agent you last picked, as long as it is still installed. To always start on one agent, turn off Start with the last agent you picked in Settings → Sessions and choose a Default agent. A session belongs to one agent, so what happens when you switch in a session that already has a conversation depends on Switching agents in a session in Settings → Sessions:

• Start over switches in place with a clean session. This is the default.
• New tab keeps the conversation on screen and opens the new agent beside it.
• Hand off switches in place and attaches the conversation to your next message, so the new agent picks up where the last one stopped.

Every conversation stays in your history either way. Turn on Save to memory before switching agents to have the agent you are leaving save what it learned to shared memory first.

Give the agent direction

The composer shows the controls the connected agent advertises, such as the permission mode, model and reasoning effort. Press ⇧Tab to cycle the permission mode.

Enter sends and ⇧Enter or ⌃J adds a line. ⌘Enter always sends. To make Enter add a line instead, turn off Enter to send in Settings → Sessions.

While you read back through a session, an empty composer folds to one line, with its toolbar tucked underneath, so the conversation gets the room. Click it, focus it or start typing and it opens again. The toolbar's controls work while it is folded.

Lists continue on their own. On a line that starts with - , 1. , - [ ] or > , a new line carries the marker over, and a numbered list renumbers. A new line on an empty item ends the list. Tab and ⇧Tab nest and unnest a list item; ⌘] and ⌘[ indent any line.

Add context

Type @ to mention context: files, folders, symbols, knowledge notes, pack components, repositories, other projects, branches, and earlier messages or sessions. In a project shared with your organization through cloud capture, you can also mention teammates, team conversations, recorded sessions and comments. Atlas shows larger references below your message so you can see what the agent receives.

Paste more than 4,000 characters or 80 lines and the text becomes a chip in the composer, so your message stays readable. The agent still receives all of it, and editing a queued message keeps the chip.

Paste, drop or pick an image and it becomes a chip in your sentence, with its name and size, and a thumbnail above the field when the agent accepts images. The two are one attachment: remove either and the other goes with it. A pasted screenshot is saved to a file first, so the agent gets the picture and a path it can open at full size.

The + button in the composer adds context too:

• Add files, or Add files or photos when the agent accepts images
• Attach media, including Take a screenshot of a region or the whole desktop
• Add from GitHub to clone a repository for reference
• Attach a session to bring in an earlier session
• Reference project to point at another project

Attach other projects

A session can work in folders besides its own. When you mention another project or a repository, or clone one with Add from GitHub, Atlas attaches it to the session. An attached project stays with the session: it is still there on later messages and when you resume the session.

A project is attached read-only at first: the agent can read it but not change it. The chip in the composer shows the access. Click its eye icon to let the agent edit files there, and click the pencil to make it read-only again. Atlas tells the agent what it may do in each attached project.

Atlas Agent can write to a project from its next turn. Other agents get write access the next time the session is resumed, and Atlas says so when you grant it.

Atlas never attaches the root of your disk, your home folder, a system folder, or a settings folder such as ~/Library or ~/.ssh. On Windows that means any drive root such as D:\, C:\Windows, C:\Program Files, C:\ProgramData and your AppData folder.

Manage attached projects

The Projects section of the session details card lists the session's own project first, marked Main, then each attached project with:

• Its access: an eye for read-only, a pencil for read and write. Click it to switch.
• How it was attached, such as by a mention or an approved request, and when, in its tooltip.
• Its branch and uncommitted changes, when it is a git repository.
• ⋯: Open in your editor, Reveal in Finder, change its access, or Detach it from the session.

+ Attach project lists the organization's projects that are not attached yet, then Choose a folder… for any other folder. The folder rules above still apply. When an agent only takes the change on resume, the section says so.

In the composer, type @ and the attached projects come first, with their access.

When the agent asks for access

When code tools are on, an agent can ask to use a folder outside the session. Atlas shows the request in the session with the folder and the agent's reason. Choose Allow read and write, Allow read-only, or Deny. The agent is told your answer. If you approve after the agent has stopped waiting, the folder is still attached and the agent can use it once it asks again.

Run a command

Type / to run one of the agent's own commands or skills. The list is what the agent advertises, and Atlas sends the command through unchanged. The one command Atlas adds is /login, which opens the agent's sign-in.

Steer a running turn

Messages you write while an agent works join a queue. Edit or remove them before they run. Plans appear above the composer, and permission requests show the agent's own choices.

When Atlas Agent needs an answer to continue, it asks you in the session and waits.

Stop is always available. For a transient provider failure, Atlas shows the retry countdown and the reason.

If Atlas quits, crashes or restarts to update while an agent is in the middle of a turn, the next launch opens that session and tells the agent to continue where it left off. The transcript marks it with Atlas restarted and resumed this turn. Settled and snoozed sessions are left alone, and a turn that keeps getting cut short is let go after three tries in a row. Turn this off with Continue sessions after a restart in Settings → Sessions.

Review the result

While the agent works, the turn shows how long it has been working and what it is doing right now. A thought shows open while the agent is in it, its newest lines in view, and folds to one line once the agent moves on. A running command is named by its program, such as Running cargo. Calls to an MCP server are counted per server, such as "Used browser 2 times". When it finishes, its work folds behind Worked for and the time, leaving the answer in view. Each block of tool calls is summarised by what it did, such as "Ran 3 commands and read 2 files", and a call that failed stays in view after the fold. Select Worked for to see every step, with how long each one took. A turn you stop reads Stopped after instead, with the time it ran.

Every turn ends with a summary of how long it worked and the files it read or changed, with lines added and removed. When the turn touched attached projects, the files are grouped by project, each group with its own counts and paths shown from that project's root; files outside every project go under Other. Choose Show changes to open the turn's diff, or Save to keep the conversation as a knowledge base note.

The usage pill in the composer shows how full the agent's context window is, along with tokens and cost when the agent reports them.

With Next-step suggestions on in Settings → Sessions, the agent offers two or three follow-ups as chips after each turn. Click one to send it.

Work with messages

Hover a message, or Tab to it, to show the row of actions under it along with the time it was sent. Hover the time for the full date. On a response that changed files, the row sits under the changed-files summary, at the end of the response. Messages from a session the agent reloaded from its own history show no time, because the agent doesn't record one.

• Copy the prompt or response as markdown
• Retry your latest prompt to replace its response
• Pin a prompt or response, then find it again from the pin button in the title bar, or Pinned messages in the session's ⋯ menu. Pins are kept on your machine.
• Branch from here, on the latest response, copies the session into a new one when the agent supports it
• More (…) on a prompt holds Edit and send as new message, to rework it

File paths in messages appear as chips with your icon theme's file icons. That covers paths the agent writes, such as src/lib/api.ts:42, and the files and folders you mention with @. Select a chip, or press Enter on it, to open the file in a tab at the line it names. A path written without its folder opens the one project file it matches. In a session that works in its own folder, such as a pull request session's worktree, the agent's paths open in tabs too. A file you attached from outside the project opens in your preferred editor, or the app your system uses for it. The system app is used only for documents, images, media and plain text; anything it might run, such as a script, a .terminal file or a web shortcut, is shown in Finder instead. A folder or an app is shown in Finder, never run. Paths the agent writes, and paths in earlier messages or in text Atlas wrote for you (such as a pull request's check names), open only inside the project; outside it they are shown in Finder.

The same chips appear wherever Atlas renders Markdown that belongs to a project: plans, canvas notes, notebook text cells, the Markdown preview, a project's README, pull request descriptions and comments, and team chat. In team chat, a path becomes a chip only if it is in the project you have open. These chips open only files inside that project; a path outside it stays as plain text. The permission prompt never shows chips.

Web links are shown in a link colour, and are underlined when you hover or Tab to them. They show the service's icon before the link text: GitHub, GitLab, Bitbucket, Codeberg, Azure DevOps, Linear, Slack, Notion, Figma, Vercel and npm have their own, and other sites show a globe. A bare link to a pull request, issue, commit or repository, or to a Linear issue, is shortened to PR #42, #17, the short commit hash, owner/repo or ATL-978. An Azure DevOps work item is shortened to #17 and a repository to project/repo. Only dev.azure.com and *.visualstudio.com addresses get the Azure DevOps icon. A service's icon and the short label appear only for that service's own address, such as github.com or gist.github.com. Any other site keeps the globe, even when its name contains a service's, so github.evil-login.io never looks like GitHub. A pull request on another host, such as a self-hosted GitLab, is shortened with its host in front: git.acme.dev · acme/web PR #42. Hover the link to see the full address. Copied text includes the full address.

Select text in a response and choose Cite to point the agent at that passage. Add a note if you like, then Cite again to drop a chip into the composer. When you send, the agent gets the quoted passage (up to 2,000 characters) and your note. A cite is private to your agent. On a session shared with your organization, turn on Share with team to also post the passage and your note as a comment; a shared cite needs a note.

Search long sessions with ⌘F, or Search in session in the ⋯ menu at the right end of the title bar. The same menu filters the transcript to your messages or the agent's, and opens the Bash calls and Plans panels, which collect commands and plans without expanding the transcript. When the agent supports it, Branch from here in the same menu copies the session into a new one so you can try another direction.

Jump between turns

A column of short ticks down the left edge of a session marks its turns, one tick per prompt and the agent's reply. The ticks for the prompts on screen are brighter. Hover a tick to see its prompt and the start of the reply, and click it to jump there; the arrows above and below the column step to the previous or next turn. Tab to the column and use ↑, ↓, Home and End to move through turns, then Enter to jump.

The column shows once a session has two turns. In a long session the ticks move closer together rather than running off the screen. When the window is too narrow to leave room beside the conversation, the column appears only while you hover the left edge. Turn it off with Turn rail in Settings → Appearance.

Session details

The session's name shows once, in the title bar. The session's own controls sit at the right end of the bar: the ⋯ menu, and the session details button (≡). They show only while a session is open.

Click the details button, or press ⌘⌥B, for one card with where the session works and what it changed. When the window is wide enough, the card docks at the top-right of the session, in room the conversation already leaves for it. It shows there by default; hide it with the button and it stays hidden for that session. In a narrower window it opens as a popover under the button instead. Either way, showing or hiding it never moves the conversation or the composer. Press Esc to close the popover.

The card holds:

• The machine the session runs on. Hover it for the session's folder; right-click it to copy the path.

• Open in your editor: opens where the session works in your preferred editor, or the first one Atlas finds. The menu beside it picks which editor that is, Finder included, without opening anything. ⌘O does the same as the button. In a session that works in its own folder, such as a pull request's worktree, it opens that folder.

• Project scripts: named commands for the project, such as a dev server or the tests. Each shows its command beside its name. Click one to run it in a terminal where the session works; the menu lists them all, with a pencil to edit each. Choose Add project script to create one. Scripts are saved in the project's .atlas/config.toml, so they travel with the repository.

  Because anyone who can change the repository can change that file, a script you did not add in Atlas asks before its first run, showing the whole command. Choose Run script to run it; Atlas remembers your approval for that project and asks again if the command changes. Scripts you add or edit in Atlas don't ask.

• The branch, with a picker. Type to filter local and remote branches; choosing a remote one creates the local branch. Enter a new name and choose Create branch to create it and switch to it. Right-click the branch to copy its name.

• Pull requests: the ones linked to the session and the ones opened from the branch, the open one first with its number, its checks and whether Atlas watches it, and earlier ones behind Show more. Click one to open it. The open one offers the next step it is waiting on: Resolve for a conflict, Ready for a draft, or Merge once its checks pass (click Merge again to confirm). Right-click a pull request for the same actions as the session's pull requests tab, or Link to this session for one found on the branch.

• The git action the branch calls for, such as Commit, push & PR, Commit & push, Push, Pull or Create PR. When there is nothing to do it says why. Its menu holds Commit, Push and Create PR, each with the reason when it is unavailable.

  An action that commits asks for the message and lets you leave files out; Commit on new branch moves the work onto a new branch named from the message. An action that would push to the default branch, or open a pull request from it, asks first, and offers a new branch instead. While it runs, the row shows each step, the last line of output (a commit hook's, for instance) and how long it has taken; when it lands, a check says what happened. Create PR opens with the title and description the pull request would have, for you to edit before it is created.

• Changes: the lines added and removed since the branch left the default branch, uncommitted changes included. Click it to open the session's diff.

• Projects: the session's project and the projects attached to it (see Manage attached projects).

• Lineage: the session this one was branched from with Branch from here, the sessions branched from it, and the agents it delegated work to. Click a session to open it.

Everything in the card works on the session's own folder, so a pull request session's worktree shows and acts on its own branch. When the window is short, the card first drops the machine, Projects and Lineage, then Open in and the git action, before it scrolls. A git action that is running still shows.

Comment on a session

Comments live in the transcript. Click anywhere in a prompt or a response to start a thread about it; select a passage and choose Comment to start one about those words. The composer opens under the message. Enter posts, ⇧Enter adds a line and Esc puts it away. Each thread sits under its message with the passage it is about quoted and marked in the text above. Reply, resolve or reopen a thread from the thread itself; a resolved thread folds to one line. The hover footer under a message has a comment button too.

Every session can be commented on. On a session that is only on your machine, the comments stay there. When the session is shared with your organization through cloud capture, Atlas posts those threads to the team once, and from then on teammates can comment from the timeline and their comments appear on the matching messages as they arrive.

On a shared session, the session's page in the timeline lists every thread on it. Thinking steps and tool calls keep a comment button of their own, which shows when you hover them.

Next

• Git & Diff: review and commit the change
• Agents: choose and install an agent
• Team chat: talk to your teammates