Configuration Guide

Codey uses standard JSON files to manage preferences, styling, model routing, and security. You can configure options globally or override them on a per-project basis.

#Precedence Order

Settings are merged (not replaced) across multiple layers, applying from lowest priority to highest priority:

1. Remote Defaults: Set by your organization via .well-known/codey.
2. Global User Config: Loaded from ~/.config/codey/codey.json.
3. Custom Config Path: Declared using the CODEY_CONFIG env variable.
4. Project Config: Defined in a local codey.json in your project's root folder.
5. Directory Configs: Specialized instructions or agents declared inside the project's .codey/ folder.

#Config Locations

Codey looks for files in the following standard platform folders:

#Configuration Parameters

A sample codey.json file:

{
  "$schema": "https://codey.ai/config.json",
  "theme": "one-dark",
  "model": "anthropic/claude-sonnet-4-5",
  "autoupdate": true,
  "permission": {
    "edit": "ask",
    "bash": "ask"
  },
  "tui": {
    "scroll_acceleration": {
      "enabled": true
    }
  }
}

#Key Configuration Blocks

• tui: Adjust scroll speeds, toggle scroll acceleration, and define diff rendering layouts ("auto" or "stacked").
• tools: Globally disable or enable specific tools like write, bash, or webfetch.
• permission: Set authorization prompts to "allow", "ask", or "deny" globally or for specific folders.
• agent: Define custom prompts, model settings, and tool scopes for specialized agent personas.