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": 50,
  "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`	Maximum autonomous iterations before stopping	`50`
`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
ANTHROPIC_API_KEY=your_key        # Anthropic API key
OPENAI_API_KEY=your_key           # OpenAI API 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

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

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