Configuration

nod separates repository-safe defaults from private user and workspace preferences. Use /settings, /permissions, and /workspace when possible; direct JSON editing is useful for settings that do not have an interactive control.

Files and precedence

MCP files have their own merge and trust rules rather than the settings precedence below. See MCP for their exact shapes and behavior.

For each setting, the highest available source wins:

1. command-line or process override, where supported
2. environment variable
3. matching workspace entry in ~/.nod/settings.json
4. global entry in ~/.nod/settings.json
5. <workspace>/.nod.json
6. built-in default

The settings file is limited to 64 KiB. Unknown JSON keys are ignored, but invalid values in known keys can make a layer unusable and produce a startup diagnostic.

Project configuration

.nod.json accepts exactly three public fields:

{
  "max_agent_steps": 40,
  "max_tool_result_bytes": 131072,
  "context": true
}

Profile-only fields such as model, provider, permission mode and rules, effort, notifications, update channel, and additional directories are ignored in project config and reported as a diagnostic. context_limits is also profile-only.

User profile

A complete representative ~/.nod/settings.json looks like this. Omit values you want nod to resolve from a lower layer or its defaults.

{
  "provider": "codex",
  "models": {
    "codex": "gpt-5.4",
    "grok": "grok-4"
  },
  "permission_mode": "auto",
  "max_agent_steps": 0,
  "max_tool_result_bytes": 65536,
  "first_call_tool_choice": "auto",
  "context": true,
  "context_limits": {
    "skill_catalog_bytes": 16384,
    "project_instructions_total_bytes": 131072
  },
  "fast_mode": false,
  "effort": "auto",
  "slash_menu_categories": true,
  "auto_upgrade": true,
  "update_channel": "stable",
  "startup_scrollback": true,
  "collapse_tool_calls": false,
  "session_titles": true,
  "prompt_history": {
    "enabled": true
  },
  "statusLine": {
    "context": false,
    "session": false,
    "workspace": false
  },
  "notifications": {
    "turn_end": true,
    "attention_required": true,
    "max": false
  },
  "permission": {
    "*": "ask"
  },
  "workspaces": {
    "/absolute/path/to/project": {
      "additional_directories": [
        "/absolute/path/to/shared"
      ],
      "permission": {
        "edit": {
          "*": "deny",
          "docs/*": "allow"
        }
      }
    }
  }
}

Agent and model settings

nod keeps one model per provider, so switching providers and switching back restores the model you were using. model, codex_model, and grok_model are older spellings of the same values. nod still reads them, and rewrites them: saving a model writes it under models and removes the older key, so a hand-written "model" disappears from the file the first time nod saves that preference.

context_limits accepts the keys and byte values listed in Context limits. Permission rules accept "allow", "ask", and "deny"; see Permissions for matching and scope.

Use "permission_mode": "full-access" for full access. Legacy "yolo" input remains accepted. For backward compatibility, nod still serializes this mode as "yolo" in saved settings and wire JSON; the interface displays "full access".

permission_mode: "auto" enables automatic review for eligible unresolved actions. Reviews use the active provider. See Automatic review configuration for the reviewer used by each provider.

Interface and update settings

Set collapse_tool_calls to true to show a summary for each tool-call group. Individual calls remain available in the full transcript with ctrl+o. startup_scrollback prints the transcript to the main screen when nod exits, so it stays in your terminal's scrollback. session_titles lets nod name a new session from its first prompt.

nod-managed fields

credential_source and yolo_acknowledged are valid profile fields, but nod manages them through authentication and permission flows. The yolo_acknowledged key retains its name for backward compatibility with full access acknowledgement. Avoid editing them by hand.

Credential source values are chatgpt_subscription and grok_subscription; see Authentication.

Workspace entries

Keys under workspaces are absolute primary workspace paths. nod saves workspace-local permission rules, additional_directories, and project MCP trust there. An additional-directory list contains at most 16 unique absolute directory paths.

A workspace object is parsed with the same setting schema as the top-level profile and may therefore carry deliberate local overrides, including context_limits and the three project-safe fields. The current interactive controls save model, effort, fast mode, permission mode, prompt history, status line, notification, and update preferences globally; older workspace copies of model and interface preferences are treated as legacy and may be migrated.

Additional directories extend tool access only. They do not contribute config, AGENTS.md, skills, hooks, Git identity, sessions, or history. See Additional workspaces.

Environment variables

These are the supported process overrides:

Environment and command-line overrides affect only the current process and are not written back to settings.

Inspect effective configuration

Inspect the resolved startup configuration as text or JSON:

nod status

nod status --json

Use nod permissions --json for the resolved permission rules and nod workspace --json for active additional directories.

Local state

nod stores private runtime state under ~/.nod/, including settings, saved provider sessions, sessions, prompt history, usage, MCP config and credentials, and managed skills.

Keep local state private

Do not copy ~/.nod into a repository. It can contain credentials, prompts, transcripts, paths, permission rules, and MCP environment values.

Browse all nod documentation

View this page as Markdown · llms.txt