Configuration

Configuration

Codive can be configured via configuration files, environment variables, or command-line flags.

Configuration Hierarchy

Codive loads configuration in this order (later sources override earlier ones):

1. Default values
2. User config: ~/.config/codive/config.toml
3. Project config: ./codive.toml
4. Environment variables
5. Command-line flags

Configuration File

Create a config.toml file:

User Config

mkdir -p ~/.config/codive
touch ~/.config/codive/config.toml

Project Config

touch codive.toml

Full Configuration Reference

# codive.toml - Full configuration example

#-----------------------------------------
# Provider Configuration
#-----------------------------------------
[provider]
# LLM provider: "anthropic" | "openai"
name = "anthropic"

# Model to use
# Anthropic: "claude-sonnet-4-20250514", "claude-opus-4-20250514"
# OpenAI: "gpt-4", "gpt-4-turbo"
model = "claude-sonnet-4-20250514"

# API base URL (optional, for proxies or custom endpoints)
# base_url = "https://api.anthropic.com"

# Temperature for responses (0.0 - 1.0)
temperature = 0.7

# Maximum tokens per response
max_tokens = 4096

#-----------------------------------------
# Agent Behavior
#-----------------------------------------
[agent]
# Maximum tool call iterations per request
max_iterations = 50

# Require confirmation before writing files
confirm_writes = true

# Require confirmation before running commands
confirm_commands = true

# Auto-accept changes matching these patterns
auto_accept_patterns = [
  "*.md",
  "*.txt",
  ".gitignore",
]

#-----------------------------------------
# Tools Configuration
#-----------------------------------------
[tools]
# Enabled tools (default: all)
enabled = [
  "read",
  "write",
  "bash",
  "glob",
  "grep",
]

# Disabled tools (overrides enabled)
# disabled = ["bash"]

# Bash tool settings
[tools.bash]
# Allowed commands (empty = all allowed)
allowed_commands = []

# Blocked commands
blocked_commands = [
  "rm -rf /",
  "sudo rm",
  "> /dev/sda",
]

# Command timeout in seconds
timeout = 30

#-----------------------------------------
# Context & Indexing
#-----------------------------------------
[context]
# Maximum files to include in context
max_files = 100

# Maximum file size to read (in bytes)
max_file_size = 1048576  # 1MB

# File patterns to ignore
ignore_patterns = [
  "node_modules/**",
  "target/**",
  ".git/**",
  "*.lock",
  "dist/**",
]

# Always include these files in context
include_files = [
  "README.md",
  "Cargo.toml",
  "package.json",
]

#-----------------------------------------
# Server Mode
#-----------------------------------------
[server]
# Server host and port
host = "127.0.0.1"
port = 3000

# Enable CORS
cors = true

# Session timeout in minutes
session_timeout = 60

#-----------------------------------------
# Logging
#-----------------------------------------
[logging]
# Log level: "error" | "warn" | "info" | "debug" | "trace"
level = "info"

# Log file path (optional)
# file = "~/.local/share/codive/codive.log"

# Log format: "pretty" | "json"
format = "pretty"

#-----------------------------------------
# UI/TUI Settings
#-----------------------------------------
[ui]
# Color theme: "auto" | "dark" | "light"
theme = "auto"

# Show token usage
show_tokens = true

# Enable syntax highlighting
syntax_highlighting = true

Environment Variables

All configuration options can be set via environment variables:

Variable	Description	Example
ANTHROPIC_API_KEY	Anthropic API key	sk-ant-...
OPENAI_API_KEY	OpenAI API key	sk-...
CODIVE_PROVIDER	LLM provider	anthropic
CODIVE_MODEL	Model name	claude-sonnet-4-20250514
CODIVE_MAX_ITERATIONS	Max iterations	50
CODIVE_LOG_LEVEL	Log level	debug

Tip

Environment variable names follow the pattern CODIVE_ + uppercase config path with underscores. For nested config like tools.bash.timeout, use CODIVE_TOOLS_BASH_TIMEOUT.

Command-Line Flags

Override any setting from the command line:

# Use a specific provider and model
codive --provider openai --model gpt-4

# Increase max iterations
codive --max-iterations 100

# Run in verbose mode
codive --verbose

# Skip confirmation prompts
codive --yes

All Flags

codive [OPTIONS] [PROMPT]

Arguments:
  [PROMPT]  Optional prompt to run in one-shot mode

Options:
  -p, --provider <PROVIDER>     LLM provider [anthropic, openai]
  -m, --model <MODEL>           Model to use
  -c, --context <PATH>          Focus on specific path
      --max-iterations <N>      Maximum iterations [default: 50]
  -y, --yes                     Auto-accept all changes
  -v, --verbose                 Enable verbose output
  -q, --quiet                   Minimal output
      --serve                   Start in server mode
      --connect <ADDR>          Connect to remote server
      --port <PORT>             Server port [default: 3000]
      --new-session             Start a fresh session
      --config <FILE>           Use specific config file
  -h, --help                    Print help
  -V, --version                 Print version

Project-Specific Configuration

Create a codive.toml in your project root for project-specific settings:

• Directorymy-project/

  • codive.toml
  • Directorysrc/

    • …
  • Cargo.toml

my-project/codive.toml

[context]
# Always include the architecture docs
include_files = [
  "ARCHITECTURE.md",
  "docs/API.md",
]

# Ignore build artifacts
ignore_patterns = [
  "target/**",
  ".cargo/**",
]

[tools.bash]
# Project-specific allowed commands
allowed_commands = [
  "cargo *",
  "npm *",
  "make *",
]

Configuration Profiles

You can create multiple configuration profiles and switch between them:

~/.config/codive/profiles/

#   work.toml
#   personal.toml
#   oss.toml

# Use a specific profile
codive --config ~/.config/codive/profiles/work.toml

Or set via environment:

export CODIVE_CONFIG=~/.config/codive/profiles/work.toml
codive

Validating Configuration

Check your configuration for errors:

codive config validate

Show the effective configuration:

codive config show

Next Steps

• Explore available commands
• Add custom tools
• Set up IDE integration