> ## Documentation Index
> Fetch the complete documentation index at: https://neroli.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Start

> Open Neroli and get into the agent flow quickly.

Open the app, pick a repo, choose your agent, and keep moving. The first win is
simple: get one useful agent session running without leaving a trail of terminal
tabs behind.

<Frame caption="The first-run flow is repo, provider, session, panes, and work in motion.">
  <div className="not-prose rounded-xl border border-dashed border-gray-300 bg-gray-50 p-8 text-center text-sm text-gray-600 dark:border-gray-700 dark:bg-gray-900 dark:text-gray-300">
    Placeholder image: Neroli opening into a repository with New Session, provider picker, TUI pane, and session status visible.
  </div>
</Frame>

## Install and connect

You need:

* macOS 15.6 or later
* a local Git repository
* at least one coding agent, such as Claude Code, Codex, or OpenCode
* GitHub authentication if you open pull requests from your workflow

Open Neroli, choose a repository, and start a session with the provider you want
for that job. The app creates an isolated workspace for the run and launches the
provider TUI directly inside the UI.

## The first loop

<Steps>
  <Step title="Open a repo">
    Neroli turns the repository into a workspace for sessions, panes, automations, and cloud handoffs.
  </Step>

  <Step title="Launch an agent">
    Start Claude, Codex, OpenCode, or another provider from a new isolated session. Mix providers when different jobs need different strengths.
  </Step>

  <Step title="Stay in the real TUI">
    Use the provider interface directly inside Neroli, with the same behavior and new features you expect from the terminal.
  </Step>

  <Step title="Add panes as needed">
    Attach terminals, browsers, simulator, diffs, file viewers, and generated artifacts to the session instead of juggling separate windows.
  </Step>

  <Step title="Run more sessions">
    Spin up more agents for features, experiments, cleanup, docs, or review without mixing their files.
  </Step>
</Steps>

Neroli keeps attention visible as work runs. You can see which sessions are
running, which ones need approval or input, which checks failed, and which work
is ready to review.

## Your first hour

Use the first hour to make the workspace feel smooth. You can add deeper setup
later.

<Steps>
  <Step title="Run one real task">
    Start with a task you would have given an agent anyway. Watch how the TUI, worktree, panes, and status stay together.
  </Step>

  <Step title="Add one verification pane">
    Open the browser for a web flow, the simulator for an iOS flow, or a diff/file viewer for generated output.
  </Step>

  <Step title="Create Run and Verify">
    Add the two automations you will use constantly: one to start the app, one to check the work.
  </Step>

  <Step title="Start a second session">
    Run a docs update, review pass, experiment, or test improvement in parallel so the isolation becomes obvious.
  </Step>

  <Step title="Move sessions on the board">
    Use Planning, In Progress, In Review, Merge, and Done to track where each session stands.
  </Step>

  <Step title="Ask for self-review">
    Have the agent summarize the change, run checks, inspect its diff, and fix obvious issues before you review.
  </Step>
</Steps>

## A simple prompt

```txt theme={null}
Implement the new billing banner.
Use the existing design system and run the relevant checks when done.
```

Add screenshots, routes, logs, or files when they help. Neroli's job is to keep
the session organized while the agent works.

## Make the workspace better

Manual launch is enough for day one. Once a repo becomes a workspace, add
automations that prepare sessions, copy env files, assign ports, run dev
servers, stop stacks, verify changes, and launch agentic helpers.

You can ask an agent to set those up. The Neroli CLI is mostly for agents and
automations, so they can discover the current session, panes, browsers,
simulator, and existing actions without guessing.

Next: understand the core model in [Concepts](/docs/concepts), manage parallel work
with the [Session board](/docs/sessions), then make every new session easier with
[Automations](/docs/automations).