DEEN

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

What does the terminal UI show?

  • 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

ActionShortcut
Send a message, or steer the running taskEnter
Queue a follow-up while a task runsAlt+Enter
New lineShift+Enter
Reference a file or folder@
Plan Mode on or offShift+Tab
Switch the permission modeAlt+M
Show details of the last stepsCtrl+O
Close a panel or stop the running taskEsc

/hotkeys shows every shortcut and lets you change them.

Steer while it works

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

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

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

Lightweight conversations

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

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.