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)

bash

1# Try coco immediately without installation
2npx git-coco@latest init
3
4# Generate your first commit message
5npx git-coco@latest commit

Option 2: Global Installation

bash

1# Install globally with npm
2npm install -g git-coco
3
4# Or with yarn
5yarn global add git-coco
6
7# Or with pnpm
8pnpm add -g git-coco

Option 3: Project-Specific Installation

bash

1# Install in your project
2npm install --save-dev git-coco
3
4# Add to package.json scripts
5{
6  "scripts": {
7    "commit": "coco commit"
8  }
9}

First-Time Setup

Step 1: Run the Setup Wizard

bash

1# Interactive setup wizard
2coco init
3
4# Or specify scope directly
5coco init --scope global    # For all your projects
6coco init --scope project   # For current project only

The wizard will guide you through:

Choosing AI provider (OpenAI, Anthropic, or Ollama)
Setting up authentication (API keys or local models)
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:

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

Anthropic:

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

Ollama (Local):

See our Ollama Setup Guide for complete instructions

Your First Commit

Step 1: Make Some Changes

bash

1# Navigate to a git repository
2cd your-project
3
4# Make some changes to your code
5echo "console.log('Hello, coco!');" >> index.js
6
7# Stage your changes
8git add .

Step 2: Generate Commit Message

bash

1# Generate commit message (stdout mode)
2coco commit
3
4# Or use interactive mode for review/editing
5coco commit -i
6
7# Or force conventional commits format
8coco 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):

bash

1# Copy the generated message and commit manually
2git commit -m "$(coco commit)"
3
4# Or pipe directly
5coco commit | git commit -F -

Interactive Mode:

bash

# 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:

bash

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

bash

1# 1. Make your changes
2# ... edit files ...
3
4# 2. Stage changes
5git add .
6
7# 3. Generate and commit
8coco commit -i  # Interactive mode for review
9
10# Or for quick commits
11git commit -m "$(coco commit)"

Conventional Commits Workflow

bash

1# Enable conventional commits
2coco commit --conventional
3
4# Or set in config for always-on
5{
6  "conventionalCommits": true
7}
8
9# Generates: "feat: add user authentication system"
10# Instead of: "Add user authentication system"

Team Workflow

bash

1# Use project-specific config
2coco init --scope project
3
4# Commit the config file for team sharing
5git add .coco.config.json
6git commit -m "feat: add coco configuration for team"
7
8# Team members can now use consistent settings

Essential Commands

Commit Generation

bash

1# Basic commit generation
2coco commit
3
4# Interactive mode (recommended)
5coco commit -i, --interactive
6
7# Conventional commits format
8coco commit -c, --conventional
9
10# Add extra context
11coco commit -a "Fixes login bug" --additional "Fixes login bug"
12
13# Include commit history for context
14coco commit -p 3 --with-previous-commits 3

Other Commands

bash

1# Generate changelog
2coco changelog
3
4# Summarize recent changes
5coco recap --yesterday
6
7# Code review
8coco review
9
10# Browse commit history interactively
11coco log -i
12
13# Help and options
14coco --help
15coco commit --help

Configuration Basics

Quick Configuration

bash

1# Set interactive mode as default
2export COCO_MODE=interactive
3
4# Enable conventional commits
5export COCO_CONVENTIONAL_COMMITS=true
6
7# Set verbose output
8export COCO_VERBOSE=true

Project Configuration File

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

json

1{
2  "mode": "interactive",
3  "conventionalCommits": true,
4  "includeBranchName": true,
5  "service": {
6    "provider": "openai",
7    "model": "gpt-4o",
8    "authentication": {
9      "type": "APIKey",
10      "credentials": {
11        "apiKey": "your-api-key-here"
12      }
13    }
14  }
15}

Common Issues & Quick Fixes

"No API Key Found"

bash

1# Set API key via environment variable
2export OPENAI_API_KEY=sk-your-key-here
3
4# Or run setup again
5coco init

"Command Not Found"

bash

1# If installed globally, check PATH
2npm list -g git-coco
3
4# If installed locally, use npx
5npx coco
6
7# Or add to package.json scripts

"No Staged Changes"

bash

1# Stage your changes first
2git add .
3
4# Or stage specific files
5git add file1.js file2.js
6
7# Then generate commit
8coco commit

"Commit Message Too Generic"

bash

1# Add more context
2coco commit --additional "Resolves issue with user login timeout"
3
4# Include previous commits for context
5coco commit --with-previous-commits 2
6
7# Use interactive mode to edit
8coco commit -i

"pnpm Compatibility Issues"

bash

1# Update commitlint packages
2pnpm add -D @commitlint/config-conventional@latest @commitlint/cli@latest
3
4# Or disable commitlint validation temporarily
5coco commit --no-conventional

Next Steps

Explore Advanced Features

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

Team Adoption

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

Optimization

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

Getting Help

Documentation

Configuration Guide - Complete configuration reference
Ollama Setup - Local AI setup guide
File Ignoring - Customize file processing

Community

GitHub Issues - Bug reports and feature requests
Discord Community - Real-time help and discussion
GitHub Discussions - Community Q&A

Troubleshooting

bash

1# Enable verbose output for debugging
2coco commit --verbose
3
4# Check current configuration
5coco init --scope project
6
7# Test API connectivity
8curl -H "Authorization: Bearer $OPENAI_API_KEY" \
9  https://api.openai.com/v1/models

Success Tips

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

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