Configuration

Nyzhi loads configuration from three layers, merged in order. Later values override earlier ones. All sections are optional — Nyzhi works with no config file if you set an API key via environment variable.

Config Layers

Config directories are created automatically on first run. For the full load order, see Config Loading Order at the end.

Provider

Select the default LLM provider and configure per-provider settings.

[provider]
default = "openai"

Per-Provider Settings

[provider.openai]
model = "gpt-5.2-codex"
# api_key = "sk-..."       # inline API key (env var preferred)
# base_url = "https://..."  # custom endpoint

[provider.anthropic]
model = "claude-sonnet-4-20250514"

[provider.gemini]
model = "gemini-2.5-flash"

See Providers for full provider details and model tiers.

Custom Providers

Any OpenAI-compatible endpoint can be added:

[provider.my-llm]
base_url = "https://api.example.com/v1"
api_key = "..."
api_style = "openai"          # openai, anthropic, or gemini
env_var = "MY_LLM_API_KEY"    # environment variable name for API key

Built-In Provider Definitions

Nyzhi ships with definitions for: openai, anthropic, gemini, openrouter, deepseek, groq, kimi, minimax, glm. Each defines a default base_url, env_var, and api_style.

Models

Global model parameters for all providers.

[models]
max_tokens = 16384
# temperature = 0.7    # sampling temperature (provider default if unset)

TUI

Theme, accent, and output style for the terminal UI. See TUI for usage.

[tui]
theme = "nyzhi-dark"
accent = "copper"
# output_style = "streaming"   # streaming or block

Theme Presets

nyzhi-dark, nyzhi-light, tokyonight, catppuccin-mocha, dracula, solarized-dark, solarized-light, gruvbox-dark

Accent Colors

copper, blue, orange, emerald, violet, rose, amber, cyan, red, pink, teal, indigo, lime, monochrome

Color Overrides

Override any theme slot with a hex color:

[tui.colors]
bg_page = "#1a1b26"
bg_surface = "#1f2335"
bg_elevated = "#24283b"
bg_sunken = "#16161e"
text_primary = "#c0caf5"
text_secondary = "#a9b1d6"
text_tertiary = "#565f89"
text_disabled = "#3b4261"
border_default = "#292e42"
border_strong = "#3b4261"
accent = "#7aa2f7"
accent_muted = "#3d59a1"
success = "#9ece6a"
danger = "#f7768e"
warning = "#e0af68"
info = "#7aa2f7"

Notifications

[tui.notify]
bell = true
desktop = false
min_duration_ms = 5000    # only notify if turn took longer than this (default: 5000)

Update

Control automatic update checks when the TUI starts.

[update]
enabled = true
check_interval_hours = 4
release_url = "https://get.nyzhi.com"

Agent

Core agent behavior: step limits, context management, and custom instructions.

[agent]
max_steps = 100
custom_instructions = ""
auto_compact_threshold = 0.8
enforce_todos = false
auto_simplify = false

Trust

Controls which tools require explicit approval. See the table below for mode behavior.

[agent.trust]
mode = "off"
allow_tools = ["edit", "write"]
allow_paths = ["src/", "tests/"]

Retry

Retry behavior for 429 and 5xx responses.

[agent.retry]
max_retries = 3
initial_backoff_ms = 1000
max_backoff_ms = 30000

Routing

Auto-select model tier based on prompt complexity. See Routing for details.

[agent.routing]
enabled = false
low_keywords = ["typo", "rename", "format"]
high_keywords = ["architect", "design", "security"]

Hooks

Run shell commands after edits, after turns, or around tool execution. See Hooks for full details.

[[agent.hooks]]
event = "after_edit"
command = "cargo fmt -- {file}"
pattern = "*.rs"
timeout = 30
# block = false

[[agent.hooks]]
event = "after_turn"
command = "cargo clippy --all -- -D warnings"
timeout = 60

Hook events: after_edit, after_turn, pre_tool, post_tool, post_tool_failure, teammate_idle, task_completed

Commands

Custom slash commands loaded from config or .nyzhi/commands/. See the commands documentation for full details.

[[agent.commands]]
name = "test"
prompt = "Write comprehensive tests for $ARGUMENTS"
description = "Generate tests for a module"

MCP

Configure MCP servers in config or in .mcp.json at the project root.

In config.toml

[mcp.servers.filesystem]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-filesystem", "/home/user/projects"]

[mcp.servers.remote-api]
url = "https://mcp.example.com"
headers = { Authorization = "Bearer token" }

In .mcp.json (project root)

Compatible with Claude Code and Codex format:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "."]
    },
    "remote": {
      "url": "https://mcp.example.com",
      "headers": {
        "Authorization": "Bearer token"
      }
    }
  }
}

Shell

[shell]
# default_shell = "/bin/bash"
# timeout = 120

Browser

[browser]
# headless = true

Memory

[memory]
# enabled = true

External Notifications

Send webhooks or notifications to external services. See Notifications for full options.

[notify]
# webhook = { url = "https://hooks.example.com/nyzhi" }
# telegram = { bot_token = "123:ABC", chat_id = "-100123" }
# discord = { webhook_url = "https://discord.com/api/webhooks/..." }
# slack = { webhook_url = "https://hooks.slack.com/services/..." }

Environment Variables

Config Loading Order

1. Load global config from ~/.config/nyzhi/config.toml.
2. Detect project root (walk up from CWD looking for .nyzhi/, .claude/, or .git/).
3. Load project config from <project_root>/.nyzhi/config.toml.
4. Load local config from <project_root>/.nyzhi/config.local.toml.
5. Merge: project overrides global, local overrides project.
6. CLI flags override everything.