Configuration

Customize models, API endpoints, package managers, and all XibeCode settings. 23 config options including apiKey, model, maxIterations, and more.

XibeCode stores its configuration in ~/.xibecode/. You can manage settings via the CLI or by editing the config file directly.

Interactive Setup

xibecode config

This opens an interactive menu to configure all settings including API key, model, package manager, default mode, and safety settings.

Quick Commands

# Set API key
xibecode config --set-key YOUR_ANTHROPIC_API_KEY

# Set custom API endpoint
xibecode config --set-url https://your-custom-endpoint.com

# Set default model
xibecode config --set-model claude-sonnet-4-5-20250929

# View current config
xibecode config --show

# Reset all settings
xibecode config --reset

Configuration File

The main configuration file is located at ~/.xibecode/config.json:

{
  "apiKey": "sk-ant-...",
  "baseUrl": "https://api.anthropic.com",
  "model": "claude-sonnet-4-5-20250929",
  "maxIterations": 0,
  "autoCompactEnabled": true,
  "autoCompactThreshold": 13000,
  "defaultVerbose": false,
  "preferredPackageManager": "pnpm",
  "enableDryRunByDefault": false,
  "gitCheckpointStrategy": "stash",
  "defaultMode": "agent",
  "autoApprovalPolicy": "always",
  "plugins": [],
  "mcpServers": {}
}

Configuration Options

Setting	Description	Default
`apiKey`	Your AI provider API key (Anthropic, OpenAI)	—
`baseUrl`	Custom API endpoint (Azure, AWS Bedrock, etc.)	Anthropic default
`model`	Default AI model to use	`claude-sonnet-4-5-20250929`
`maxIterations`	Max agent turns; `0` = unlimited	`0`
`autoCompactEnabled`	Auto microcompact + full handoff near context budget	`true`
`autoCompactThreshold`	Tokens to keep free when deciding to compact	`13000`
`defaultVerbose`	Enable verbose logging by default	`false`
`preferredPackageManager`	Package manager: pnpm, bun, npm, or yarn	`pnpm`
`enableDryRunByDefault`	Run in dry-run mode by default	`false`
`gitCheckpointStrategy`	Git checkpoint method: stash or commit	`stash`
`defaultMode`	Default agent mode to start in	`agent`
`autoApprovalPolicy`	Mode transition approval: always, prompt-only, never	`always`
`testCommandOverride`	Custom test command (overrides auto-detection)	Auto-detected
`plugins`	Array of plugin file paths	`[]`
`mcpServers`	MCP server configurations	`{}`

Environment Variables

# API Keys (examples — many providers supported; see Providers docs)
ANTHROPIC_API_KEY=your_key
OPENAI_API_KEY=your_key
OPENROUTER_API_KEY=your_key
ROUTINGRUN_API_KEY=your_key
ZENLLM_API_KEY=your_key

# API Configuration
ANTHROPIC_BASE_URL=https://...    # Custom endpoint
XIBECODE_MODEL=claude-opus-4-...  # Default model

# Behavior
XIBECODE_DRY_RUN=true             # Enable dry-run by default
XIBECODE_VERBOSE=true             # Enable verbose logging
XIBECODE_MODE=plan                # Default agent mode
XIBECODE_AUTO_COMPACT=0           # Disable auto-compact
XIBECODE_DISABLE_FILE_CHECKPOINTING=1  # Disable file-history snapshots
XIBECODE_HOME=~/.xibecode         # Override home directory

# Daemon / messaging
XIBECODE_BUSY_INPUT_MODE=steer    # steer | queue | interrupt
XIBECODE_RUNTIME_MODE=default     # default | e2b
XIBECODE_CMD_TIMEOUT_MS=60000     # /cmd shell timeout
XIBECODE_DAEMON_VERBOSE=1         # Tool traces in daemon logs
XIBECODE_DISABLE_UPDATE_CHECK=1   # Skip npm update offers

Sandbox / Cloud Configuration

Cloud execution is configured with dedicated sandbox settings:

xibecode config --set-sandbox-mode e2b
xibecode config --set-sandbox-gateway-url "https://your-gateway.example.com"
xibecode config --set-sandbox-auth-token "your-shared-token"
xibecode config --set-sandbox-session-strategy sandbox_full
xibecode config --set-sandbox-sync-max-mb 50
xibecode config --set-sandbox-sync-exclude ".git,node_modules,.xibecode,dist,build,.env,.env.*"
xibecode config --set-sandbox-sync-respect-gitignore true

Strategies

host_only - remote shell execution, local file tools
sandbox_full - synced workspace, remote file and command execution

Relevant cloud env vars

XIBECODE_SANDBOX_MODE=e2b
XIBECODE_SANDBOX_GATEWAY_URL=https://your-gateway.example.com
XIBECODE_SANDBOX_AUTH_TOKEN=your-shared-token
XIBECODE_SANDBOX_STRATEGY=sandbox_full
XIBECODE_SANDBOX_SYNC_MAX_MB=50
XIBECODE_SANDBOX_SYNC_EXCLUDE=.git,node_modules,.xibecode
XIBECODE_SANDBOX_SYNC_RESPECT_GITIGNORE=1
XIBECODE_SANDBOX_SESSION_ID=<existing-session-id>
XIBECODE_SANDBOX_SKIP_SYNC=1
XIBECODE_E2B_TEMPLATE=<template-id-or-alias>
XIBECODE_E2B_SANDBOX_TIMEOUT_MS=900000
XIBECODE_RUNTIME_MODE=e2b

Priority Order

Configuration is resolved in this order (highest priority first):

CLI flags (e.g., --api-key, --model)
Environment variables
Project-level config (.xibecode/config.json)
Global config file (~/.xibecode/config.json)

Agent Mode Configuration

{
  "defaultMode": "agent",
  "autoApprovalPolicy": "prompt-only"
}

Auto-approval policies:

always — Auto-approve all mode transitions
prompt-only — Require confirmation for escalation (read -> write)
always-for-debugger — Auto-approve only debugger transitions
never — Always require confirmation

Custom API Endpoints

XibeCode supports custom API endpoints, making it compatible with Azure OpenAI, AWS Bedrock, or any Claude-compatible API:

# Via config
xibecode config --set-url https://your-custom-endpoint.com

# Via CLI flag
xibecode run "task" --base-url https://your-custom-endpoint.com

# Via environment variable
export ANTHROPIC_BASE_URL=https://your-custom-endpoint.com

Azure OpenAI Example

{
  "baseUrl": "https://your-resource.openai.azure.com",
  "apiKey": "your-azure-api-key",
  "model": "your-deployment-name"
}

AWS Bedrock Example

{
  "baseUrl": "https://bedrock-runtime.us-east-1.amazonaws.com",
  "apiKey": "your-aws-credentials",
  "model": "anthropic.claude-3-sonnet-20240229-v1:0"
}

Package Manager Detection

XibeCode automatically detects your preferred package manager by checking for lock files:

pnpm-lock.yaml → pnpm
bun.lockb → bun
yarn.lock → yarn
package-lock.json → npm

Override this with the preferredPackageManager setting.

Test Runner Configuration

XibeCode auto-detects test runners:

Vitest — vitest.config.ts or vitest in package.json
Jest — jest.config.js or jest in package.json
Mocha — .mocharc.js or mocha in package.json
pytest — pytest.ini or pyproject.toml
Go test — go.mod file present
Cargo test — Cargo.toml file present

Override with a custom test command:

{
  "testCommandOverride": "npm run test:unit"
}

Git Checkpoint Strategies

stash — Uses git stash (recommended, lightweight)
commit — Creates a commit (persistent history)

{
  "gitCheckpointStrategy": "stash"
}

Project-Level Configuration

Create a .xibecode/config.json in your project root for project-specific settings:

{
  "testCommandOverride": "pnpm test",
  "defaultMode": "tester",
  "plugins": ["./custom-plugin.js"]
}

Backup Configuration

XibeCode automatically backs up files before editing. Backups are stored in ~/.xibecode/backups/ with timestamps:

~/.xibecode/backups/
  ├── src_app.ts_2024-01-15T10-30-00.bak
  ├── src_utils_helper.ts_2024-01-15T10-31-00.bak
  └── ...

Additional CLI Commands

XibeCode v1.1 introduces dedicated commands for the new subsystems:

Settings Management

xc settings list                    # Show fully merged settings
xc settings get <key>               # Get a specific setting value
xc settings set <key> <value>       # Set a value (writes to user source)
xc settings set <key> <value> --source project  # Write to project source
xc settings sources                 # Show all settings sources
xc settings paths                   # Show file paths for each source

See Settings for full documentation.

Hooks Management

xc hooks list                       # Show all registered hooks
xc hooks add <event> <type> <value> # Register a new hook
xc hooks remove <event> <index>     # Remove a hook by index
xc hooks events                     # Show available lifecycle events

See Lifecycle Hooks for full documentation.

Memory Management

xc memory list                      # List all project memories
xc memory search <query>            # Search memories by keyword
xc memory dream                     # Run dream consolidation
xc memory path                      # Show memory directory path

See Auto-Memory for full documentation.

Next Steps

Agent Modes — Learn about all 13 personas
MCP Integration — Set up external tool servers
Plugins — Create custom plugins
Settings — Multi-source layered configuration
Lifecycle Hooks — Run custom logic at agent events
Auto-Memory — Persistent project memory
Permissions — Fine-grained tool execution rules

Max iterations

Config / flag	Meaning
`maxIterations: 0` (default)	Unlimited agent loops
`maxIterations: 100`	Stop after 100 model turns
`xibecode run -d 0`	Unlimited for this run
`xibecode run -d 50`	Cap this run at 50

Economy mode still applies economyMaxIterations as a separate lower bound for cheap runs.

See Agent engine and Providers.