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

# Introduction

> Tokenmaxxing without the chaos.

Neroli is a blazing-fast Mac app for running coding agents in parallel without
turning your workflow into scattered terminals, mystery branches, and half-lost
agent chats. Bring Claude, Codex, OpenCode, or whichever provider you like. Use
one, switch between them, or run several at once.

Neroli does not try to replace your favorite agent. It sits one layer above it:
isolated sessions, session panes, workspace automations, and smooth
local-to-cloud handoff around the real provider TUIs. You keep the native agent
experience, full feature parity, and new provider features right away.

<Frame caption="Neroli turns one-agent-at-a-time coding into a fast parallel workspace.">
  <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: a Neroli workspace with several isolated sessions, direct TUI panes, Run and Build actions, and a Cloud handoff status.
  </div>
</Frame>

## Why Neroli exists

Coding agents are powerful enough to run more than one thread of work at a time.
The hard part is everything around them: isolation, visibility, setup, review,
handoff, and knowing which session needs you.

Neroli gives that work a home. Each agent gets a real workspace, direct provider
TUI, panes, automations, status, review, and optional cloud handoff.

It is built around a few ideas:

* **Provider freedom:** use the agents you already like, alone or side by side.
* **Sessions:** each agent run gets its own branch, worktree, panes, and state.
* **Direct TUIs:** Neroli runs the real provider interfaces instead of wrapping a stale subset.
* **Automations:** your workspace can set itself up, run, build, verify, stop, and improve.
* **Cloud handoff:** snapshot a session and keep it running elsewhere, then bring it back.

## What this unlocks

<CardGroup cols={2}>
  <Card title="Build in parallel" icon="git-branch">
    Run a feature, a test pass, a docs update, and an experiment without mixing files.
  </Card>

  <Card title="Keep context visible" icon="panel-right">
    Terminals, browser panes, simulators, diffs, artifacts, approvals, and status stay attached to the session.
  </Card>

  <Card title="Let agents use the workspace" icon="bot">
    Agents can inspect sessions, use attached browsers, run automations, and create better automations for next time.
  </Card>

  <Card title="Move without lock-in" icon="cloud-upload">
    Snapshot a local session into cloud, keep it running, then bring the result back to the same workspace.
  </Card>
</CardGroup>

## The flow

<Steps>
  <Step title="Launch fast">
    Open Neroli, choose a repo, and start a new session without fighting project setup or terminal sprawl.
  </Step>

  <Step title="Run agents in parallel">
    Dispatch multiple agents into isolated sessions so features, fixes, experiments, tests, and docs can move at the same time.
  </Step>

  <Step title="Watch what needs you">
    Neroli shows what is running, waiting for approval, blocked, failed, ready, local, or cloud.
  </Step>

  <Step title="Let the workspace run itself">
    Automations can copy env files, assign ports, start dev servers, run checks, stop services, and even suggest better automations.
  </Step>

  <Step title="Move work when needed">
    Handoff snapshots the session conversation, edits, and workspace state into cloud, then brings work back local when you want it.
  </Step>
</Steps>

## Read this way

<CardGroup cols={2}>
  <Card title="Start" icon="sparkles" href="/docs/start">
    Open the app, connect your agents, and launch your first session.
  </Card>

  <Card title="Concepts" icon="layers-3" href="/docs/concepts">
    Understand workspaces, sessions, worktrees, panes, and status.
  </Card>

  <Card title="Session board" icon="columns-3" href="/docs/sessions">
    Manage parallel sessions like a lightweight issue tracker.
  </Card>

  <Card title="Automations" icon="wand-sparkles" href="/docs/automations">
    Teach the workspace how to set up, run, build, stop, and improve itself.
  </Card>

  <Card title="Cloud" icon="cloud" href="/docs/cloud">
    Snapshot sessions into cloud, run more agents, and bring work back local.
  </Card>

  <Card title="Review" icon="git-pull-request" href="/docs/review">
    See what changed and choose what lands.
  </Card>

  <Card title="Recipes and gotchas" icon="list-checks" href="/docs/recipes">
    Set up isolated dev sessions, cloud handoff, self-review, and common fixes.
  </Card>
</CardGroup>

## What matters

* **Speed:** the app boots fast and gets you into a session quickly.
* **Provider choice:** Neroli is the layer on top, not the agent you must adopt.
* **Feature parity:** direct TUIs mean provider features work as soon as providers ship them.
* **Isolation:** sessions can experiment without colliding.
* **Visibility:** terminals, browsers, simulators, diffs, and artifacts stay attached to the session.
* **Automation:** scripts and agentic sessions can keep improving the workspace.
* **Portability:** work belongs to the workspace, not a single provider or runtime.

<Info>
  Neroli is local-first by default. Cloud is there when a session should keep running somewhere else.
</Info>