This page documents all available configuration options in nanx config files. Config files can be written in YAML, TOML, or JSON format.

File Locations

Configuration files are loaded in merge order (global → local → user-local):

• Global (user-level): ~/.config/nanx/config.(yaml|yml|toml|json)
• Local (project-level): .nanx/config.(yaml|yml|toml|json)
• User-Local (gitignored): .nanx/config.user.(yaml|yml|toml|json) New in v0.3.0

Environment Variables

Editor resolution priority order:

1. $NANX_EDITOR - Tool-specific editor override
2. config.editor.command - Full path from config file
3. config.editor.default - Editor name from config file
4. $VISUAL - Standard visual/screen editor (e.g., vim, emacs)
5. $EDITOR - Standard line editor (e.g., vi, nano)
6. Auto-detected popular editor (cursor, code, nvim, vim, nano, vi)
7. Interactive prompt with auto-install option

Complete Configuration Example

# ~/.config/nanx/config.yaml

# Disable inheritance from parent configs
no_inherit: false

# Editor configuration
editor:
  default: cursor  # cursor, vscode, vim, emacs, nano, subl, atom
  command: /usr/local/bin/cursor  # Optional: full path to editor

# AI providers configuration
providers:
  - name: claude
    type: anthropic
    api_key: sk-ant-api03-...
    model: claude-3-5-sonnet-20241022

  - name: gpt
    type: openai
    api_key: sk-...
    model: gpt-4-turbo

  - name: gemini
    type: google
    api_key: ...
    model: gemini-pro

  - name: local
    type: custom
    base_url: http://localhost:11434/v1
    model: qwen2.5-coder:32b
    headers:   # Optional custom headers

# Repository settings
repo:
  commit:
    generate_message:
      default_provider: claude
      rules_file: ~/.config/nanx/commit-rules.md  # Optional
      auto_stage: false
      max_tokens: 500
      temperature: 0.7

  branch:
    default_remote: origin
    auto_setup_remote: true

  push:
    default_remote: origin
    auto_set_upstream: true

# System settings
sys:
  top:
    provider: btop  # btop or native

# Apps/package manager settings
apps:
  provider: auto  # auto, homebrew, apt, github
  fallback_provider: github
  auto_install_essential: true

Top-Level Options

no_inherit

Type: boolean | Default: false

When set to true, disables configuration inheritance from parent directories. Useful for project-specific configurations that should not merge with user-level settings.

no_inherit: true

Editor Configuration

editor.default

Type: string | Optional

The default editor to use for commands like nanx config edit. Can be any editor name available in PATH. Common values: cursor, code, vim, nvim, emacs, nano, vi.

If not set, nanx will check $NANX_EDITOR, $VISUAL, and $EDITOR environment variables, auto-detect popular editors, or prompt interactively with auto-install option.

editor.command

Type: string | Optional

Full path to the editor executable. This takes precedence over default and environment variables. Use this for non-standard editor locations.

editor:
  default: cursor
  command: /usr/local/bin/cursor  # Full path override

AI Providers

providers

Type: array

List of AI provider configurations. Each provider requires a name, type, API key, and model. See AI Providers Setup for detailed configuration.

Provider Fields

Repository Settings

repo.commit.generate_message

Configuration for AI-powered commit message generation.

default_provider

Type: string | Required

Name of the AI provider to use by default (must match a provider name in providers).

rules_file

Type: string | Optional

Path to a markdown file containing custom commit message rules/guidelines for the AI.

auto_stage

Type: boolean | Default: false

Automatically stage all files when using --generate-message flag.

max_tokens

Type: number | Default: 500

Maximum tokens for AI-generated commit messages.

temperature

Type: number | Default: 0.7

AI creativity level (0.0 = deterministic, 1.0 = creative).

repo:
  commit:
    generate_message:
      default_provider: claude
      rules_file: ~/.config/nanx/commit-rules.md
      auto_stage: false
      max_tokens: 500
      temperature: 0.7

repo.branch

default_remote

Type: string | Default: origin

Default remote name for branch operations.

auto_setup_remote

Type: boolean | Default: true

Automatically set up remote tracking for new branches.

repo:
  branch:
    default_remote: origin
    auto_setup_remote: true

repo.push

default_remote

Type: string | Default: origin

Default remote name for push operations.

auto_set_upstream

Type: boolean | Default: true

Automatically set upstream tracking when pushing.

repo:
  push:
    default_remote: origin
    auto_set_upstream: true

System Settings

sys.top.provider

Type: string | Default: btop

System monitor provider to use. Options: btop (uses external btop if installed), native (built-in TUI monitor).

sys:
  top:
    provider: btop

Apps Settings

apps.provider

Type: string | Default: auto

Package manager provider to use. Options: auto (auto-detect platform), homebrew (macOS), apt (Linux), github (GitHub releases).

apps.fallback_provider

Type: string | Default: github

Fallback provider if the primary provider fails.

apps.auto_install_essential

Type: boolean | Default: true

Automatically install essential dependencies when needed.

apps:
  provider: auto
  fallback_provider: github
  auto_install_essential: true

Format Examples

YAML

editor:
  default: cursor
providers:
  - name: claude
    type: anthropic
    api_key: sk-ant-...

TOML

[editor]
default = "cursor"

[[providers]]
name = "claude"
type = "anthropic"
api_key = "sk-ant-..."

JSON

{ 
  "editor": { 
    "default": "cursor"
  },
  "providers": [
    { 
      "name": "claude",
      "type": "anthropic",
      "api_key": "sk-ant-..."
    }
  ]
}

Next Steps

• AI Providers Setup - Detailed AI configuration guide
• Configuration Overview - Back to configuration overview
• Config Commands - Manage your configuration