Configuration

How configuration works

Most configuration happens automatically through the TUI. When you switch models with /model or Ctrl+M, connect a provider with /connect, toggle MCP servers with /mcp, or adjust settings with /settings, Caboose persists those changes to your config files automatically. You rarely need to edit TOML by hand — but you can if you prefer.

Configuration uses a two-layer TOML system. Project-level settings override global ones:

Layer	Path	Scope
Global	~/.config/caboose/config.toml	Applies to all projects
Project	.caboose/config.toml	Applies only to the current project

This lets you set sensible defaults globally while customizing behavior per project.

Provider configuration

The easiest way to set up a provider is /connect:

/connect anthropic

This prompts for your API key and saves it. To switch models, use /model or Ctrl+M — the selection is persisted to your config automatically.

You can also set defaults manually in the [provider] section:

[provider]
default = "anthropic"
model = "claude-sonnet-4"

Supported providers and their default models:

• Anthropic — claude-sonnet-4
• OpenAI — gpt-4.1
• Gemini — gemini-2.0-flash
• OpenRouter — anthropic/claude-sonnet-4
• DeepSeek — deepseek-chat
• Groq — llama-3.3-70b-versatile
• Mistral — mistral-large-latest

API key storage

Caboose looks for API keys in the following order:

1. Environment variables — e.g. ANTHROPIC_API_KEY, OPENAI_API_KEY
2. Auth store — saved by /connect, stored locally
3. Config file — ~/.config/caboose/config.toml

Environment variables take precedence, so they work well for CI or ephemeral environments.

Behavior settings

Adjust these from /settings in the TUI, or set them manually in the [behavior] section:

[behavior]
auto_handoff_prompt = true
max_session_cost = 10.0

• auto_handoff_prompt — When true, Caboose prompts you to generate a handoff summary when context reaches 90% capacity.
• max_session_cost — A spending cap in USD. The session warns at 80% and pauses at 100%, giving you options to continue, raise the limit, or stop.

Session budgets can also be set from /settings using preset amounts.

Tools configuration

Enable or restrict specific tools in the [tools] section:

[tools]
allow = ["read_file", "write_file", "edit_file", "glob", "grep", "bash", "list_directory", "fetch"]

Omit a tool from the allow list to prevent Caboose from using it.

MCP servers

Toggle built-in MCP presets (Context7, Fetch) on and off from /mcp — changes are saved to your project config automatically. You can also add custom servers manually:

[mcp.servers.my-database]
command = "npx"
args = ["-y", "@my-org/db-mcp-server"]

See MCP Integration for more details.

Skills

Skills can be enabled or disabled from /settings. User-defined skills live in .caboose/skills/ (project) or ~/.config/caboose/skills/ (global). See Skills & Commands for details.

Project context with CABOOSE.md

Run /init inside a project to generate a CABOOSE.md file. This file is automatically included at the start of every prompt, giving the agent persistent context about your project’s architecture, conventions, and constraints. Edit it freely — it is a standard Markdown file checked into your repository.

/init

Caboose analyzes your project and generates the file. Keeping it accurate significantly improves the quality of the agent’s responses.