Concepts
Understand how Neroli keeps each coding-agent session, worktree, provider TUI, pane, automation, status, and review artifact together.
Neroli feels simple when you treat the session as the unit of work.
A session is not just a terminal tab. It is an isolated worktree, provider TUI, panes, status, automations, review state, and optional cloud handoff moving together.
Workspace, session, worktree, and Team
| Term | What it means |
|---|---|
| Workspace | A repository opened in Neroli. |
| Session | One agent run with its own branch, panes, status, and automations. |
| Worktree | The Git isolation boundary that keeps a session’s files separate. |
| Provider | The coding agent you choose for the session. |
| Team | Shared policy, Cloud setup, billing, and automation definitions for selected private repositories. |
This is what lets you run multiple agents without losing track of which files, commands, browser, or review belong to which job.
A Team does not create another checkout or make ordinary sessions collaborative. Sessions remain private to their creator. Only Cloud sessions linked to a shared Team automation are available to authorized teammates while they remain in Cloud. See Teams for the full privacy and lifecycle rules.
What belongs to a session
| Session piece | Why it matters |
|---|---|
| Provider conversation | The agent chat stays tied to the work it produced. |
| Worktree and branch | Files stay isolated until you choose what lands. |
| Panes | The browser, simulator, terminals, diffs, and file viewers stay with the task. |
| Automations | Run, Build, Verify, Stop, and setup happen from the right workspace. |
| Artifacts | Generated images, PDFs, markdown, notebooks, and spreadsheets stay reviewable. |
| Status | Waiting, failed, blocked, cloud, ready, and review states are visible. |
| Board group | Planning, In Progress, In Review, Merge, and Done keep many sessions manageable. |
Why direct TUIs matter
Neroli launches the real provider interfaces directly. That keeps the app fast and avoids a stale wrapper around your agents.
You still get the provider’s native behavior, shortcuts, auth, model features, and release-day updates. Neroli adds the workspace layer around it: isolation, visibility, automations, panes, review, and cloud handoff.
Session panes
Panes keep useful context attached to the work instead of scattered across your desktop.
| Pane | Use it for |
|---|---|
| Provider TUI | Talk to the provider you chose for the session. |
| Terminal | Run commands inside the session worktree. |
| Browser | Inspect the app, test flows, capture evidence, and let agents verify UI work. |
| Simulator | Work with the session’s dedicated iOS simulator. |
| Preview | Inspect generated previews and local app surfaces. |
| Diff viewer | Review changed files from the session. |
| File viewer | Open generated artifacts, markdown, images, PDFs, and text outputs. |
Status is part of the product
Neroli tracks whether a session is running, waiting for input, asking for approval, blocked, failed, ready for review, local, or cloud. The point is not to watch every token. The point is to know which session needs attention.
Agents can use the workspace too
The Neroli CLI is mostly for agents and automations. It lets them inspect the current workspace, attached panes, browser, simulator, known services, recent sessions, and saved automations. That is why you can ask an agent to run the browser, verify a UI flow, create setup automations, or analyze recent sessions without handing it a pile of local paths.
The useful habit
When you start a job, think in this order:
Pick the session
Start fresh for new work, or continue an existing session when the context already lives there.
Attach the right panes
Add the browser, terminal, simulator, diff, or file viewer that makes the work visible.
Use automations
Run the workspace’s setup, run, build, verify, and stop actions from the session.
Move the session
Use the sidebar board to reflect where the work actually stands.
Review before merging
Ask the agent to self-review, inspect the result, then decide what lands.
Next: organize parallel work with the Session board, then turn the model into repeatable workflows with Automations.