Configuration Overview

Coco's configuration controls AI provider settings, output behavior, file filtering, and more. It can be defined in multiple locations, each with a specific priority.

Configuration Priority

coco merges configuration from multiple sources. Higher-priority sources override lower ones:

1. Command Line Flags — highest priority, useful for one-off changes
2. Environment Variables — COCO_* prefixed variables (see below)
3. Project Config — .coco.json or .coco.config.json in your project root
4. Git Profile — [coco] section in ~/.gitconfig
5. XDG Config — $XDG_CONFIG_HOME/coco/config.json (defaults to ~/.config/coco/config.json)
6. Built-in Defaults — sensible defaults for all settings

Run coco doctor to see which sources are active and where your config is loaded from.

Project Config Filename

Coco looks for .coco.json first, then falls back to .coco.config.json for backward compatibility. New projects should use .coco.json — it's shorter and follows the dotfile convention. Both filenames work identically.

Configuration Options

Core Settings

Conventional Commits

File Processing

AI Prompts

Auto-Fix

Example:

1{
2  "autoFixTool": "codex",
3  "autoFixToolOptions": {
4    "model": "o4-mini",
5    "approval-mode": "auto-edit"
6  }
7}

Interactive Log TUI

The logTui object configures the full-screen coco log -i experience.

Example:

1{
2  "logTui": {
3    "theme": {
4      "preset": "catppuccin",
5      "borderStyle": "round",
6      "colors": {
7        "accent": "#89b4fa",
8        "focusBorder": "#89dceb",
9        "selection": "#45475a"
10      }
11    },
12    "idleTips": true,
13    "dateBucketing": true
14  }
15}

NO_COLOR=1 overrides color settings and keeps the TUI readable in monochrome. Terminals such as TERM=dumb use the ASCII-safe rendering path.

Service Configuration

The service object configures the AI provider and model settings:

Service Options

Opt-in Fast Paths (lossy)

The diff-condensing pipeline ships several lossless optimizations on by default — content-hash cache, trivial-shape skip for pure additions / deletions / renames / binary diffs, sort discipline, rate-limit retries. None of these change the output detail; they just avoid redundant work.

service.fastPath exposes opt-in lossy optimizations that trade summary detail for speed. They are off by default. When you enable one, you accept that final commit messages on the affected file shapes may be blander than LLM-generated summaries — the templated extract names structural changes only.

When to enable fastPath.markdown:

• You commit doc changes frequently and want the speed win on docs-shaped commits.
• Your downstream commit-message style for docs is naturally structural (e.g. "docs: update OAuth section") and doesn't lean on LLM-generated detail.
• You're running on a slow / rate-limited model and the latency saved per markdown file is worth the loss in summary nuance.

When to leave it off (default):

• You want commit messages on doc commits to retain LLM-generated detail like "expanded the OAuth section with PKCE examples and clarified rate-limit behavior."
• Your team uses doc commit messages for changelogs or audit trails.

1{
2  "service": {
3    "provider": "openai",
4    "model": "gpt-4.1-nano",
5    "fastPath": {
6      "markdown": true
7    }
8  }
9}

The templated summary format looks like:

Dynamic Model Routing

When service.model is set to "dynamic", Coco selects a task-appropriate model automatically. See Dynamic Model Routing for the full guide.

Supported task keys: summarize, commit, changelog, review, recap, repair, largeDiff.

1{
2  "service": {
3    "provider": "openai",
4    "model": "dynamic",
5    "dynamicModelPreference": "balanced",
6    "dynamicModels": {
7      "summarize": "gpt-4.1-nano",
8      "commit": "gpt-4.1-mini",
9      "review": "gpt-4.1"
10    }
11  }
12}

Authentication

Three authentication types are supported:

Provider Examples

OpenAI Configuration:

1{
2  "service": {
3    "provider": "openai",
4    "model": "gpt-4o",
5    "tokenLimit": 2048,
6    "temperature": 0.4,
7    "maxConcurrent": 6,
8    "authentication": {
9      "type": "APIKey",
10      "credentials": {
11        "apiKey": "sk-..."
12      }
13    },
14    "requestOptions": {
15      "timeout": 30000,
16      "maxRetries": 3
17    },
18    "maxParsingAttempts": 3,
19    "fields": {
20      "topP": 1.0,
21      "frequencyPenalty": 0.0,
22      "presencePenalty": 0.0
23    }
24  }
25}

OpenAI via OpenRouter:

1{
2  "service": {
3    "provider": "openai",
4    "model": "anthropic/claude-3.5-sonnet",
5    "baseURL": "https://openrouter.ai/api/v1",
6    "authentication": {
7      "type": "APIKey",
8      "credentials": {
9        "apiKey": "sk-or-v1-..."
10      }
11    }
12  }
13}

Anthropic Configuration:

1{
2  "service": {
3    "provider": "anthropic",
4    "model": "claude-haiku-4-5-20251001",
5    "tokenLimit": 4096,
6    "temperature": 0.4,
7    "authentication": {
8      "type": "APIKey",
9      "credentials": {
10        "apiKey": "sk-ant-..."
11      }
12    },
13    "fields": {
14      "maxTokens": 2048
15    }
16  }
17}

Ollama Configuration:

1{
2  "service": {
3    "provider": "ollama",
4    "model": "qwen2.5-coder:7b",
5    "endpoint": "http://localhost:11434",
6    "tokenLimit": 2048,
7    "temperature": 0.4,
8    "authentication": {
9      "type": "None"
10    },
11    "fields": {
12      "numCtx": 4096,
13      "numPredict": 2048
14    }
15  }
16}

Supported Models

Coco's diff-condensing pipeline is bounded summarization (input: a diff, output: 1-3 sentences). The fast / cheap tier of each provider is the right default for it; the larger models are worth picking only when summary quality is more important than latency or cost.

OpenAI Models:

• gpt-4.1-nano (default — fastest / cheapest in the GPT-4.1 line)
• gpt-4.1-mini, gpt-4.1 (step up if you want richer summaries)
• gpt-4o, gpt-4o-mini (older but still solid)
• gpt-4-turbo, gpt-4, gpt-3.5-turbo (legacy — pin only if you have a reason)

Anthropic Models:

• claude-haiku-4-5-20251001 (default — current fast tier; right pick for diff condensing)
• claude-haiku-4-5, claude-sonnet-4-6, claude-opus-4-7 (current generation; pick the bigger model when quality matters more than speed)
• claude-sonnet-4-0 (earlier 4.x line)
• claude-3-7-sonnet-latest, claude-3-5-sonnet-latest, claude-3-5-haiku-latest, claude-3-opus-20240229, claude-3-sonnet-20240229, claude-3-haiku-20240307 (pre-4.x, kept for back-compat)

Ollama Models:

• qwen2.5-coder:7b (recommended for code)
• llama3.1:8b (recommended general purpose)
• deepseek-r1:8b, deepseek-r1:32b
• codellama:7b, codellama:13b, codellama:34b
• llama3.2:1b, llama3.2:3b
• And many more (see src/lib/langchain/types.ts for the full list)

Picking a model for coco: the diff-condensing pipeline doesn't reason or chain-of-thought; it summarizes. Default to your provider's fast tier and step up only when you've eyeballed a few generated commits and decided the quality isn't there. The defaults change over time as providers refresh their lineups — the values shipped in src/lib/langchain/utils.ts are the current recommendations.

Config Management

The coco init command simplifies the process of generating and updating your config file. When you run coco init, you'll be guided through an interactive setup process where you can customize your installation. This command can:

• Create a new config file in your chosen location
• Update an existing config with new settings
• Help you manage configurations across different scopes (global or project-specific)
• Set up AI provider authentication
• Configure conventional commits and commitlint integration

Configuration Examples

Complete Project Configuration

Here's an example of a comprehensive .coco.json file:

1{
2  "$schema": "https://git-co.co/schema.json",
3  "mode": "interactive",
4  "verbose": false,
5  "conventionalCommits": true,
6  "includeBranchName": true,
7  "openInEditor": false,
8  "defaultBranch": "main",
9  "logTui": {
10    "theme": {
11      "preset": "catppuccin",
12      "borderStyle": "round"
13    }
14  },
15  "ignoredFiles": [
16    "package-lock.json",
17    "yarn.lock",
18    "pnpm-lock.yaml",
19    "dist/*",
20    "build/*",
21    "node_modules/*"
22  ],
23  "ignoredExtensions": [
24    ".map",
25    ".lock",
26    ".min.js",
27    ".min.css"
28  ],
29  "service": {
30    "provider": "openai",
31    "model": "gpt-4o",
32    "tokenLimit": 4096,
33    "temperature": 0.3,
34    "maxConcurrent": 6,
35    "authentication": {
36      "type": "APIKey",
37      "credentials": {
38        "apiKey": "sk-..."
39      }
40    },
41    "requestOptions": {
42      "timeout": 60000,
43      "maxRetries": 3
44    },
45    "maxParsingAttempts": 3
46  }
47}

Git Configuration

You can also set coco configurations in your .gitconfig file:

1[user]
2    name = Your Name
3    email = your.email@example.com
4
5# -- Start coco config --
6[coco]
7    mode = interactive
8    conventionalCommits = true
9    defaultBranch = main
10    verbose = false
11    
12    # Service configuration
13    serviceProvider = openai
14    serviceModel = gpt-4o
15    serviceApiKey = sk-...
16    serviceTokenLimit = 4096
17    serviceTemperature = 0.3
18# -- End coco config --

Environment Variables

Set configuration options as environment variables. Coco reads COCO_* prefixed variables and maps them to config fields:

1# Core settings
2export COCO_MODE=interactive
3export COCO_VERBOSE=true
4export COCO_CONVENTIONAL_COMMITS=true
5export COCO_DEFAULT_BRANCH=main
6
7# Service configuration
8export COCO_SERVICE_PROVIDER=openai
9export COCO_SERVICE_MODEL=gpt-4o
10export COCO_SERVICE_API_KEY=sk-...          # or use OPENAI_API_KEY
11export COCO_SERVICE_TOKEN_LIMIT=4096
12export COCO_SERVICE_TEMPERATURE=0.3
13export COCO_SERVICE_BASE_URL=https://openrouter.ai/api/v1  # OpenAI-compatible endpoints
14export COCO_SERVICE_ENDPOINT=http://localhost:11434          # Ollama only
15
16# Dynamic model routing
17export COCO_SERVICE_DYNAMIC_MODEL_PREFERENCE=balanced
18export COCO_SERVICE_DYNAMIC_MODELS='{"summarize":"gpt-4.1-nano","commit":"gpt-4.1-mini"}'
19
20# File processing (comma-separated)
21export COCO_IGNORED_FILES="*.lock,dist/*,node_modules/*"
22export COCO_IGNORED_EXTENSIONS=".map,.min.js,.min.css"

Provider-specific API key environment variables (OPENAI_API_KEY, ANTHROPIC_API_KEY) are also recognized and used as fallbacks when the config does not include an explicit key.

Variable Naming Conventions

When using different configuration methods, follow these naming conventions:

Troubleshooting Configuration

Quick Check

Run coco doctor to scan your configuration for common issues:

1# Diagnose config problems
2coco doctor
3
4# Auto-fix what can be fixed (model upgrades, missing fields, etc.)
5coco doctor --fix

Common Issues

1. API Key Not Found

1# Set via environment variable
2export COCO_SERVICE_API_KEY=sk-...
3
4# Or add to config file
5{
6  "service": {
7    "authentication": {
8      "type": "APIKey", 
9      "credentials": {
10        "apiKey": "sk-..."
11      }
12    }
13  }
14}

2. pnpm Compatibility Issues

1# Update commitlint packages
2pnpm add -D @commitlint/config-conventional@latest @commitlint/cli@latest
3
4# Or disable commitlint validation
5{
6  "conventionalCommits": false
7}

3. Model Not Available

1# Check available models for your provider
2coco init --scope project
3
4# Or update to supported model
5{
6  "service": {
7    "model": "gpt-4o"  // Use supported model
8  }
9}

Validation

Use coco init to validate your configuration:

1# Validate current configuration
2coco init --scope project
3
4# Test with verbose output
5coco commit --verbose

Best Practices

1. Use Project-Specific Configs: Keep .coco.json in your project root for team consistency
2. Environment Variables for CI/CD: Use environment variables in automated environments
3. Git Config for Personal Settings: Use .gitconfig for personal preferences across projects
4. Secure API Keys: Never commit API keys to version control; use environment variables or git config
5. Start Simple: Begin with basic configuration and add complexity as needed
6. Run coco doctor: After upgrading coco or changing config, run coco doctor to catch issues
7. Regular Updates: Keep your configuration updated with new features and model improvements