Skip to content

Getting Started

Jump to bottom
Griffen Fargo edited this page Oct 6, 2025 · 1 revision

Welcome to coco! This guide will take you from installation to generating your first AI-powered commit message in just a few minutes.

What is Coco?

coco is an AI-powered git assistant that generates meaningful commit messages from your staged changes. It supports:

  • 🤖 Smart commit generation from code changes
  • 📋 Conventional commits with automatic validation
  • 🔧 Commitlint integration for team consistency
  • 🏠 Local AI models (Ollama) or cloud APIs (OpenAI, Anthropic)
  • 📦 All package managers (npm, yarn, pnpm)

Quick Installation

Option 1: Use Without Installing (Recommended for First Try)

# Try coco immediately without installation
npx git-coco@latest init

# Generate your first commit message
npx git-coco@latest commit

Option 2: Global Installation

# Install globally with npm
npm install -g git-coco

# Or with yarn
yarn global add git-coco

# Or with pnpm
pnpm add -g git-coco

Option 3: Project-Specific Installation

# Install in your project
npm install --save-dev git-coco

# Add to package.json scripts
{
  "scripts": {
    "commit": "coco commit"
  }
}

First-Time Setup

Step 1: Run the Setup Wizard

# Interactive setup wizard
coco init

# Or specify scope directly
coco init --scope global    # For all your projects
coco init --scope project   # For current project only

The wizard will guide you through:

  1. Choosing AI provider (OpenAI, Anthropic, or Ollama)
  2. Setting up authentication (API keys or local models)
  3. Configuring preferences (conventional commits, interactive mode, etc.)

Step 2: Choose Your AI Provider

For Beginners (Recommended): OpenAI

  • Most reliable and fast
  • Excellent commit message quality
  • Requires API key (~$0.01-0.05 per commit)

For Privacy/Cost-Conscious: Ollama

  • Completely local and private
  • No API costs after setup
  • Requires more setup and hardware

For Advanced Users: Anthropic Claude

  • Excellent reasoning capabilities
  • Great for complex codebases
  • Requires API key

Step 3: Get Your API Key (if using cloud providers)

OpenAI:

  1. Go to platform.openai.com
  2. Create account and add billing method
  3. Generate API key in API Keys section
  4. Copy the key (starts with sk-)

Anthropic:

  1. Go to console.anthropic.com
  2. Create account and add billing method
  3. Generate API key in API Keys section
  4. Copy the key (starts with sk-ant-)

Ollama (Local):

Your First Commit

Step 1: Make Some Changes

# Navigate to a git repository
cd your-project

# Make some changes to your code
echo "console.log('Hello, coco!');" >> index.js

# Stage your changes
git add .

Step 2: Generate Commit Message

# Generate commit message (stdout mode)
coco

# Or use interactive mode for review/editing
coco -i

# Or force conventional commits format
coco --conventional

Step 3: Review and Commit

Stdout Mode (Default):

# Copy the generated message and commit manually
git commit -m "$(coco)"

# Or pipe directly
coco | git commit -F -

Interactive Mode:

# Review, edit, and commit in one step
coco -i

Common Workflows

Daily Development Workflow

# 1. Make your changes
# ... edit files ...

# 2. Stage changes
git add .

# 3. Generate and commit
coco -i  # Interactive mode for review

# Or for quick commits
git commit -m "$(coco)"

Conventional Commits Workflow

# Enable conventional commits
coco --conventional

# Or set in config for always-on
{
  "conventionalCommits": true
}

# Generates: "feat: add user authentication system"
# Instead of: "Add user authentication system"

Team Workflow

# Use project-specific config
coco init --scope project

# Commit the config file for team sharing
git add .coco.config.json
git commit -m "feat: add coco configuration for team"

# Team members can now use consistent settings

Essential Commands

Commit Generation

# Basic commit generation
coco

# Interactive mode (recommended)
coco -i, --interactive

# Conventional commits format
coco -c, --conventional

# Add extra context
coco -a "Fixes login bug" --additional "Fixes login bug"

# Include commit history for context
coco -p 3 --with-previous-commits 3

Other Commands

# Generate changelog
coco changelog

# Summarize recent changes
coco recap --yesterday

# Code review
coco review

# Help and options
coco --help
coco commit --help

Configuration Basics

Quick Configuration

# Set interactive mode as default
export COCO_MODE=interactive

# Enable conventional commits
export COCO_CONVENTIONAL_COMMITS=true

# Set verbose output
export COCO_VERBOSE=true

Project Configuration File

Create .coco.config.json in your project root:

{
  "mode": "interactive",
  "conventionalCommits": true,
  "includeBranchName": true,
  "service": {
    "provider": "openai",
    "model": "gpt-4o",
    "authentication": {
      "type": "APIKey",
      "credentials": {
        "apiKey": "your-api-key-here"
      }
    }
  }
}

Common Issues & Quick Fixes

"No API Key Found"

# Set API key via environment variable
export OPENAI_API_KEY=sk-your-key-here

# Or run setup again
coco init

"Command Not Found"

# If installed globally, check PATH
npm list -g git-coco

# If installed locally, use npx
npx coco

# Or add to package.json scripts

"No Staged Changes"

# Stage your changes first
git add .

# Or stage specific files
git add file1.js file2.js

# Then generate commit
coco

"Commit Message Too Generic"

# Add more context
coco --additional "Resolves issue with user login timeout"

# Include previous commits for context
coco --with-previous-commits 2

# Use interactive mode to edit
coco -i

"pnpm Compatibility Issues"

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

# Or disable commitlint validation temporarily
coco --no-conventional

Next Steps

Explore Advanced Features

  1. Read the Configuration Guide for detailed customization
  2. Set up Ollama for local, private AI
  3. Configure file ignoring for better focus
  4. Explore conventional commits for better project history

Team Adoption

  1. Share your .coco.config.json with your team
  2. Set up git hooks for automated commit generation
  3. Integrate with CI/CD for consistent commit standards
  4. Train your team on conventional commits best practices

Optimization

  1. Monitor API costs and optimize token usage
  2. Fine-tune prompts for your specific project needs
  3. Set up shortcuts and aliases for common workflows
  4. Integrate with your IDE for seamless development

Getting Help

Documentation

Community

Troubleshooting

# Enable verbose output for debugging
coco --verbose commit

# Check current configuration
coco init --scope project

# Test API connectivity
curl -H "Authorization: Bearer $OPENAI_API_KEY" \
  https://api.openai.com/v1/models

Success Tips

  1. Start simple - Use default settings first, customize later
  2. Use interactive mode - Review and edit messages before committing
  3. Enable conventional commits - Better project history and automation
  4. Ignore irrelevant files - Focus on meaningful changes
  5. Add context when needed - Use --additional for complex changes
  6. Share team config - Consistent commit styles across the team

Welcome to smarter, AI-powered git workflows with coco! 🚀

Clone this wiki locally