1# Check coco version and basic info
2coco --version
3
4# Verbose output shows detailed processing
5coco commit --verbose
6
7# Validate current configuration
8coco init --scope project
9
10# Test with minimal config
11COCO_VERBOSE=true coco commit

1# Check if installed globally
2npm list -g git-coco
3
4# If not installed, install globally
5npm install -g git-coco
6
7# Check PATH includes npm global bin
8npm config get prefix
9echo $PATH
10
11# Alternative: Use npx (no installation needed)
12npx git-coco@latest commit
13
14# For project-specific installation
15npm install --save-dev git-coco
16npx coco commit

1# Use npx instead (recommended)
2npx git-coco@latest init
3
4# Or fix npm permissions (macOS/Linux)
5sudo chown -R $(whoami) $(npm config get prefix)/{lib/node_modules,bin,share}
6
7# Or use a Node version manager
8# Install nvm, then:
9nvm install node
10npm install -g git-coco

1# Clear npm cache
2npm cache clean --force
3
4# Reinstall coco
5npm uninstall -g git-coco
6npm install -g git-coco@latest
7
8# Check Node.js version (requires Node 16+)
9node --version
10
11# Update Node.js if needed
12nvm install --lts
13nvm use --lts

1# Set via environment variable (temporary)
2export OPENAI_API_KEY=sk-your-key-here
3export ANTHROPIC_API_KEY=sk-ant-your-key-here
4
5# Set via configuration file (permanent)
6coco init --scope project
7
8# Verify API key format
9# OpenAI: starts with "sk-"
10# Anthropic: starts with "sk-ant-"
11
12# Test API key directly
13curl -H "Authorization: Bearer $OPENAI_API_KEY" \
14  https://api.openai.com/v1/models

1# Verify API key is correct (no extra spaces/characters)
2echo "$OPENAI_API_KEY" | wc -c  # Should be ~51 characters
3
4# Check API key permissions and billing
5# Visit: https://platform.openai.com/account/billing
6
7# Regenerate API key if needed
8# Visit: https://platform.openai.com/api-keys
9
10# Test with curl
11curl -H "Authorization: Bearer $OPENAI_API_KEY" \
12  -H "Content-Type: application/json" \
13  -d '{"model":"gpt-3.5-turbo","messages":[{"role":"user","content":"test"}],"max_tokens":5}' \
14  https://api.openai.com/v1/chat/completions

1# Check usage and billing limits
2# Visit: https://platform.openai.com/account/usage
3
4# Reduce concurrent requests
5{
6  "service": {
7    "maxConcurrent": 1,
8    "requestOptions": {
9      "timeout": 60000,
10      "maxRetries": 2
11    }
12  }
13}
14
15# Use smaller token limits
16{
17  "service": {
18    "tokenLimit": 1024
19  }
20}
21
22# Switch to different model (if quota per model)
23{
24  "service": {
25    "model": "gpt-3.5-turbo"  // Instead of gpt-4
26  }
27}

1# Initialize git repository
2git init
3
4# Or navigate to existing git repository
5cd /path/to/your/git/repo
6
7# Verify you're in a git repository
8git status

1# Stage your changes first
2git add .
3
4# Or stage specific files
5git add file1.js file2.js
6
7# Check what's staged
8git diff --cached
9
10# If files are already committed, make new changes
11echo "// New change" >> file.js
12git add file.js

1# Stage changes you want to commit
2git add .
3
4# Or stash changes temporarily
5git stash
6# ... use coco ...
7git stash pop
8
9# Or commit existing changes first
10git commit -m "WIP: temporary commit"

1# Update commitlint packages to latest
2pnpm add -D @commitlint/config-conventional@latest @commitlint/cli@latest
3
4# Or disable commitlint validation temporarily
5coco commit --no-conventional
6
7# Or use npm/yarn instead for coco
8npm install -g git-coco

1# Install coco globally instead of in project
2npm install -g git-coco
3
4# Or use npx
5npx git-coco@latest commit
6
7# Or disable PnP for this project
8echo 'nodeLinker: node-modules' >> .yarnrc.yml
9yarn install

1# Check commitlint configuration
2cat .commitlintrc.json
3# or
4cat commitlint.config.js
5
6# Test commitlint directly
7echo "feat: test message" | npx commitlint
8
9# Update commitlint packages
10npm install --save-dev @commitlint/config-conventional@latest @commitlint/cli@latest
11
12# Disable validation temporarily
13coco commit --no-conventional
14
15# Use interactive mode to edit message
16coco commit -i

1# Enable conventional commits mode
2coco commit --conventional
3
4# Or set in configuration
5{
6  "conventionalCommits": true
7}
8
9# Check valid commit types
10# feat, fix, docs, style, refactor, perf, test, build, ci, chore, revert
11
12# Example valid formats:
13# feat: add new feature
14# fix(auth): resolve login issue
15# feat!: breaking change

1# Create commitlint config file
2echo 'module.exports = {extends: ["@commitlint/config-conventional"]}' > commitlint.config.js
3
4# Or JSON format
5echo '{"extends": ["@commitlint/config-conventional"]}' > .commitlintrc.json
6
7# Install required packages
8npm install --save-dev @commitlint/config-conventional @commitlint/cli
9
10# Verify configuration
11npx commitlint --help-config

1# Check available models for your provider
2# OpenAI models: gpt-4o, gpt-4o-mini, gpt-4-turbo, gpt-3.5-turbo
3# Anthropic models: claude-3-5-sonnet-latest, claude-3-haiku-latest
4
5# Update to supported model
6{
7  "service": {
8    "model": "gpt-4o"  // Use current model name
9  }
10}
11
12# For Ollama, pull the model first
13ollama pull qwen2.5-coder:7b

1# Increase timeout settings
2{
3  "service": {
4    "requestOptions": {
5      "timeout": 120000,  // 2 minutes
6      "maxRetries": 3
7    }
8  }
9}
10
11# Check internet connection
12curl -I https://api.openai.com
13
14# Check firewall/proxy settings
15# Corporate networks may block AI APIs
16
17# For Ollama, check service is running
18curl http://localhost:11434/api/version

1# Add more context
2coco commit --additional "Fixes user login timeout issue"
3
4# Include previous commits for context
5coco commit --with-previous-commits 3
6
7# Use interactive mode to edit
8coco commit -i
9
10# Ignore irrelevant files
11coco commit --ignored-files "*.lock" --ignored-extensions ".map"
12
13# Try different model
14{
15  "service": {
16    "model": "gpt-4o",  // Instead of gpt-3.5-turbo
17    "temperature": 0.3  // Lower for more consistent output
18  }
19}

1# Enable verbose mode to see raw response
2coco commit --verbose
3
4# Increase parsing attempts for Ollama
5{
6  "service": {
7    "maxParsingAttempts": 5  // Higher for local models
8  }
9}
10
11# Try different model (some are more reliable)
12{
13  "service": {
14    "model": "gpt-4o"  // More reliable than older models
15  }
16}
17
18# Check if using latest coco version
19npm update -g git-coco

1# Reduce token limits
2{
3  "service": {
4    "tokenLimit": 1024  // Instead of 4096
5  }
6}
7
8# Ignore large/irrelevant files
9{
10  "ignoredFiles": ["dist/*", "node_modules/*", "*.lock"],
11  "ignoredExtensions": [".map", ".min.js", ".bundle.js"]
12}
13
14# Use faster model
15{
16  "service": {
17    "model": "gpt-3.5-turbo"  // Faster than gpt-4
18  }
19}
20
21# For Ollama, use smaller model
22ollama pull qwen2.5-coder:3b  # Instead of 7b or larger

1# Ignore large files and directories
2{
3  "ignoredFiles": [
4    "node_modules/**",
5    "dist/**", 
6    "build/**",
7    "*.{jpg,png,gif,pdf,zip}"
8  ]
9}
10
11# Use --no-diff for very large changesets
12coco commit --no-diff
13
14# For Ollama, use appropriate model size for your RAM
15# 8GB RAM: use 3b models
16# 16GB RAM: use 7b models
17# 32GB+ RAM: use 14b+ models

1# Check configuration priority order:
2# 1. Command line flags (highest)
3# 2. Environment variables
4# 3. .coco.config.json (project)
5# 4. .gitconfig
6# 5. XDG config (lowest)
7
8# Verify config file syntax
9cat .coco.config.json | jq .  # Should parse without errors
10
11# Check environment variables
12env | grep COCO
13
14# Test with explicit config
15coco commit --verbose --mode interactive

1# Validate JSON syntax
2cat .coco.config.json | jq .
3
4# Check against schema
5# Visit: https://git-co.co/schema.json
6
7# Regenerate config with wizard
8coco init --scope project
9
10# Common fixes:
11{
12  "$schema": "https://git-co.co/schema.json",
13  "service": {
14    "provider": "openai",  // Must be: openai, anthropic, or ollama
15    "model": "gpt-4o",     // Must be valid model name
16    "authentication": {
17      "type": "APIKey",    // Must be: APIKey, OAuth, or None
18      "credentials": {
19        "apiKey": "sk-..."
20      }
21    }
22  }
23}

1# Use PowerShell or Command Prompt as Administrator
2# Install with npm (not yarn) on Windows
3
4# For WSL users
5wsl --install
6# Then install coco inside WSL
7
8# Path issues
9npm config get prefix
10# Add to PATH in System Environment Variables
11
12# Use npx to avoid installation issues
13npx git-coco@latest commit

1# Allow Terminal full disk access
2# System Preferences > Security & Privacy > Privacy > Full Disk Access
3
4# Install Xcode Command Line Tools
5xcode-select --install
6
7# Use Homebrew for Node.js
8brew install node
9npm install -g git-coco

1# Install Node.js via package manager
2curl -fsSL https://deb.nodesource.com/setup_lts.x | sudo -E bash -
3sudo apt-get install -y nodejs
4
5# Fix npm permissions
6mkdir ~/.npm-global
7npm config set prefix '~/.npm-global'
8echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
9source ~/.bashrc
10
11# Install coco
12npm install -g git-coco

1# Maximum verbosity
2COCO_VERBOSE=true coco --verbose commit
3
4# Debug specific components
5DEBUG=coco:* coco commit  # If debug logging is implemented

1# System information
2node --version
3npm --version
4git --version
5coco --version
6
7# Configuration
8coco init --scope project  # Shows current config
9
10# Test basic functionality
11echo "test" > test.txt
12git add test.txt
13coco commit --verbose

1# Use without installation
2npx git-coco@latest commit
3
4# Generate commit manually with AI
5curl -X POST https://api.openai.com/v1/chat/completions \
6  -H "Authorization: Bearer $OPENAI_API_KEY" \
7  -H "Content-Type: application/json" \
8  -d '{
9    "model": "gpt-3.5-turbo",
10    "messages": [{"role": "user", "content": "Generate a commit message for: $(git diff --cached)"}],
11    "max_tokens": 100
12  }'
13
14# Fallback to manual commits
15git commit -m "fix: manual commit while debugging coco"