Core Concepts6 min read

Using Modes

The ten built-in modes and how to switch between them

A mode is the single biggest steering wheel you have in Nexgile Code. It bundles three things: a persona (the role and instructions the agent works under), a set of tool groups (what the agent is allowed to do), and optionally file restrictions (which paths its edit tools may touch). Pick the right mode and the agent behaves like the specialist you need; pick the wrong one and you’ll fight it — asking Ask mode to edit code, for instance, can’t work at all, because Ask has no edit tools.

Nx IDE ships 31 modes: the ten core modes described here plus 21 specialist modes. You can also build your own.

The ten built-in modes

Mode	Best for	Can edit files?	Can run commands?
🏗️ Architect	Planning, design, breaking down complex work	Markdown files only	No
💻 Code	Implementation — features, fixes, refactors	Yes	Yes
❓ Ask	Questions, explanations, learning a codebase	No	No
🪲 Debug	Diagnosing and fixing bugs systematically	Yes	Yes
🪃 Orchestrator	Coordinating multi-step work across modes	No (delegates)	No (delegates)
🔬 Tester	Independently verifying a change against its requirement	No	Yes
🔍 Reviewer	Independent code review of a diff	No	Yes
🚀 Shipper	Staging, committing, pushing approved work	No	Yes
📚 Spec Bootstrap	Generating a wiki for a brand-new project	Spec files only	Yes
🔄 Spec Sync	Keeping an existing wiki current with the code	Spec files only	Yes

Notes on the restricted rows:

Architect can read everything but write only .md files — it plans; it doesn’t implement.
Orchestrator has no tool groups at all. It works purely by delegating subtasks to other modes and collecting their results.
Spec Bootstrap / Spec Sync edits are limited to the docs/, sources/, spec/, and scripts/ subtrees plus .nexgilerules files at the project root.
Tester and Reviewer deliberately cannot edit: their value is independence from the implementer.

The default mode is Architect. That is intentional: new tasks start in a mode that can explore and plan but cannot change your source code, so the cost of a vague first request is a plan to review — not an edit to undo.

Switching modes

You’ll switch modes constantly. Three ways:

The mode selector in the chat box. The chip at the bottom of the chat input shows the current mode (for example 🏗️ Architect). Click it to open a searchable list of all 31 modes — type to filter, click to switch. Keyboard users can cycle without opening it: Ctrl + . for the next mode and Ctrl + Shift + . for the previous one (⌘ on macOS) while the chat panel has focus.
Agent-requested switches. Modes can ask to hand off — Architect finishing a plan will typically request a switch to Code to implement it. Every agent-initiated switch requires your approval unless you’ve enabled the mode-switch auto-approve toggle. Suggested answers to agent questions can also carry a mode switch, so one click both answers and switches.
Slash-command routing. A custom slash command can declare a mode in its frontmatter; invoking the command switches to that mode automatically.

Switching mid-task is safe and normal: the conversation and its context carry over — only the persona, tool access, and file restrictions change.

Per-mode model profiles

Modes can pin their own API configuration profile. In Settings → Modes, each mode has an API Configuration selector — “Select which API configuration to use for this mode.” A common setup:

Architect and Ask → a strong reasoning model (plan quality is leverage).
Code and Debug → your best coding model.
Spec Sync, simple Q&A → a cheaper, faster model.

Once pinned, the profile follows the mode: switch to Debug and its model comes with it, switch back to Code and yours returns.

Choosing the right mode

Architect → Code: the big-work pattern

For anything larger than a small fix, plan first. In Architect, describe the goal; the agent explores, asks clarifying questions, and produces a todo-list plan for your review. Iterate on the plan — it’s cheap to change words — then accept the offered switch to Code, which implements the approved items in order. You’ll spend fewer tokens and undo fewer wrong turns than diving straight into implementation.

Debug: for diagnosis, not guesswork

Debug mode follows a disciplined protocol: enumerate 5–7 possible causes, narrow to the 1–2 most likely, add targeted logging to confirm, and ask you to confirm the diagnosis before fixing. Use it when the cause is unknown; use Code when you already know exactly what to change. Pairing Debug with the @problems mention hands it the entire Problems panel as its starting evidence.

Ask: read-only by construction

Ask mode answers questions, explains concepts, and analyzes code — with no edit or command tools whatsoever. That makes it the safest way to explore an unfamiliar codebase: you can grant read auto-approval and browse freely, knowing nothing can change.

Orchestrator, Tester, Reviewer, Shipper: the delivery chain

These four are designed to work as a pipeline: Orchestrator delegates implementation, an independent Tester builds its own test plan from the requirement and verifies, an independent Reviewer reads the diff fresh, and Shipper — only after you confirm — stages, commits, and pushes to a feature branch. You can invoke any of them manually (Tester and Reviewer make excellent standalone second opinions on work Code just finished), or let the opt-in Workflow Mode run the whole chain automatically.

Spec Bootstrap and Spec Sync: documentation as a product

Spec Bootstrap interviews you and generates a deeplink-strict wiki for a greenfield project; Spec Sync walks git history and surgically updates that wiki as code lands. Use Bootstrap once at the start, Sync after every sprint.

Modes and your conventions

Rules files can target modes individually. Alongside the project-wide .nexgilerules, Nexgile Code loads .nexgilerules-<mode-slug> (for example .nexgilerules-code, .nexgilerules-docgen) and .nexgile/rules-<mode-slug>/ directories — but only when that mode is active. This is how you give Code mode a “run the linter before finishing” rule without burdening Ask mode with it, or hold Architect to a planning template. The filename must match the mode’s slug exactly — .nexgilerules-Debug won’t load for the debug mode. Details and precedence rules are in Rules Files & AGENTS.md.

Modes also determine behavior in the Workflow Mode delivery chain: with it enabled, a new top-level task started in Code or Debug is automatically routed to the Orchestrator, which runs the implement → test → review → ship pipeline for you.