Advanced Usage

This guide covers advanced features, customization options, and power-user techniques for getting the most out of coco in complex development environments.

Custom Prompts & Templates

Understanding Prompt Variables

coco uses template variables that are dynamically replaced during commit generation:

// Available variables in prompts
{
  summary: "Diff summary of staged changes",
  format_instructions: "JSON schema instructions", 
  additional_context: "User-provided context via --additional",
  commit_history: "Previous commits when --with-previous-commits used",
  branch_name_context: "Current branch name (if enabled)",
  commitlint_rules_context: "Project commitlint rules"
}

Custom Commit Prompts

Basic Custom Prompt:

{
  "prompt": "Generate a concise commit message for a TypeScript React project. Focus on user-facing changes and use conventional commits format.\n\nChanges:\n{{summary}}\n\n{{format_instructions}}"
}

Advanced Custom Prompt with Context:

{
  "prompt": "You are a senior developer writing commit messages for a fintech application. Security and compliance are critical.\n\nCode Changes:\n{{summary}}\n\nBranch Context: {{branch_name_context}}\n\nProject Rules:\n{{commitlint_rules_context}}\n\nAdditional Context:\n{{additional_context}}\n\nGenerate a professional commit message that:\n1. Follows conventional commits format\n2. Mentions security implications if relevant\n3. Is clear for compliance audits\n4. Uses imperative mood\n\n{{format_instructions}}"
}

Domain-Specific Prompts:

E-commerce Platform:

{
  "prompt": "Generate a commit message for an e-commerce platform. Focus on:\n- Customer impact (UX, performance, features)\n- Business logic changes\n- Payment/security implications\n- Mobile responsiveness\n\nChanges: {{summary}}\n\n{{format_instructions}}"
}

DevOps/Infrastructure:

{
  "prompt": "Generate a commit message for infrastructure/DevOps changes. Focus on:\n- System reliability and performance\n- Security and compliance\n- Deployment and scaling impact\n- Monitoring and observability\n\nChanges: {{summary}}\n\n{{format_instructions}}"
}

Custom Summarize Prompts

For large file changes, customize the summarization:

{
  "summarizePrompt": "Summarize these code changes focusing on:\n1. Business logic modifications\n2. API changes\n3. Database schema updates\n4. Security implications\n5. Performance impacts\n\nKeep summary under 200 words and highlight the most important changes.\n\nCode changes:\n{{content}}"
}

Multi-Project Configuration

Workspace-Level Configuration

Monorepo Setup:

# Root workspace config
.coco.config.json              # Default for all projects

# Project-specific overrides  
packages/frontend/.coco.config.json
packages/backend/.coco.config.json
packages/mobile/.coco.config.json

Root Configuration:

{
  "mode": "interactive",
  "conventionalCommits": true,
  "includeBranchName": true,
  "service": {
    "provider": "openai",
    "model": "gpt-4o",
    "temperature": 0.3
  },
  "ignoredFiles": [
    "node_modules/**",
    "dist/**",
    "build/**"
  ]
}

Frontend Override:

{
  "prompt": "Generate commit message for React frontend changes. Focus on UI/UX improvements, component changes, and user-facing features.\n\n{{summary}}\n\n{{format_instructions}}",
  "ignoredFiles": [
    "public/build/**",
    "src/**/*.css.map",
    "coverage/**"
  ]
}

Backend Override:

{
  "prompt": "Generate commit message for Node.js backend changes. Focus on API changes, database modifications, business logic, and security implications.\n\n{{summary}}\n\n{{format_instructions}}",
  "ignoredFiles": [
    "logs/**",
    "uploads/**",
    "*.log"
  ]
}

Environment-Specific Configurations

Development Environment:

export COCO_MODE=interactive
export COCO_VERBOSE=true
export COCO_SERVICE_TEMPERATURE=0.4  # More creative

Production/CI Environment:

export COCO_MODE=stdout
export COCO_VERBOSE=false
export COCO_SERVICE_TEMPERATURE=0.2  # More deterministic
export COCO_SERVICE_TOKEN_LIMIT=1024  # Cost control

Team Lead Configuration:

export COCO_WITH_PREVIOUS_COMMITS=5  # More context
export COCO_SERVICE_MODEL=gpt-4o     # Best quality

Automation & Scripting

Git Aliases

Add to your .gitconfig:

[alias]
    # Smart commit with coco
    cc = "!f() { git add . && coco -i; }; f"
    
    # Quick conventional commit
    ccf = "!f() { git add . && coco --conventional; }; f"
    
    # Commit with context
    ccc = "!f() { git add . && coco -a \"$1\" -i; }; f"
    
    # Generate changelog
    cl = "!coco changelog"
    
    # Weekly recap
    recap = "!coco recap --last-week"

Usage:

git cc                           # Interactive commit
git ccf                          # Fast conventional commit
git ccc "Fixes login timeout"    # Commit with context
git cl                           # Generate changelog
git recap                        # Weekly summary

Shell Functions

Add to your .bashrc or .zshrc:

# Smart commit function
commit() {
    if [ $# -eq 0 ]; then
        # No arguments - interactive mode
        git add . && coco -i
    else
        # With message - add context
        git add . && coco -a "$*" -i
    fi
}

# Quick conventional commit
ccommit() {
    git add . && coco --conventional --append-ticket
}

# Commit specific files with context
commitf() {
    local files="$1"
    shift
    git add "$files" && coco -a "$*" -i
}

# Generate and show changelog
changelog() {
    local range="${1:-HEAD~10:HEAD}"
    coco changelog -r "$range" | less
}

Advanced Scripting

Batch Commit Processing:

#!/bin/bash
# batch-commit.sh - Process multiple staged changes

# Check for staged changes
if ! git diff --cached --quiet; then
    echo "Processing staged changes..."
    
    # Generate commit with context
    if [ -n "$1" ]; then
        commit_msg=$(coco -a "$1")
    else
        commit_msg=$(coco)
    fi
    
    # Show generated message
    echo "Generated commit message:"
    echo "$commit_msg"
    echo
    
    # Confirm before committing
    read -p "Commit with this message? (y/n): " -n 1 -r
    echo
    
    if [[ $REPLY =~ ^[Yy]$ ]]; then
        git commit -m "$commit_msg"
        echo "Committed successfully!"
    else
        echo "Commit cancelled."
    fi
else
    echo "No staged changes found."
fi

Smart Branch Workflow:

#!/bin/bash
# smart-workflow.sh - Intelligent branch-based commits

branch=$(git branch --show-current)
ticket=$(echo "$branch" | grep -oE '[A-Z]+-[0-9]+')

case "$branch" in
    feature/*)
        coco --conventional --append-ticket -a "Feature implementation"
        ;;
    fix/*)
        coco --conventional --append-ticket -a "Bug fix"
        ;;
    hotfix/*)
        coco --conventional --append-ticket -a "Critical hotfix"
        ;;
    *)
        coco --conventional
        ;;
esac

Performance Optimization

Token Usage Optimization

Reduce Token Consumption:

{
  "service": {
    "tokenLimit": 1024,        // Reduce from default 2048
    "temperature": 0.2         // More deterministic, less tokens
  },
  "ignoredFiles": [
    "**/*.{map,min.js,min.css}",  // Ignore generated files
    "node_modules/**",
    "dist/**",
    "coverage/**"
  ],
  "ignoredExtensions": [
    ".log", ".tmp", ".cache", ".lock"
  ]
}

Smart File Filtering:

{
  "ignoredFiles": [
    // Large generated files
    "package-lock.json",
    "yarn.lock", 
    "pnpm-lock.yaml",
    
    // Build outputs
    "dist/**",
    "build/**", 
    ".next/**",
    
    // Test outputs
    "coverage/**",
    "test-results/**",
    
    // Logs and temps
    "*.log",
    "tmp/**",
    ".cache/**"
  ]
}

Caching Strategies

Environment-Based Caching:

# Cache API responses for development
export COCO_CACHE_DIR="$HOME/.coco/cache"
export COCO_CACHE_TTL=3600  # 1 hour cache

# Disable caching in CI
export COCO_CACHE_DISABLED=true

Model Selection by Context:

# Use faster model for simple changes
simple_commit() {
    COCO_SERVICE_MODEL=gpt-3.5-turbo coco "$@"
}

# Use better model for complex changes
complex_commit() {
    COCO_SERVICE_MODEL=gpt-4o coco --with-previous-commits 3 "$@"
}

Integration with Development Tools

VS Code Integration

Tasks Configuration (.vscode/tasks.json):

{
    "version": "2.0.0",
    "tasks": [
        {
            "label": "Coco: Interactive Commit",
            "type": "shell",
            "command": "coco",
            "args": ["-i"],
            "group": "build",
            "presentation": {
                "echo": true,
                "reveal": "always",
                "focus": false,
                "panel": "shared"
            }
        },
        {
            "label": "Coco: Conventional Commit",
            "type": "shell", 
            "command": "coco",
            "args": ["--conventional", "-i"],
            "group": "build"
        },
        {
            "label": "Coco: Generate Changelog",
            "type": "shell",
            "command": "coco",
            "args": ["changelog"],
            "group": "build"
        }
    ]
}

Keybindings (.vscode/keybindings.json):

[
    {
        "key": "ctrl+shift+c",
        "command": "workbench.action.tasks.runTask",
        "args": "Coco: Interactive Commit"
    },
    {
        "key": "ctrl+shift+alt+c", 
        "command": "workbench.action.tasks.runTask",
        "args": "Coco: Conventional Commit"
    }
]

JetBrains IDEs Integration

External Tools Configuration:

Go to Settings > Tools > External Tools
Add new tool:
- Name: Coco Interactive Commit
- Program: coco
- Arguments: -i
- Working Directory: $ProjectFileDir$
Add keyboard shortcut in Settings > Keymap

Terminal Integration

Fish Shell Functions:

# ~/.config/fish/functions/commit.fish
function commit
    if count $argv > /dev/null
        git add . && coco -a "$argv" -i
    else
        git add . && coco -i
    end
end

# ~/.config/fish/functions/ccommit.fish  
function ccommit
    git add . && coco --conventional --append-ticket
end

Zsh with Oh My Zsh Plugin:

# ~/.oh-my-zsh/custom/plugins/coco/coco.plugin.zsh
alias cc='git add . && coco -i'
alias ccf='git add . && coco --conventional'
alias ccl='coco changelog'
alias ccr='coco recap --yesterday'

# Auto-completion
_coco_commands() {
    local commands=(
        'commit:Generate commit message'
        'changelog:Generate changelog'
        'recap:Summarize changes'
        'review:Code review'
        'init:Setup wizard'
    )
    _describe 'commands' commands
}

compdef _coco_commands coco

Advanced Git Hooks

Sophisticated Pre-commit Hook

#!/bin/sh
# .git/hooks/pre-commit

# Colors for output
RED='\033[0;31m'
GREEN='\033[0;32m'
YELLOW='\033[1;33m'
NC='\033[0m' # No Color

# Check if coco is available
if ! command -v coco >/dev/null 2>&1; then
    echo "${YELLOW}Warning: coco not found. Skipping AI commit generation.${NC}"
    exit 0
fi

# Check for staged changes
if git diff --cached --quiet; then
    echo "${RED}No staged changes found.${NC}"
    exit 1
fi

# Get branch name for context
branch=$(git branch --show-current)
ticket=$(echo "$branch" | grep -oE '[A-Z]+-[0-9]+' || echo "")

# Generate commit message based on branch type
case "$branch" in
    feature/*)
        echo "${GREEN}Generating feature commit message...${NC}"
        suggested_msg=$(coco --conventional --append-ticket -a "Feature implementation")
        ;;
    fix/*|bugfix/*)
        echo "${GREEN}Generating bugfix commit message...${NC}"
        suggested_msg=$(coco --conventional --append-ticket -a "Bug fix")
        ;;
    hotfix/*)
        echo "${GREEN}Generating hotfix commit message...${NC}"
        suggested_msg=$(coco --conventional --append-ticket -a "Critical hotfix")
        ;;
    *)
        echo "${GREEN}Generating commit message...${NC}"
        suggested_msg=$(coco --conventional)
        ;;
esac

# Display suggested message
echo "${YELLOW}Suggested commit message:${NC}"
echo "$suggested_msg"
echo

# Save to temporary file for commit-msg hook
echo "$suggested_msg" > .git/COCO_SUGGESTED_MSG

echo "${GREEN}Commit message saved. Use 'git commit' (no -m) to use suggested message.${NC}"

Smart Commit-msg Hook

#!/bin/sh
# .git/hooks/commit-msg

commit_msg_file="$1"
commit_msg=$(cat "$commit_msg_file")

# Check if using suggested message
if [ -f .git/COCO_SUGGESTED_MSG ]; then
    suggested_msg=$(cat .git/COCO_SUGGESTED_MSG)
    
    # If commit message is empty or default, use suggested
    if [ -z "$commit_msg" ] || [ "$commit_msg" = "# Please enter the commit message" ]; then
        echo "$suggested_msg" > "$commit_msg_file"
        echo "Using AI-generated commit message."
    fi
    
    # Clean up
    rm -f .git/COCO_SUGGESTED_MSG
fi

# Validate with commitlint if available
if command -v commitlint >/dev/null 2>&1; then
    if ! commitlint --edit "$commit_msg_file"; then
        echo "Commit message validation failed."
        exit 1
    fi
fi

Custom Workflows

Release Workflow

#!/bin/bash
# release-workflow.sh

set -e

# Get version from package.json or ask user
if [ -f package.json ]; then
    current_version=$(node -p "require('./package.json').version")
    echo "Current version: $current_version"
    read -p "New version: " new_version
else
    read -p "Release version: " new_version
fi

# Generate changelog since last tag
echo "Generating changelog..."
coco changelog --since-last-tag > CHANGELOG_DRAFT.md

# Show changelog
echo "Generated changelog:"
cat CHANGELOG_DRAFT.md
echo

read -p "Proceed with release? (y/n): " -n 1 -r
echo

if [[ $REPLY =~ ^[Yy]$ ]]; then
    # Update version if package.json exists
    if [ -f package.json ]; then
        npm version "$new_version" --no-git-tag-version
        git add package.json
    fi
    
    # Add changelog to existing file
    if [ -f CHANGELOG.md ]; then
        cat CHANGELOG_DRAFT.md CHANGELOG.md > CHANGELOG_NEW.md
        mv CHANGELOG_NEW.md CHANGELOG.md
    else
        mv CHANGELOG_DRAFT.md CHANGELOG.md
    fi
    
    git add CHANGELOG.md
    
    # Create release commit
    release_msg=$(coco -a "Release version $new_version")
    git commit -m "$release_msg"
    
    # Create tag
    git tag -a "v$new_version" -m "Release version $new_version"
    
    echo "Release v$new_version created successfully!"
    echo "Push with: git push origin main --tags"
else
    rm -f CHANGELOG_DRAFT.md
    echo "Release cancelled."
fi

Code Review Workflow

#!/bin/bash
# review-workflow.sh

# Get target branch (default to main)
target_branch="${1:-main}"

# Generate review for current branch vs target
echo "Generating code review for current branch vs $target_branch..."

# Get diff summary
diff_summary=$(git diff "$target_branch"...HEAD --stat)
echo "Changes summary:"
echo "$diff_summary"
echo

# Generate AI review
review_output=$(coco review -b "$target_branch")

# Save review to file
review_file="code-review-$(date +%Y%m%d-%H%M%S).md"
cat > "$review_file" << EOF
# Code Review - $(git branch --show-current)

**Target Branch:** $target_branch
**Review Date:** $(date)
**Reviewer:** AI Assistant (coco)

## Changes Summary
\`\`\`
$diff_summary
\`\`\`

## AI Review
$review_output

## Manual Review Checklist
- [ ] Code follows project conventions
- [ ] Tests are included and passing
- [ ] Documentation is updated
- [ ] No security vulnerabilities
- [ ] Performance impact considered
- [ ] Breaking changes documented
EOF

echo "Review saved to: $review_file"

# Open in default editor if available
if command -v code >/dev/null 2>&1; then
    code "$review_file"
elif command -v vim >/dev/null 2>&1; then
    vim "$review_file"
fi

Monitoring & Analytics

Usage Tracking Script

#!/bin/bash
# coco-analytics.sh

# Configuration
LOG_FILE="$HOME/.coco/usage.log"
REPORT_FILE="$HOME/.coco/monthly-report.txt"

# Ensure log directory exists
mkdir -p "$(dirname "$LOG_FILE")"

# Log usage (call this from git hooks or aliases)
log_usage() {
    local command="$1"
    local timestamp=$(date '+%Y-%m-%d %H:%M:%S')
    local project=$(basename "$(git rev-parse --show-toplevel 2>/dev/null || pwd)")
    
    echo "$timestamp,$project,$command" >> "$LOG_FILE"
}

# Generate usage report
generate_report() {
    local month="${1:-$(date '+%Y-%m')}"
    
    echo "Coco Usage Report - $month" > "$REPORT_FILE"
    echo "=================================" >> "$REPORT_FILE"
    echo >> "$REPORT_FILE"
    
    # Total usage
    total_usage=$(grep "^$month" "$LOG_FILE" | wc -l)
    echo "Total coco commands: $total_usage" >> "$REPORT_FILE"
    echo >> "$REPORT_FILE"
    
    # Usage by project
    echo "Usage by project:" >> "$REPORT_FILE"
    grep "^$month" "$LOG_FILE" | cut -d',' -f2 | sort | uniq -c | sort -nr >> "$REPORT_FILE"
    echo >> "$REPORT_FILE"
    
    # Usage by command
    echo "Usage by command:" >> "$REPORT_FILE"
    grep "^$month" "$LOG_FILE" | cut -d',' -f3 | sort | uniq -c | sort -nr >> "$REPORT_FILE"
    
    echo "Report saved to: $REPORT_FILE"
}

# Usage
case "$1" in
    log)
        log_usage "$2"
        ;;
    report)
        generate_report "$2"
        ;;
    *)
        echo "Usage: $0 {log|report} [args]"
        echo "  log <command>     - Log usage of command"
        echo "  report [month]    - Generate usage report"
        ;;
esac

This advanced usage guide provides power users with the tools and techniques needed to fully customize and optimize their coco workflow for any development environment or team structure.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Advanced Usage

Custom Prompts & Templates

Understanding Prompt Variables

Custom Commit Prompts

Custom Summarize Prompts

Multi-Project Configuration

Workspace-Level Configuration

Environment-Specific Configurations

Automation & Scripting

Git Aliases

Shell Functions

Advanced Scripting

Performance Optimization

Token Usage Optimization

Caching Strategies

Integration with Development Tools

VS Code Integration

JetBrains IDEs Integration

Terminal Integration

Advanced Git Hooks

Sophisticated Pre-commit Hook

Smart Commit-msg Hook

Custom Workflows

Release Workflow

Code Review Workflow

Monitoring & Analytics

Usage Tracking Script

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Clone this wiki locally