Configuration

Neo loads the first available config:

1. ./neo.yaml
2. ~/.neo/config.yaml
3. Embedded defaults from internal/config/defaults/neo.yaml

First hit wins. Config files are not merged.

Default Config

This is the complete configuration surface. Copy it to ~/.neo/config.yaml or ./neo.yaml and change only the values you need.

# LLM backend: anthropic, openai, openrouter, or google.
provider: anthropic

# OpenAI only: api_key uses OPENAI_API_KEY; subscription uses `neo login`.
# openai_auth: api_key

model: claude-opus-4-8

# Optional. When omitted, subagents follow the active provider and model.
# subagents:
#   provider: anthropic
#   model: <claude-model-id>

permissions:
  mode: trusted # trusted, ask, or readonly

# Transcripts compact at 70% of this estimate.
compaction:
  context_window_tokens: 200000

features:
  agents_file: true
  skills: true
  prompt_caching: true

output:
  verbose: false

The embedded source, including annotated provider examples, is internal/config/defaults/neo.yaml.

Provider Selection

Config	Auth source	Provider adapter
provider: anthropic	ANTHROPIC_API_KEY	internal/llm/anthropic
provider: openai with openai_auth: api_key	OPENAI_API_KEY	internal/llm/openai.Client
provider: openai with openai_auth: subscription	ChatGPT/Codex device-code credentials from ~/.neo/auth.json	internal/llm/openai.CodexClient
provider: openrouter	OPENROUTER_API_KEY	internal/llm/openrouter
provider: google	GOOGLE_API_KEY	internal/llm/google

Subscription credentials are created with neo login and removed with neo logout. The docs describe only where credentials live and which flow uses them; token values are never generated into developer docs.

The top-level provider selects the backend for a session. In the TUI, /model lists models for that provider and switches the model and compactor for the current session without rewriting configuration. Start a new session with a different provider value to change backends.

Feature Flags

Each feature flag is tri-state in Go: absent means use the built-in default, while explicit false disables that capability.

Flag	Default	Effect
agents_file	true	Load AGENTS.md into the chat system prompt.
skills	true	Discover skills and expand $name references or /name slash invocations.
prompt_caching	true	Mark the stable system prompt prefix as cacheable when the provider supports it.

Output

output.verbose is tri-state, same as feature flags: absent or false means concise mode (the default).

Setting	Default	Effect
output.verbose: false	(default)	Show live in-flight activity and concise completed receipts (e.g. a file read or command run). Errors, failures, and direct ! command output always render in full.
output.verbose: true		Restore full tool call/result cards, including complete file contents and command output.

Permissions

permissions.mode defaults to trusted.

Mode	Effect
trusted	Allow built-in tools; ask before high-risk bash commands; deny path-shaped file tools outside the repo root.
ask	Allow read/search tools inside the repo root; ask before bash and file mutations.
readonly	Allow read/search tools only; deny bash and file mutations.