Skip to content

Getting Started

Jump to bottom
Griffen Fargo edited this page Jun 9, 2026 · 4 revisions

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

More providers: coco also supports Google Gemini, Mistral, Azure OpenAI, and AWS Bedrock. Set service.provider accordingly — see the Configuration Overview for per-provider config and environment-variable keys.

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 commit

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

# Or force conventional commits format
coco commit --conventional

Heads up (0.57.0+): bare coco (no subcommand) is now a smart entry point — in a configured git repo it opens the coco ui workstation, not a commit. Always use coco commit for commit messages. See Smart default routing below.

Step 3: Review and Commit

Stdout Mode (Default):

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

# Or pipe directly
coco commit | git commit -F -

Interactive Mode:

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

Smart default routing

As of 0.57.0, running coco with no subcommand is a smart entry point — it looks at your environment and sends you to the right place instead of always running a commit:

Situation Where you land
No coco config yet (fresh install) coco init — the setup wizard
Configured and inside a git repo coco ui — the full workstation
Configured but not in a git repo coco workspace — the multi-repo view

This mirrors how lazygit, tig, and gitui behave (bare invocation opens the UI), and it means a fresh install no longer drops you straight into an API-key error.

To generate a commit message, call the subcommand explicitly:

coco commit              # stdout mode
coco commit -i           # interactive review/edit
coco commit --conventional

Scripts and aliases are safe: coco commit is unchanged. If you specifically want the old "bare coco = commit" behavior, pass --commit or set COCO_DEFAULT=commit in your environment.

Common Workflows

Daily Development Workflow

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

# 2. Stage changes
git add .

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

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

Conventional Commits Workflow

# Enable conventional commits
coco commit --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 commit

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

# Conventional commits format
coco commit -c, --conventional

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

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

Other Commands

# Generate changelog
coco changelog

# Summarize recent changes
coco recap --yesterday

# Code review
coco review

# Browse commit history interactively
coco log -i

# 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

"Commit Message Too Generic"

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

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

# Use interactive mode to edit
coco commit -i

"pnpm Compatibility Issues"

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

# Or disable commitlint validation temporarily
coco commit --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 commit --verbose

# 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