# Your first TUI session

Source: https://docs.ideharmony.com/getting-started/first-tui-session


**Outcome:** the Harmony TUI agent running in your own terminal, one completed
turn, and the same work visible from the desktop.

## Prerequisites

- Harmony installed
- [A provider connected](/docs/getting-started/connect-a-provider)

## 1. Launch it

From any terminal, in your project directory:

```powershell
nala
```

**Expected result:** the TUI opens with a composer, a transcript area, and a
header showing the session and route.

## 2. Learn four keys before anything else

| Input | Does |
|---|---|
| `/` | Opens the command list — 49 built-in commands |
| `@` | Mentions files, agents, and other entities |
| `#` | References tasks and artifacts |
| `!` | Runs a shell command directly |

Everything else can wait. These four are how you address the agent, your
repository, your work, and your machine respectively.

## 3. Send a turn

Type a real request and submit it:

```text
Summarize what this repository does, based on its README and package manifest.
```

**Expected result:** the header moves through its acknowledgement and thinking
states, tool activity appears in the transcript, and a response arrives.

> [!NOTE]
> The chrome is gated on real evidence: it shows Thinking once submission is
> acknowledged, and Ready or Failed only on terminal turn evidence. If it looks
> stuck, it is reporting that honestly rather than guessing.

## 4. Try a few commands

```text
/help
/tasks
/agents
/doctor
```

The full generated list is at [TUI slash commands](/docs/tui/slash-commands).

## 5. Hand off to the desktop

```text
/desktop
```

**Expected result:** the desktop opens attached to the same daemon, with your
session, tasks, and artifacts present.

**Verify** from a separate terminal:

```powershell
harmony tasks list
```

The task you created in the TUI is listed. Same daemon, same durable state,
different view.

## 6. Detach without stopping

```text
/detach
```

This leaves the session running. Reattach later with `/resume` or `/attach`.

> [!IMPORTANT]
> `/detach` and `/stop` are different. Detaching keeps the session alive;
> stopping cancels the in-flight turn; quitting ends your session. Reach for
> detach when you just want your terminal back.

## Common recovery

| Symptom | Where to go |
|---|---|
| `nala` opens a CLI, not the TUI | Confirm you are on a current preview build |
| Composer accepts input but nothing runs | [Provider problems](/docs/troubleshooting/providers) |
| Turn never reaches a terminal state | Check task state, then [daemon problems](/docs/troubleshooting/daemon) |

## Next

- [TUI overview](/docs/tui)
- [TUI slash commands](/docs/tui/slash-commands)
- [First orchestration run](/docs/getting-started/first-orchestration-run)