coco

An AI-powered git assistant that generates meaningful commit messages, creates changelogs, explores repository history, and streamlines your development workflow.

✨ Key Features:

• 🤖 AI-Powered Commit Messages - Generate contextual commits from your staged changes
• 📋 Conventional Commits - Full support with automatic validation and formatting
• 🔧 Commitlint Integration - Seamless integration with your existing commitlint configuration
• 🏠 Local AI Support - Run completely offline with Ollama (no API costs, full privacy)
• 🖥️ Coco UI Git Workstation - Seven top-level views (history, status, diff, compose, branches, tags, stash) reachable via g-prefixed chords, with an interactive command palette (:) and global search (/)
• 📦 Package Manager Friendly - Works with npm, yarn, and pnpm
• 👥 Team Ready - Shared configurations and enterprise deployment

Quick Start

# Try without installing
npx git-coco@latest init

# Install globally  
npm install -g git-coco

# Setup and configure
coco init

# Generate your first commit
git add .
coco -i

Commands

• coco commit - Generate commit messages from staged changes
• coco changelog - Create changelogs from commit history
• coco recap - Summarize recent changes and activity
• coco review - AI-powered code review of your changes
• coco log - Explore commit history with graph, filters, JSON output, and commit details
• coco ui - Open the full-screen Git workstation TUI
• coco init - Interactive setup wizard

Usage Examples

Basic Workflow

# Make your changes
git add .

# Generate commit message (interactive mode recommended)
coco -i

# Or use stdout mode
git commit -m "$(coco)"

Conventional Commits

# Enable conventional commits format
coco --conventional

# With additional context
coco -a "Fixes login timeout" --conventional

# Include ticket from branch name
coco --append-ticket --conventional

Team Workflows

# Generate changelog for releases
coco changelog --since-last-tag

# Summarize recent work
coco recap --yesterday

# Code review before committing
coco review

# Explore commit history
coco ui
coco ui --view status
coco log --limit 20
coco log -i
coco log --view full --limit 20
coco log --all --limit 20
coco log --author "Grace Hopper" --path src
coco log --commit HEAD
coco log --format json

Navigating the TUI

coco ui and coco log -i share a chord-driven navigation model. Press g and then a second key to jump anywhere; < (or Esc) pops the navigation stack back.

g h   history          g c   compose         <    back
g s   status           g b   branches        Esc  back / close modal
g d   diff             g t   tags            ?    help overlay
                       g z   stash           :    command palette

The command palette (:) is an interactive launcher with fuzzy filter and recently-used at the top — every keybinding and workflow action is reachable from there. / searches the active view (history, branches, tags, or stash). See the Coco UI wiki page for the full keymap.

Configuration

Configure coco for your workflow with the interactive setup wizard:

# Setup wizard
coco init

# Project-specific setup
coco init --scope project

AI Providers:

• OpenAI - GPT-4o, GPT-4o-mini (API key required)
• Anthropic - Claude 3.5 Sonnet (API key required)
• Ollama - Local models, no API costs, full privacy

Example Configuration:

{
  "mode": "interactive",
  "conventionalCommits": true,
  "logTui": {
    "theme": {
      "preset": "catppuccin"
    }
  },
  "service": {
    "provider": "openai",
    "model": "gpt-4o"
  }
}

Documentation

For comprehensive guides, advanced usage, and detailed configuration options, visit our complete documentation:

📚 Coco Wiki

Essential Guides:

• Getting Started - Complete beginner's guide from installation to first commit
• Command Reference - Detailed command options and examples
• Configuration Overview - All configuration options and setup methods
• Coco UI - GitKraken-style terminal workstation guide
• Interactive Log TUI - History-focused coco log -i guide
• Team Collaboration - Enterprise deployment and team adoption strategies

Advanced Resources:

• Using Ollama - Local AI setup for privacy and cost control
• Advanced Usage - Custom prompts, automation, and power-user features
• Troubleshooting - Solutions for common issues and debugging

🆘 Need Help?

• Troubleshooting Guide - Comprehensive problem-solving resource
• GitHub Issues - Bug reports and feature requests
• Discord Community - Real-time help and discussion

Contribution

We welcome contributions! Check out our CONTRIBUTING.md for more information.

Project Stats

License

MIT © gfargo

Thanks for using coco ✨💜