---
title: "The terminal UI · Alran Code Docs"
url: https://alran.dev/en/docs/tui
locale: en
updated: 2026-11-16
---

[Docs](https://alran.dev/en/docs)Working with Alran

# The terminal UI

Run `alran` in a project folder. Everything happens in one screen: the conversation, the plan, the work and the status.

On this page

[What does the terminal UI show?](#screen) [Shortcuts](#shortcuts) [Steer while it works](#steer) [Files and context](#context) [Look and feel](#look) [Lightweight conversations](#lightweight) [Common questions](#faq)

## What does the terminal UI show? {#screen}

- **The conversation.** Your message, Alran's answer and every step it takes: files read and written, commands run, with their output one keystroke away (Ctrl+O).
- **The to-do list.** For work with several steps, Alran keeps a list and ticks items off as it goes. Ctrl+T makes it compact.
- **The composer.** Where you type. It stays usable while Alran works.
- **The status line.** Folder, Git branch, permission mode, model, effort and how much context is left. Choose its items with `/statusline`.

## Shortcuts {#shortcuts}

| Action | Shortcut |
| Send a message, or steer the running task | Enter |
| Queue a follow-up while a task runs | Alt+Enter |
| New line | Shift+Enter |
| Reference a file or folder | @ |
| Plan Mode on or off | Shift+Tab |
| Switch the permission mode | Alt+M |
| Show details of the last steps | Ctrl+O |
| Close a panel or stop the running task | Esc |

`/hotkeys` shows every shortcut and lets you change them.

## Steer while it works {#steer}

You never have to wait. Enter sends a message into the running task and Alran takes it into account at the next step. Alt+Enter queues a message for when the current answer is done; `/queue` manages the queue. `/btw` asks a side question in a separate conversation without interrupting the work.

## Files and context {#context}

Type @ and pick a file or folder to point Alran at it. `/add-dir` adds another readable and writable folder to the session. `/context` shows how much of the context is used; long sessions are compacted automatically, or by hand with `/compact`.

## Look and feel {#look}

`/theme` chooses the colour theme, `/settings` the TUI mode (regular or fullscreen) and other preferences. `alran --tui-mode fullscreen` starts in fullscreen.

## Lightweight conversations {#lightweight}

For a quick question that needs no files or tools:

```bash
alran --mode lightweight "Explain how DNS caching works."
```

Lightweight sessions send a small prompt and no tools, so they cannot read or change your files.

## Common questions {#faq}

What does the terminal UI show?

The screen has four parts: the conversation with your message, the answer and every step Alran takes, the to-do list for work with several steps, the composer where you type, and the status line with folder, Git branch, permission mode, model, effort and how much context is left.

How do I steer Alran while it is still working?

Press Enter to send a message into the running task, Alran takes it into account at the next step. Press Alt+Enter to queue a message for when the current answer is done.

How do I point Alran at a file or folder?

Type @ and pick the file or folder you mean. The command /add-dir adds another readable and writable folder to the session.

[PreviousSign in and accounts](https://alran.dev/en/docs/auth) [NextPlan Mode and permissions](https://alran.dev/en/docs/plan-mode)
