Skip to content

Config Overview

Jump to bottom
Griffen Fargo edited this page Oct 6, 2025 · 5 revisions

Configuration Overview

The .coco.config is a central piece in customizing and controlling the behavior of coco. It allows you to set project-level settings and is flexible enough to be defined in various locations, each with a specific order of priority.

Configuration Priority

coco determines its configuration based on a hierarchical priority system. If a configuration is specified in more than one place, the one with the highest priority will be used. The order of priority, from highest to lowest, is as follows:

  1. Command Line Flags: These are the highest priority and override all other settings. Useful for quick, one-off changes or testing.
  2. Environment Variables: Set configuration options as environment variables for broader scope.
  3. Project Config (.coco.config.json): This JSON file in your project root defines project-specific configurations. Ideal for settings that are specific to a single project.
  4. Git Profile (.gitconfig): Settings defined under a [coco] section in your .gitconfig. These are used unless overridden by higher-priority configurations.
  5. XDG Configuration Directory: If XDG_CONFIG_HOME is set, coco will look for a coco/config file in this directory.

Configuration Options

Core Settings

Option Type Default Description
mode "stdout" | "interactive" "stdout" Output destination for generated results
verbose boolean false Enable verbose logging
defaultBranch string "main" Default git branch for the repository

Conventional Commits

Option Type Default Description
conventionalCommits boolean false Generate commit messages in Conventional Commits format
includeBranchName boolean true Include current branch name in commit prompt for context
openInEditor boolean false Open commit message in editor for editing before proceeding

File Processing

Option Type Default Description
ignoredFiles string[] ["package-lock.json", ".gitignore", ".ignore"] File paths or patterns to ignore (uses minimatch)
ignoredExtensions string[] [".map", ".lock"] File extensions to ignore during processing

AI Prompts

Option Type Default Description
prompt string - Custom prompt text for generating results
summarizePrompt string - Custom prompt for summarizing large files

Service Configuration

The service object configures the AI provider and model settings:

Provider Options

OpenAI Configuration:

{
  "service": {
    "provider": "openai",
    "model": "gpt-4o",
    "tokenLimit": 2048,
    "temperature": 0.4,
    "maxConcurrent": 6,
    "authentication": {
      "type": "APIKey",
      "credentials": {
        "apiKey": "sk-..."
      }
    },
    "requestOptions": {
      "timeout": 30000,
      "maxRetries": 3
    },
    "maxParsingAttempts": 3,
    "fields": {
      "topP": 1.0,
      "frequencyPenalty": 0.0,
      "presencePenalty": 0.0
    }
  }
}

Anthropic Configuration:

{
  "service": {
    "provider": "anthropic",
    "model": "claude-3-5-sonnet-latest",
    "tokenLimit": 2048,
    "temperature": 0.4,
    "authentication": {
      "type": "APIKey",
      "credentials": {
        "apiKey": "sk-ant-..."
      }
    },
    "fields": {
      "maxTokens": 2048
    }
  }
}

Ollama Configuration:

{
  "service": {
    "provider": "ollama",
    "model": "llama3.1:8b",
    "endpoint": "http://localhost:11434",
    "tokenLimit": 2048,
    "temperature": 0.4,
    "authentication": {
      "type": "None"
    },
    "fields": {
      "numCtx": 4096,
      "numPredict": 2048
    }
  }
}

Supported Models

OpenAI Models:

  • gpt-4o (recommended)
  • gpt-4o-mini
  • gpt-4-turbo
  • gpt-4
  • gpt-3.5-turbo

Anthropic Models:

  • claude-3-5-sonnet-latest (recommended)
  • claude-3-5-haiku-latest
  • claude-3-opus-20240229
  • claude-3-sonnet-20240229
  • claude-3-haiku-20240307

Ollama Models:

  • llama3.1:8b (recommended)
  • llama3.1:70b
  • codellama:13b
  • deepseek-r1:8b
  • qwen2.5-coder:7b
  • And many more (see full list in configuration)

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.config.json file:

{
  "$schema": "https://git-co.co/schema.json",
  "mode": "interactive",
  "verbose": false,
  "conventionalCommits": true,
  "includeBranchName": true,
  "openInEditor": false,
  "defaultBranch": "main",
  "ignoredFiles": [
    "package-lock.json",
    "yarn.lock",
    "pnpm-lock.yaml",
    "dist/*",
    "build/*",
    "node_modules/*"
  ],
  "ignoredExtensions": [
    ".map",
    ".lock",
    ".min.js",
    ".min.css"
  ],
  "service": {
    "provider": "openai",
    "model": "gpt-4o",
    "tokenLimit": 4096,
    "temperature": 0.3,
    "maxConcurrent": 6,
    "authentication": {
      "type": "APIKey",
      "credentials": {
        "apiKey": "sk-..."
      }
    },
    "requestOptions": {
      "timeout": 60000,
      "maxRetries": 3
    },
    "maxParsingAttempts": 3
  }
}

Git Configuration

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

[user]
    name = Your Name
    email = [email protected]

# -- Start coco config --
[coco]
    mode = interactive
    conventionalCommits = true
    defaultBranch = main
    verbose = false
    
    # Service configuration
    serviceProvider = openai
    serviceModel = gpt-4o
    serviceApiKey = sk-...
    serviceTokenLimit = 4096
    serviceTemperature = 0.3
# -- End coco config --

Environment Variables

Set configuration options as environment variables using UPPER_SNAKE_CASE:

# Core settings
export COCO_MODE=interactive
export COCO_VERBOSE=true
export COCO_CONVENTIONAL_COMMITS=true
export COCO_DEFAULT_BRANCH=main

# Service configuration
export COCO_SERVICE_PROVIDER=openai
export COCO_SERVICE_MODEL=gpt-4o
export COCO_SERVICE_API_KEY=sk-...
export COCO_SERVICE_TOKEN_LIMIT=4096
export COCO_SERVICE_TEMPERATURE=0.3

# File processing
export COCO_IGNORED_FILES="*.lock,dist/*,node_modules/*"
export COCO_IGNORED_EXTENSIONS=".map,.min.js,.min.css"

Variable Naming Conventions

When using different configuration methods, follow these naming conventions:

Config File Environment Variable Git Config CLI Flag
mode COCO_MODE coco.mode --mode
conventionalCommits COCO_CONVENTIONAL_COMMITS coco.conventionalCommits --conventional
includeBranchName COCO_INCLUDE_BRANCH_NAME coco.includeBranchName --include-branch-name
service.provider COCO_SERVICE_PROVIDER coco.serviceProvider N/A
service.model COCO_SERVICE_MODEL coco.serviceModel N/A
service.apiKey COCO_SERVICE_API_KEY coco.serviceApiKey N/A

Troubleshooting Configuration

Common Issues

1. API Key Not Found

# Set via environment variable
export COCO_SERVICE_API_KEY=sk-...

# Or add to config file
{
  "service": {
    "authentication": {
      "type": "APIKey", 
      "credentials": {
        "apiKey": "sk-..."
      }
    }
  }
}

2. pnpm Compatibility Issues

# Update commitlint packages
pnpm add -D @commitlint/config-conventional@latest @commitlint/cli@latest

# Or disable commitlint validation
{
  "conventionalCommits": false
}

3. Model Not Available

# Check available models for your provider
coco init --scope project

# Or update to supported model
{
  "service": {
    "model": "gpt-4o"  // Use supported model
  }
}

Validation

Use coco init to validate your configuration:

# Validate current configuration
coco init --scope project

# Test with verbose output
coco --verbose commit

Best Practices

  1. Use Project-Specific Configs: Keep .coco.config.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. Regular Updates: Keep your configuration updated with new features and model improvements

Clone this wiki locally