Settings

XibeCode uses a layered configuration system that merges settings from multiple sources. This lets you set global preferences, override them per-project, and enforce organizational policies.

Settings Sources

Settings are loaded from four sources, merged in priority order (highest wins):

When the same key exists in multiple sources, the higher-priority source wins.

Settings Schema

{
  "permissions": {
    "allow": ["Bash(git *)", "Read(*)", "Write(*)"],
    "deny": ["Bash(rm -rf *)"],
    "ask": ["Bash(*)"]
  },
  "hooks": {
    "PreToolUse": [
      { "type": "command", "value": "echo 'about to use a tool'" }
    ],
    "SessionStart": [
      { "type": "command", "value": "echo 'session started'" }
    ]
  },
  "agent": {
    "defaultMode": "agent",
    "autoApprovalPolicy": "always",
    "microcompactThreshold": 0.75,
    "dreamConsolidationInterval": 3600
  },
  "memory": {
    "enabled": true,
    "maxMemories": 100,
    "relevanceThreshold": 0.3
  }
}

CLI Commands

List all settings

xc settings list

Shows the fully merged settings with the source of each value indicated.

Get a specific key

xc settings get permissions.allow
xc settings get agent.defaultMode

Set a value

xc settings set agent.defaultMode plan
xc settings set permissions.allow '["Bash(git *)","Read(*)"]'

By default, values are written to the user settings file. Use --source to target a specific layer:

xc settings set agent.defaultMode plan --source project
xc settings set permissions.deny '["Bash(rm -rf *)"]' --source policy

View source files

xc settings sources

Lists all setting sources with their paths and whether they exist.

View file paths

xc settings paths

Shows the exact file paths for each settings source.

Example Workflows

Global defaults with per-project overrides

Set your preferred model globally:

xc settings set agent.defaultMode agent

Override for a specific project by creating .xibecode/settings.json in the project root:

{
  "agent": {
    "defaultMode": "plan"
  }
}

Team-shared project settings

Commit .xibecode/settings.json to share settings with your team:

{
  "permissions": {
    "allow": ["Read(*)", "Write(src/**)"],
    "deny": ["Bash(rm -rf *)"],
    "ask": ["Bash(*)"]
  },
  "hooks": {
    "PreToolUse": [
      { "type": "command", "value": "audit-log.sh" }
    ]
  }
}

Keep personal overrides in .xibecode/settings.local.json (add to .gitignore):

{
  "agent": {
    "autoApprovalPolicy": "always"
  }
}

Enforced organizational policies

Place machine-wide policies in /etc/xibecode/settings.json:

{
  "permissions": {
    "deny": ["Bash(curl *|*)", "Bash(wget *)"],
    "allow": ["Read(*)", "Write(*)", "Bash(git *)", "Bash(pnpm *)"]
  }
}

Policy settings cannot be overridden by user or project settings.

How Merging Works

The merge is a deep merge:

• Objects are merged recursively (nested keys from higher priority override lower)
• Arrays are replaced entirely by the higher-priority source (not concatenated)
• Primitives use the highest-priority value

For example, if user settings has permissions.allow: ["Read(*)"] and project settings has permissions.allow: ["Read(*)", "Write(*)"], the merged result is ["Read(*)", "Write(*)"] — the project array replaces the user array entirely.

Next Steps

• Permissions — Configure allow/deny/ask rules
• Lifecycle Hooks — Register custom logic at agent events
• Auto-Memory — Persistent project memory system