Configuration

Nexrall Code configures itself through a .nexrall/ directory and a few well-known files, layered by scope so team settings, personal settings, and machine-local overrides coexist. This page maps the directory and the settings.json hierarchy.

The .nexrall/ directory

A project can carry a .nexrall/ directory at its root; a global copy lives at ~/.nexrall/. Files are discovered and merged at session start.

Path	What it holds
.nexrall/nexrall.md (or nexrall.md, NEXRALL.md)	Project-specific instructions, auto-included in every session.
.nexrall/instructions.md / .nexrall/config.md	Alternate project-instruction filenames (first match wins).
~/.nexrall/nexrall.md	Global instructions that apply to every project.
.nexrall/settings.json	Project settings (permissions, model, etc.), shared with the team.
~/.nexrall/settings.json	Your personal settings, across all projects.
.nexrall/permissions.json	Permission rules (see Permissions).
.nexrall/mcp.json	MCP server connections (see MCP).
.nexrall/agents/	Custom sub-agents (see Sub-agents & skills).
.nexrall/commands/	Custom slash commands.
.nexrall/skills/	Reusable skill playbooks.
.nexrall/plugins/	Installed plugins (see Plugins).
.nexrall/checkpoints/	File checkpoints for /rewind.
.nexrall/memory.md	Persistent memory written via memory_write.
.nexrall/cli-sessions/	Saved CLI sessions.
.nexrall/trusted-folders.json	Folders you've explicitly trusted.

Project instructions: nexrall.md

The most-used piece of configuration. Run /init (or ask the agent in a session) to generate a nexrall.md at the project root — a short brief (tech stack, conventions, what to avoid) that's prepended to every session in that directory, so you don't repeat context each time.

Nexrall reads these candidate filenames for the project brief, in order (first match wins):

1. nexrall.md
2. NEXRALL.md
3. .nexrall/instructions.md
4. .nexrall/config.md

A global ~/.nexrall/nexrall.md applies to every project; persistent memory (project-scoped, keyed by working directory) is merged in alongside it.

Settings hierarchy

Settings merge across tiers, and the tiers are layered so the most specific wins. The effective value of a setting is resolved in this order:

Tier	Location	Scope
Managed (read-only policy)	managed-settings.json (macOS /Library/Application Support/Nexrall/, Windows %PROGRAMDATA%\Nexrall\, Linux /etc/nexrall/)	Highest — enforced organization-wide
User	~/.nexrall/settings.json	You, across all projects
Project	<workDir>/.nexrall/settings.json	This repository

For permission rules specifically, the precedence is inverted where it matters: deny always wins, then allow, then ask — a deny at any tier blocks the action regardless of an allow lower down.

settings.json shape

{
  "permissions": {
    "allow": ["Bash(npm run lint)", "Bash(npm run test *)"],
    "ask": ["Bash(curl *)"],
    "deny": ["Read(.env)", "Read(secrets/**)"]
  },
  "env": {
    "NEXRALL_ALLOW_DESTRUCTIVE": "0"
  }
}

The permissions block is the main one (see Permissions for rule syntax). A hooks key and an env key can also live here — env exposes environment variables to the agent session.

Next steps

• Permissions — the allow/ask/deny rule syntax in detail.
• Environment variables — the NEXRALL_* variables.
• Sub-agents & skills — .nexrall/agents/ and .nexrall/skills/.