Tutorial · Intermediate
Mastering Agent Mode
Agent Mode is where Starlight stops being a chatbot and starts being a coworker. Give it a goal, walk away, and come back to finished work. This guide covers how to write goals that work, read the progress output, and know when to step in.
What Agent Mode is - and isn't
Agent Mode gives Starlight a goal and lets it work autonomously inside its sandbox. It decomposes the task into steps, executes each one, tests the results, and reports back. It's not a chat - you don't watch it stream token by token. Instead, you give it the objective, and it works through the steps, logging progress as it goes. You can check in at any time, and it can run in the background on Nova.
Writing a good goal statement
The goal is the single most important part of using Agent Mode. A good goal is specific, has a clear definition of done, and includes any constraints. Bad: 'Build a website.' Good: 'Build a single-page portfolio website with a dark theme, three project cards, a contact form that posts to an API endpoint, and responsive mobile layout. Use plain HTML, CSS, and vanilla JavaScript - no frameworks. The contact form should validate email format before submitting.' The second one gives Starlight everything it needs to succeed without guessing.
What Starlight does autonomously
Once you give it a goal, Starlight runs through four phases on its own.
Decomposes the task
Starlight breaks your goal into a plan - files to create, assets to generate, code to write, tests to run. You can see the plan before it starts executing.
Executes in the sandbox
Each step runs inside the fully-instrumented sandbox. Compilers, engines, renderers, audio tools - Starlight knows where everything is and uses the right tool for each step.
Verifies its own output
Starlight doesn't just write code and hope. It runs it, tests it, profiles it, and checks the results against the goal. If something fails, it debugs and retries before showing you anything.
Reports back with receipts
When it's done (or stuck), you get a summary of what was accomplished, what files were created, test results, and any issues it couldn't resolve. Not excuses - receipts.
Reading the progress output
As Starlight works, it logs each step in a tree structure - similar to a build log. You'll see entries like 'generated fox.glb · rigged · 32 bones' or 'wrote 24 files · engine, shaders, gameplay' or 'ran playtest in sandbox · 60 fps · 0 errors.' Checkmarks mean a step passed; red markers mean something failed and Starlight is retrying. You don't need to read every line - scan for failures and the final summary.
When to intervene vs let it run
Agent Mode is designed to be hands-off, but there are moments to step in. If Starlight is stuck on the same step for multiple retries, it may need a hint - jump in with a message and it'll incorporate your guidance. If the plan looks wrong before execution starts, edit it. Otherwise, let it work. The self-verification loop is there for a reason: Starlight catches most of its own mistakes before you'd notice them.
Long-running background agents (Nova)
On the Nova plan, agents can run in the background and survive disconnects. Start a job on your desktop, close your laptop, and come back to finished work. Cross-device continuity means the session state follows you - pick up where you left off from any device. This is ideal for large builds, multi-file refactors, and tasks that generate many assets.
The best agent goals read like a brief from a trusted colleague - clear, specific, and with a definition of done that anyone could check.
Starlight Team
Try Agent Mode
Agent Mode is available on paid plans. Start with a small goal - like building a single utility script with tests - and scale up from there.