Configuration

Nib is configured with JSON settings files in the widely used settings.json format. You don't need any of them to get started. They exist for when you want to pin a model, pre-approve commands, add hooks or adjust the sandbox.

Settings filesCopy Anchor Link

At each scope Nib also reads the shared file (.claude/settings.local.json, .claude/settings.json, ~/.claude/settings.json). When both exist at the same scope, the .nib/ file takes precedence.

Managed settingsCopy Anchor Link

How settings combineCopy Anchor Link

Precedence, highest first: managed → command line → local → project → user.

• Scalar values (model, effortLevel, …): the highest scope that sets the key wins.
• Permission rules from every scope are combined, then evaluated deny → ask → allow. A deny anywhere wins.
• Hooks from every scope all run.
• env values are merged, with higher scopes winning per variable.

Settings are read leniently. Unknown keys are kept and ignored. A known key with an invalid value is dropped with a warning naming the file and key, and the rest of the file still applies. A file that isn't valid JSON is skipped with a warning.

What a project can't setCopy Anchor Link

A repository's settings come from whoever wrote the repository, so some keys are limited:

• Until you trust the workspace, project and local files can't set hooks, env, apiKeyHelper, statusLine, subagentStatusLine, permissions.allow, permissions.additionalDirectories or sandbox.network.allowedDomains. Deny and ask rules still apply, because they only narrow what the agent can do.
• Ever: project and local files can't set permissions.defaultMode to auto or bypassPermissions, and can't set protected environment variables (HOME, TMPDIR, TMP, TEMP, XDG_*, OTEL_EXPORTER_OTLP_*, and the config directory variables of Nib and of the agents whose files it reads). They also can't weaken the sandbox: turning it off, opening localhost or Unix sockets, or adding readable or writable paths only works from user, managed or --settings files. Nor can they define MCP servers (mcpServers), approve the project's own servers (enableAllProjectMcpServers, enabledMcpjsonServers) or switch plugins on or off (enabledPlugins): a repository's servers go in .mcp.json, where each asks for your approval. Nor can they move auto memory (autoMemoryDirectory), a folder the agent writes in without asking.
• Managed only: allowManagedHooksOnly and allowManagedPermissionRulesOnly take effect only in managed settings.

ExampleCopy Anchor Link

{
  "model": "anthropic:claude-opus-5-5",
  "effortLevel": "medium",
  "permissions": {
    "allow": ["Bash(bun test *)", "Bash(bun run lint)", "Edit(src/**)"],
    "deny": ["Read(.env)", "Read(**/*.pem)"],
    "defaultMode": "acceptEdits"
  },
  "env": {
    "NODE_OPTIONS": "--max-old-space-size=8192"
  },
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write|ApplyPatch",
        "hooks": [{ "type": "command", "command": "bunx biome format --write ." }]
      }
    ]
  }
}

KeysCopy Anchor Link

ModelCopy Anchor Link

PermissionsCopy Anchor Link

Rule syntax is described in Permissions.

HooksCopy Anchor Link

SandboxCopy Anchor Link

Package registries and toolchain downloads are reachable without listing them, unless deniedDomains lists them. autoAllowBashIfSandboxed, excludedCommands, filesystem.disabled, network.allowAllUnixSockets, network.httpProxyPort and network.socksProxyPort are accepted so existing settings load, but not applied yet. Settings that could weaken the sandbox are ignored in project settings. See Sandbox.

MCPCopy Anchor Link

See MCP servers. The organization policy keys allowedMcpServers, deniedMcpServers, strictKnownMarketplaces and allowedExtensions are described under Managed settings.

Instructions, skills and agentsCopy Anchor Link

Environment and toolsCopy Anchor Link

GitCopy Anchor Link

Other files Nib readsCopy Anchor Link

Every .nib/ path has a ~/.nib/ user-level counterpart, and a .claude/ equivalent that Nib also reads. The exception is the project's MCP server file, whose counterpart is .mcp.json at the project root.

Daemon configurationCopy Anchor Link

The daemon takes its own configuration from flags and NIB_* environment variables. You rarely need these; the desktop app and CLI set them for you.