> ## Documentation Index
> Fetch the complete documentation index at: https://docs.luminy.tech/llms.txt
> Use this file to discover all available pages before exploring further.
# Agent Modes: Build, Plan, and Explore Your Codebase
> Luminy's three agent modes control how the AI approaches your tasks — making changes, creating a plan first, or exploring your codebase read-only.
Luminy runs an **agentic loop**: the model receives your message, reasons about what to do, executes tool calls (reading files, running shell commands, searching code), observes the results, and repeats — cycle after cycle — until the task is complete or you stop it. You control the character of that loop by choosing an agent mode. Each mode shapes how aggressively the agent acts, how much it reads versus writes, and whether it pauses for your approval before proceeding.
## The three agent modes
**Default mode.** The agent reads and writes files, runs shell commands, executes git operations, and searches your codebase. Use Build for any task where you want the agent to actually implement something — adding features, fixing bugs, refactoring, writing tests, or making multi-file changes.
The agent analyzes your request and produces a **structured todo list** of steps before writing any code. It lays out the full plan and waits for your review. Once you're satisfied, you can switch to Build mode to execute. Use Plan when a change is large enough that you want to understand and approve the approach before committing to it.
**Read-only mode.** The agent fans out lightweight sub-agents to read across multiple files and modules cheaply, then synthesizes a coherent answer. No files are modified. Use Explore when you want to understand unfamiliar code, trace a data flow, or answer a structural question without the risk of any changes being made.
For large refactors, use **Plan** mode first to review the full change before switching to **Build** to execute it. This two-step workflow keeps big changes reviewable and reversible.
## Sub-agents
In Explore mode (and during certain Build-mode tasks), Luminy can spin up **sub-agents** — lightweight agents that each run in their own isolated context. Sub-agents are read-only gatherers: they locate evidence across files, return code snippets and symbol references, and report back to the main agent, which synthesizes the findings.
Up to **3 sub-agents** run concurrently, allowing the agent to explore multiple independent areas of a codebase in parallel — for example, reading the database layer, the API layer, and the frontend components simultaneously rather than sequentially.
Sub-agent activity is shown directly in the chat: each invoke appears as a collapsible tool call with a **Compass** icon, so you can see exactly what each sub-agent was asked to do and what it returned.
Sub-agents operate as read-only gatherers — they locate and return evidence, but all judgments, edits, and final outputs are always produced by the main agent. Sub-agents never write files or run shell commands.
## The agentic loop
Every time you send a message, Luminy begins an agentic loop:
The model reads your message and the current conversation history, thinks about what it needs, and decides on a next action.
The agent executes a tool call — reading a file, running a search, writing code, executing a shell command, or invoking a sub-agent.
The result of the tool call is returned to the model. It evaluates the output and decides what to do next.
The loop continues — reason, act, observe — until the task is complete, the agent reaches a natural stopping point, or you intervene.
Each iteration of the loop is visible in the chat as a sequence of tool call blocks, so you can follow exactly what the agent is doing at every step.
## Stopping the agent
A red **Stop** button appears in the input area while the agent is running. Clicking it halts the current run immediately at the end of the active tool call. Any file changes already written to disk are preserved — stopping the agent does not undo work that has already been completed.
## Clarification
When the agent needs more information before it can proceed, it pauses the loop and surfaces a **blocking clarification prompt** — a structured set of questions for you to answer. Each question may offer options to pick from or a free-text field. Once you submit your answers, the agent resumes from where it left off, incorporating your input into its next step.
This clarification flow ensures the agent doesn't silently guess on ambiguous requirements — it asks you directly instead of proceeding on a potentially wrong assumption.