Recipes and gotchas

Apply practical Neroli workflows for parallel agents, isolated environments, browser verification, Cloud handoff, review, and common setup gotchas.

These are the workflows that make Neroli feel different from scattered terminal tabs. Start with the one that removes the most friction from your current repo.

Isolated dev sessions

Use this when parallel agents need to run the app, database, or test stack at the same time.

Prepare the session

Copy .env.local or generated config into the session without committing secrets.

Assign unique ports

Give each session its own frontend, backend, database, queue, or simulator ports.

Isolate services

Use a unique Docker project name, database name, schema, cache prefix, or local data directory for each session.

Expose Run and Stop

Pin Run in the toolbar and add Stop behavior so the session can clean up after itself.

Add Verify

Give humans and agents one command that proves the session is ready for review.

Create Neroli automations for isolated dev sessions.

Prepare should copy env files safely, assign unique ports, and create isolated
Docker/database state. Run should start the app from this session. Stop should
tear it down. Verify should run the checks we use before review.

Parallel feature work

Use this when you want several directions explored without mixing files.

Start one session per feature, fix, experiment, docs update, or review.
Give each session the context and outcome it needs.
Move planning work into Planning and active work into In Progress.
Let sessions run in parallel while Neroli tracks which ones need input.
Move substantial candidates to In Review and ask each agent to self-review.
Put validated candidates in Merge, then move them to Done or archive them.

Top-bar command

Use this when you repeat the same command while working in sessions.

Choose the command

Start with a repository-real build, test, lint, run, or verification command.

Create the action

Create a manual Workspace Command and enable Show in top bar.

Choose its prominence

Turn on Pinned for frequent actions. Leave it off to keep the command in the top-bar overflow menu.

Run it in context

Open a session and launch the command from its top bar so it runs in that worktree.

Create a Neroli Workspace Command named Verify that runs the repository's normal
checks, show it in the session top bar, and leave it unpinned.

Browser verification

Use this when an agent changes a visible web flow.

Start the app from the session

Use the session’s Run automation so the browser points at the right worktree.

Open the attached browser

Keep the page in a Neroli pane so the agent and human are looking at the same UI.

Ask the agent to verify

Have it inspect the page, click through the changed flow, check console or network evidence when useful, and report what it saw.

Review the evidence

Use the browser state, screenshots, logs, and diff together before merging.

Verify the UI change in the attached Neroli browser.
Use the session's Run automation if needed, inspect the changed route, capture
what you saw, and tell me any console, network, or visual issues.

Cloud handoff

Use this when a session should keep running away from your Mac, or when you want more agents moving at once.

Start local

Get the session into a useful state locally first. The handoff snapshot includes conversation context, file edits, and workspace state.

Check setup

Make sure the workspace knows how to install, build, run, and verify itself without hidden local state.

Move to cloud

Send the session to cloud and keep watching status in Neroli.

Bring it back

Move the result local, run verification from the session, and review before merging.

Agent self-review

Use this before you read the diff yourself.

Review your own work before I merge it.

Summarize what changed, inspect the diff for unrelated edits or risky files,
run the relevant checks from this session, fix anything obvious, and tell me
what still needs my attention.

Good self-review includes the changed behavior, verification result, known risks, and any files you should inspect manually.

Keep artifacts reviewable

Use this when agents generate docs, images, PDFs, spreadsheets, notebooks, or other output files.

keep source-code edits in Changes
keep generated outputs visible as artifacts
ask the agent which artifacts are final and which are scratch
open important artifacts in a file viewer before merging
ignore bulky build outputs unless they are intentional deliverables

Gotchas

Gotcha	What to do
Ports collide across sessions	Assign ports in Prepare instead of hardcoding them.
A command ran from the wrong repo	Run it from the session pane or session automation.
Verify passes outside Neroli but fails inside	Compare env, paths, generated files, and session setup.
Browser looks stale	Restart the session’s Run action and reload the attached browser pane.
Browser verification used the wrong app	Start the app from the session’s Run automation, then reload the attached browser.
Cloud fails during handoff	Read the recovery message, then fix setup, auth, network access, or pending sync.
Simulator or preview missing in cloud	Keep that work local; those panes depend on your Mac.
Generated files are noisy	Keep build outputs ignored unless they are real review artifacts.
Two sessions edit the same area	Review them in sequence and merge deliberately.
The board is crowded	Move validated work to Done, then archive sessions you no longer need.
A session repeats the same manual work	Add a top-bar Workspace Command.
Provider auth is missing	Sign in to the provider locally, then start a new session.
Secrets appear in a diff	Stop and remove them before review. Automations should copy secrets, not commit them.

When to add an automation

Add one when you repeat a task more than twice, when agents keep asking how to run something, or when a setup mistake blocks parallel work.

Good automation names are clear and obvious: Prepare session, Run dev, Stop, Build, Verify, Improve automations, Update docs.