Skip to content
Nx IDEDocs

Customization5 min read

Custom Modes

Define your own personas with .nexgilemodes YAML

Nx IDE ships 31 modes, but the highest-value persona is often the one only your team can write: the docs writer who may touch nothing but Markdown, the SQL reviewer who can read and run but never edit, the release manager with your exact checklist baked in. Custom modes let you define personas with their own role, instructions, and tool permissions — including per-file-type edit restrictions — and they appear in the mode dropdown next to the built-ins.

Creating your first custom mode

Section titled “Creating your first custom mode”

Create a file named .nexgilemodes at your project root. It’s YAML with a single customModes: list (JSON is also accepted — if YAML parsing fails, the file is retried as JSON):

customModes:
  # Each entry defines one mode.
  - slug: docs-writer                 # Unique ID: letters, numbers, dashes only.
                                      # Used in the dropdown, .nexgilerules-docs-writer,
                                      # .nexgile/rules-docs-writer/, and skills-docs-writer/.
    name: 📝 Docs Writer              # Display name shown in the mode dropdown.
    description: Writes and edits project documentation only.
                                      # Short blurb shown in the mode list UI.
    roleDefinition: >-
      You are a senior technical writer. You produce clear, accurate,
      example-driven documentation. You never invent APIs — you read the
      source first and document what actually exists.
                                      # The persona. Placed at the start of the
                                      # system prompt — defines who the agent is.
    whenToUse: >-
      Use for writing or restructuring documentation, READMEs, and
      changelogs. Not for code changes.
                                      # Guidance used by the Orchestrator when it
                                      # delegates, and shown in the UI.
    customInstructions: >-
      Follow the style guide in docs/STYLE.md. Use sentence-case headings.
      Every code sample must be runnable. Update the docs index when you
      add a page.
                                      # Appended to the mode's rules on every request.
    groups:                           # Tool permissions for this mode.
      - read                          # read_file, search_files, list_files, codebase_search
      - - edit                        # edit tools, restricted by the options object:
        - fileRegex: \.(md|mdx)$      # regex tested against the relative file path
          description: Markdown files only
      - command                       # execute_command (e.g. to run a docs build)
                                      # (omit "mcp" to keep MCP tools off in this mode)
    source: project                   # Where it lives: project (.nexgilemodes)
                                      # or global. Optional — inferred from the file.

Save the file — the mode appears in the dropdown immediately. No reload needed.

Field reference

Section titled “Field reference”
Field Required Purpose
slug Yes Unique identifier ([a-zA-Z0-9-]+). Also keys mode-scoped rules, skills, and per-mode model profiles.
name Yes Display name in the dropdown (emoji welcome).
roleDefinition Yes The persona — who the agent is in this mode.
description No One-line summary for the modes UI.
whenToUse No Helps the Orchestrator (and teammates) pick this mode when delegating.
customInstructions No Standing instructions injected on every request in this mode.
groups Yes Tool permissions: any of read, edit, command, mcp. [] means only always-available tools (ask, complete, delegate, todos, skills).
source No project or global; normally set for you based on where the mode is saved.

Tool groups and file restrictions

Section titled “Tool groups and file restrictions”

A groups entry is either a plain group name or a pair of [group, options]. The options object supports fileRegex — a regular expression tested against each file’s workspace-relative path — and a human-readable description:

groups:
  - read
  - - edit
    - fileRegex: ^src/migrations/.*\.sql$
      description: SQL migration files only

If the mode tries to edit a file that doesn’t match, the edit is rejected and the agent is told which pattern applies — the same mechanism that keeps built-in Architect on Markdown. Listing the same group twice is a validation error. See How Tools Work for what each group unlocks.

Global custom modes

Section titled “Global custom modes”

Project modes travel with the repo. For personas you want in every project, use global custom modes, stored in a custom_modes.yaml file in Nexgile Code’s settings directory. You rarely edit it by hand: open Settings → Modes, create or edit a mode, and choose global as its save location — the file is managed for you (and watched, so hand edits are picked up too).

Custom modes override built-ins

Section titled “Custom modes override built-ins”

If a custom mode uses the same slug as a built-in mode, yours wins. This is the supported way to reshape a built-in: define a mode with slug: code and your own roleDefinition or customInstructions, and every task in Code mode uses your version. Delete the custom entry to get the stock behavior back.

Precedence

Section titled “Precedence”

When the same slug is defined in more than one place:

  1. Project tier beats global tier.
  2. Within the project tier, .nexgilemodes beats per-file agents in .nexgile/agents/ (see Custom Agents).
  3. Within the global tier, ~/.nexgile/agents/ beats custom_modes.yaml.
  4. Any custom mode beats a built-in mode with the same slug.

Live reload

Section titled “Live reload”

.nexgilemodes, the global custom_modes.yaml, and the agents directories are all watched. Edit, create, or delete — the merged mode list rebuilds and the dropdown updates on save. This makes iteration fast: tweak customInstructions, save, and start a new task to feel the difference.

Import and export

Section titled “Import and export”

From the Modes view (Settings → Modes) you can share modes as a single YAML file:

  • Export mode packages the selected mode’s full definition — including any rules files from its .nexgile/rules-<slug>/ directory — into one shareable .yaml.
  • Import mode loads such a file at either the project level (written to .nexgilemodes + .nexgile/rules-<slug>/) or the global level. Importing a slug that already exists overwrites it, and the mode’s rules folder is replaced by the imported one.

Troubleshooting

Section titled “Troubleshooting”
  • Your custom modes vanished from the dropdown — the classic symptom of a corrupt .nexgilemodes. Nexgile Code shows an error toast with the YAML line number; fix the syntax (a stray tab or unclosed quote is typical) and save. Until it parses, the file contributes zero modes.
  • Schema errors — if the YAML parses but a field is wrong (missing roleDefinition, duplicate slug, invalid fileRegex), a toast lists each offending field and the file’s modes are skipped.
  • Smart-quote paste damage — content pasted from chat tools or word processors often carries curly quotes, long dashes, and invisible characters. Nexgile Code cleans these automatically before parsing, so paste away.
  • Mode loads but its rules don’t — a mode-scoped rules file must match the slug exactly: .nexgilerules-docs-writer for slug: docs-writer. See Rules Files & AGENTS.md.
  • More in Troubleshooting.
Section titled “Related”