---
title: "Interactive sessions"
description: "Prompt, queue, steer, and resume Hoplite threads from the terminal."
canonical_url: "https://hoplite.sh/docs/cli/interactive"
markdown_url: "https://hoplite.sh/docs/cli/interactive.md"
---

# Interactive sessions
URL: /docs/cli/interactive
LLM index: /llms.txt
Description: Prompt, queue, steer, and resume Hoplite threads from the terminal.
Related: /docs/cli, /docs/cli/commands, /docs/threads/run, /docs/agent/models

# Interactive sessions

`hoplite` opens an interactive session in your terminal. The session is a Hoplite [thread](/docs/threads): the agent works in the project's cloud sandbox, and the conversation is saved in Hoplite, not on your machine.

The CLI connects while it starts. Before your first prompt, the footer shows the thread's model settings and a header above the composer names the project, repository, local branch, and workspace. A new session doesn't create a thread until you send a prompt, so nothing is recorded until then. Once the thread exists, the header adds an **Open in Hoplite ↗** link to it.

## The composer

Type a prompt and press **Enter**. The answer, tool calls, and file edits stream into the transcript. Edits show as red and green diffs under their tool row. While the sandbox starts, the footer shows the setup phase, such as **Starting sandbox**.

Type `/` to open the slash-command menu. It lists the built-in [slash commands](/docs/cli/commands) and the thread's [skills](/docs/cli/commands#skills). **Up** and **Down** recall your earlier prompts.

### Long pastes and attachments

A paste of more than 3,500 characters shows in the composer as a chip, such as **[Pasted text · 4,212 chars]**, and is sent as an attachment named `pasted-text.txt`, as in the web app. One **Backspace** removes the chip. A message can carry about 900 KB in total. A paste that would make it larger isn't added, and a notice gives its size.

Attachments show in the transcript as chips with their names, such as **[pasted-text.txt]**, for your messages and your teammates', when you resume a thread and in the queue. In terminals that support links, clicking a chip in the transcript opens the attachment. Opening it needs you to be signed in to Hoplite in your browser. **Ctrl+O** shows each attachment's name and link, since the thread doesn't store its text in the message.

### Queue or steer while the agent works

You can keep typing while a run is working:

| Key | What it does |
| --- | --- |
| **Enter** | Queue the message. It runs after the current run ends |
| **⌃↵** (Ctrl+Enter), **⌘↵** (Cmd+Enter), or **⌥↵** (Alt+Enter) | Steer: send the message into the current run right away |

Queued messages show above the composer, including messages your teammates queued on the same thread. Press **Up** to edit your newest queued message. While you edit it, **Enter** saves the edit, **Enter** on an empty composer deletes it, and **⌃↵** runs it now. If the message starts running before you save the edit, your text stays in the composer.

When no run is active, **Enter** and **⌃↵** both send the message, and **⌥↵** inserts a new line. The web app's version of these controls is described in [Run a thread](/docs/threads/run#send-messages-while-the-agent-works).

### Run a command in the sandbox

Start a line with `!` to run it as a shell command in the thread's sandbox, such as `!git status` or `!npm test 2>&1 | tail -20`. The composer shows a pink `$` marker and **! runs in the sandbox** while the line starts with `!`.

The command runs right away, even while the agent works; it isn't queued behind the run. It isn't sent to the agent or saved in the thread: only your terminal shows it. Its output shows in the transcript with standard error in its own color, then ✓ or ✗ with the exit code, and how long it took. Long output shows its first 20 lines; **Ctrl+O** shows the rest. Press **Esc** twice to cancel a command that is still running, which stops it in the sandbox too. **Up** recalls `!` lines like your prompts, and they are saved in your prompt history (`~/.hoplite/history.jsonl`). To keep a command out of history, for example one with a token in it, put a space after the `!` (`! export TOKEN=...`), as with bash's `HISTCONTROL=ignorespace`.

The sandbox starts with the thread's first prompt, so in a new session, send a prompt first. Commands run in a login `bash` at the repository root with the sandbox's base environment, not the project's secrets, and stop after 120 seconds. Avoid changing files the agent is working on. From outside a session, [`hoplite exec`](/docs/cli/commands#run-commands-in-the-sandbox) runs a command the same way.

### Open a shell in the sandbox

`/shell` hands your terminal to an interactive shell in the thread's sandbox, like `ssh`. Every key goes to the sandbox, including **Ctrl+C**. Type `~.` at the start of a line to come back to the session; replies and updates that arrived meanwhile show then. See [Open a shell in the sandbox](/docs/cli/commands#open-a-shell-in-the-sandbox) for the escapes and `hoplite shell`.

### Stop a run

Press **Esc** twice to stop the run you started. Queued messages still run afterwards. While a `!` command runs, **Esc** twice cancels that command first. `/stop` stops whatever is running on the thread, including a teammate's run.

### Approvals and questions

When a tool needs approval, an **Approval needed** card shows what the agent wants to do. For a file edit, the card includes the diff. Choose **Allow** or **Reject**. See [Approvals](/docs/threads/review#approvals) for how approval policies work.

When the agent asks a question, it shows as a question card. Answer it in the card, or press **Esc** to decline.

### Full transcript

The inline transcript keeps tool output short. Press **Ctrl+O** to open the full transcript, with complete diffs, long task lists, and every tool's output. Use **PgUp** and **PgDn** to scroll, and **Ctrl+O** or **Esc** to close it.

## Keyboard shortcuts

| Key | Action |
| --- | --- |
| **Enter** | Send, or queue while a run works |
| **⌃↵**, **⌘↵**, **⌥↵** | Steer the running run |
| **Shift+Enter**, **⌥↵** when idle, **Ctrl+J** | Insert a new line |
| **Up**, **Down** | Prompt history; **Up** edits your newest queued message while a run works |
| **Esc Esc** | Cancel a running `!` command, else stop your run; with neither, clear the draft |
| **!** at the start of a line | Run the line in the thread's sandbox |
| **Ctrl+O** | Open or close the full transcript |
| **Tab** | Switch between **Mine** and **Team** in the `/resume` picker |
| **Ctrl+A**, **Ctrl+E** | Move to the start or end of the line |
| **Ctrl+U**, **Ctrl+K**, **Ctrl+W** | Delete to line start, to line end, or the previous word |
| **Ctrl+Y** | Paste the last deleted text |
| **Ctrl+L** | Redraw the screen |
| **Ctrl+C** twice | Exit (`/quit` works too) |

## Resume a thread

Hoplite keeps the conversation, so you can continue any thread later. Resuming replays the thread's messages into the transcript.

| Command | Opens |
| --- | --- |
| `hoplite -c` or `hoplite --resume` | The latest thread you used in this repository |
| `hoplite -r` | A picker of your recent threads in this repository |
| `hoplite --resume ID` | The thread with this ID |
| `/resume` | A picker inside the session |

The `/resume` picker lists the project's threads from Hoplite. It opens on **Mine**; press **Tab** for **Team** to see your teammates' threads, and type to search. If Hoplite opens a teammate's thread only for its followers, the CLI tells you so; select it in `/resume` again to follow and open it.

`/new` and `/clear` start a new thread. `/rename TITLE` renames the current thread. Before the thread exists, the title is used for the thread that your first prompt creates.

The CLI stores no transcripts. It keeps a list of the threads you used in `~/.hoplite/threads.json` (ID, repository, title, last used), which `-c`, `-r`, and the offline picker use.

## Work with teammates

Threads are shared with your workspace. When a teammate opens the thread in Hoplite or in their own terminal:

- The footer shows who else has the thread open, in Hoplite or in a terminal, for example **Ada viewing** or **Ada, Bo viewing**. It says **Ada composing** while Ada is typing a message. Teammates see you the same way, as composing while your composer holds text.
- Their messages show with their name above the prompt card.
- Their messages and runs appear in your transcript live, between your own turns. The footer shows who is running, for example **Ada is running**.
- Their queued messages show above the composer next to yours.
- If their run fails, the failure card says it was a teammate's run.

`/stop` stops a teammate's run as well as yours; **Esc Esc** only stops your own.

## Model, reasoning, and speed

The footer shows the thread's model, reasoning level, and speed.

| Command | What it does |
| --- | --- |
| `/model` | Pick the thread's [model](/docs/agent/models). `/model MODEL` switches directly |
| `/reasoning` (or `/effort`) | Pick the model's reasoning level. `/reasoning LEVEL` sets it directly |
| `/fast` | Turn the fast (priority) speed on or off, for models that support it |

On a thread that already has messages, changing the model compacts the thread's context before the next prompt, as it does in the web app. The `/model` picker asks first, so you can switch and compact or keep the current model. `/model MODEL` switches at once and tells you afterwards.

## When a run fails

A failed run shows Hoplite's failure card: what went wrong, when a usage limit resets, and the actions available. Each action shows the command that takes it.

| Command | What it does |
| --- | --- |
| `/retry` | Retry the last failed run |
| `/retry hoplite` | Retry on Hoplite credits, when a linked subscription's usage limit was reached |
| `/continue` | Continue in a new thread |
| `/model`, `/reasoning` | Switch settings when the card suggests it |

Actions that lead to a page, such as **Add credits**, are links you can open in your browser. See [Retry a run](/docs/threads/run#retry-a-run) for what a retry does on the server.

## Offline and reconnecting

- **Hoplite can't be reached at startup** (connection refused, DNS, TLS, or a server error): one notice says so, and the CLI keeps retrying in the background. It tells you when the connection is back.
- **You send a prompt while offline**: the prompt is not queued. It fails at once and says it was not sent. Press **Up** to get it back.
- **The connection drops during a run**: the CLI reconnects, reopens the thread, and follows the run to its end. Press **Esc Esc** to stop waiting.
- **`/resume` while offline**: the picker falls back to the local thread list.

The work itself runs in Hoplite, so losing your connection or closing the terminal doesn't stop a run.

## Sitemap

See the full [sitemap](/docs/sitemap.md) for all pages.
Well-known sitemap: [/docs/.well-known/sitemap.md](/docs/.well-known/sitemap.md).