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

# Sessions

> Create, rename, pin, close, restart and revive sessions.

## Create a session

Press `n` in Rakumux mode, click **+ New session**, or press `Enter` on a folder's or worktree's
header. Rakumux creates the session straight away with a generated name, selects it and puts you at
its shell prompt, with no naming dialog.

The session goes in the **current folder**: the folder of the selected session or header. A
single-folder filter takes precedence, and with no folder context the folder you started Rakumux in
is used. A session made in a folder the filter hides adds that folder to the filter.

For another folder, a program instead of the shell, or startup commands, use the command line:

```bash theme={null}
rakumux new --name tests --cwd ~/projects/api --cmd "cargo test"   # a shell that runs a startup command
rakumux new --name agent --detach -- claude                         # a program instead of the shell
```

`--detach` leaves the session running without attaching to it. See the [CLI reference](https://rakumux.com/docs/reference/cli.md).

## What a row shows

Each session in the list has three lines:

1. **The name**, with the time since it was last active and a status mark on the right. Signed in
   with [AI session titles](https://rakumux.com/docs/account/ai-titles.md) on, it's an AI title from what you asked the agent;
   the **↻** after a hovered name asks for a new one.
2. **The app**, running subagents (`◈ 3`) and what the session reported about itself.
3. **Where it works now**, with its git branch (`⎇ main`, or `⎇ @` and a short commit id when no
   branch is checked out): see [Where each session has worked](https://rakumux.com/docs/guides/session-list.md#where-each-session-has-worked).

Widen the list by dragging the line beside it to see more of each line.

## Status marks

The mark on the right of a row says how the session is doing:

| Mark | Meaning |
| - | - |
| spinner | Working, including while subagents run |
| `◐` | Waiting for you: a question or a permission request |
| `●` (amber) | Unread: a finished reply you haven't looked at |
| `○` (amber, fading) | Ready: you've read its last reply. It fades over the hour and the day after you read it |
| `●` | Running: a live program that isn't an agent |
| `✕` | Exited: the program ended; its last screen is kept |
| `○` | Dead: the terminal is gone, for example after a reboot |

Rows don't repeat the status in words; an ended session's row still says `exited · ⏎ restart` or
`dead · ⏎ revive`.

## Rename

Press `r` in Rakumux mode (`Ctrl-\ r` from inside the session), or run
`rakumux rename [<name|id>] <new name>`. Sessions you didn't name can get a better name
automatically: signed in, an [AI session title](https://rakumux.com/docs/account/ai-titles.md) from what you asked their agent,
or with your own key, [AI naming](https://rakumux.com/docs/agents/ai-naming.md). Automatic names never replace one you chose;
asking for a new title (the **↻** after a hovered session's name, or `s`) does.

## Pin

Pinned sessions lead their folder, and lead **Ready** under the Status tab.

* **With the mouse:** point at a session and a star shows just left of its name. `☆` pins it and the
  gold `★` unpins it, without changing the selection. This needs a terminal that reports pointer
  movement, as desktop terminals do, over SSH too.
* **With the keyboard:** `p` pins or unpins the selected session, on phones too.
* **From the command line:** `rakumux pin <name|id>` and `rakumux unpin <name|id>`.

The tab bar and Grid cards show `★` after a pinned session's name. Every window sees the same pins.

## Order

The list keeps its order: using a session never moves it, and a new session goes at the bottom of
its group, just above **+ New session**. Drag a session up or down (in the Tabs layout, drag its tab
left or right), or press `J` and `K`, to move it. It stays in its folder (or status, or app), and
among the pinned sessions or the others. Your order is saved in `~/.rakumux/config.json`.

## Close, exit and delete

| Action | What happens |
| - | - |
| End the program you're working in (`exit`, `Ctrl-D`, quitting the agent) | The session is deleted. |
| `x` (close) | Asks first, then ends the session's program. The session stays in the list as **exited**, ready to restart. |
| The program ends in the background | The session shows as **exited**, with its last screen kept. `Enter` restarts it in the same folder. |
| `d` or `dd` (delete) | Asks first, then removes the session and its saved scrollback for good. |

## Dead sessions and revive

A **dead** session has no terminal any more, for example after `rakumux daemon stop` or a reboot. Its
saved scrollback is shown dimmed, and `Enter` **revives** it: a new terminal in the same folder, its
startup commands run again, and an agent picks up where it was.

* **Claude Code, Codex and OpenCode** resume the same conversation, with the flags they were started
  with.
* **Other programs** have their last command typed at the prompt, but not run.

After a crash or a reboot the server revives the sessions that were running by itself. See
[Restarts and recovery](https://rakumux.com/docs/guides/recovery.md).

## Running Rakumux inside a session

You can run Rakumux inside one of its own sessions, for example over SSH from a session on another
machine. That session is marked as the current one and can't be opened from inside itself.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.