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:

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

Custom Commit Prompts

Basic Custom Prompt:

json
{
  "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:

json
{
  "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:

json
{
  "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:

json
{
  "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:

json
{
  "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:

bash
1# Root workspace config
2.coco.config.json              # Default for all projects
3
4# Project-specific overrides  
5packages/frontend/.coco.config.json
6packages/backend/.coco.config.json
7packages/mobile/.coco.config.json

Root Configuration:

json
1{
2  "mode": "interactive",
3  "conventionalCommits": true,
4  "includeBranchName": true,
5  "service": {
6    "provider": "openai",
7    "model": "gpt-4o",
8    "temperature": 0.3
9  },
10  "ignoredFiles": [
11    "node_modules/**",
12    "dist/**",
13    "build/**"
14  ]
15}

Frontend Override:

json
1{
2  "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}}",
3  "ignoredFiles": [
4    "public/build/**",
5    "src/**/*.css.map",
6    "coverage/**"
7  ]
8}

Backend Override:

json
1{
2  "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}}",
3  "ignoredFiles": [
4    "logs/**",
5    "uploads/**",
6    "*.log"
7  ]
8}

Environment-Specific Configurations

Development Environment:

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

Production/CI Environment:

bash
1export COCO_MODE=stdout
2export COCO_VERBOSE=false
3export COCO_SERVICE_TEMPERATURE=0.2  # More deterministic
4export COCO_SERVICE_TOKEN_LIMIT=1024  # Cost control

Team Lead Configuration:

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

Automation & Scripting

Git Aliases

Add to your .gitconfig:

ini
1[alias]
2    # Smart commit with coco
3    cc = "!f() { git add . && coco -i; }; f"
4    
5    # Quick conventional commit
6    ccf = "!f() { git add . && coco --conventional; }; f"
7    
8    # Commit with context
9    ccc = "!f() { git add . && coco -a \"$1\" -i; }; f"
10    
11    # Generate changelog
12    cl = "!coco changelog"
13    
14    # Weekly recap
15    recap = "!coco recap --last-week"

Usage:

bash
1git cc                           # Interactive commit
2git ccf                          # Fast conventional commit
3git ccc "Fixes login timeout"    # Commit with context
4git cl                           # Generate changelog
5git recap                        # Weekly summary

Shell Functions

Add to your .bashrc or .zshrc:

bash
1# Smart commit function
2commit() {
3    if [ $# -eq 0 ]; then
4        # No arguments - interactive mode
5        git add . && coco -i
6    else
7        # With message - add context
8        git add . && coco -a "$*" -i
9    fi
10}
11
12# Quick conventional commit
13ccommit() {
14    git add . && coco --conventional --append-ticket
15}
16
17# Commit specific files with context
18commitf() {
19    local files="$1"
20    shift
21    git add "$files" && coco -a "$*" -i
22}
23
24# Generate and show changelog
25changelog() {
26    local range="${1:-HEAD~10:HEAD}"
27    coco changelog -r "$range" | less
28}

Advanced Scripting

Batch Commit Processing:

bash
1#!/bin/bash
2# batch-commit.sh - Process multiple staged changes
3
4# Check for staged changes
5if ! git diff --cached --quiet; then
6    echo "Processing staged changes..."
7    
8    # Generate commit with context
9    if [ -n "$1" ]; then
10        commit_msg=$(coco -a "$1")
11    else
12        commit_msg=$(coco commit)
13    fi
14    
15    # Show generated message
16    echo "Generated commit message:"
17    echo "$commit_msg"
18    echo
19    
20    # Confirm before committing
21    read -p "Commit with this message? (y/n): " -n 1 -r
22    echo
23    
24    if [[ $REPLY =~ ^[Yy]$ ]]; then
25        git commit -m "$commit_msg"
26        echo "Committed successfully!"
27    else
28        echo "Commit cancelled."
29    fi
30else
31    echo "No staged changes found."
32fi

Smart Branch Workflow:

bash
1#!/bin/bash
2# smart-workflow.sh - Intelligent branch-based commits
3
4branch=$(git branch --show-current)
5ticket=$(echo "$branch" | grep -oE '[A-Z]+-[0-9]+')
6
7case "$branch" in
8    feature/*)
9        coco commit --conventional --append-ticket -a "Feature implementation"
10        ;;
11    fix/*)
12        coco commit --conventional --append-ticket -a "Bug fix"
13        ;;
14    hotfix/*)
15        coco commit --conventional --append-ticket -a "Critical hotfix"
16        ;;
17    *)
18        coco commit --conventional
19        ;;
20esac

Performance Optimization

Token Usage Optimization

Reduce Token Consumption:

json
1{
2  "service": {
3    "tokenLimit": 1024,        // Reduce from default 2048
4    "temperature": 0.2         // More deterministic, less tokens
5  },
6  "ignoredFiles": [
7    "**/*.{map,min.js,min.css}",  // Ignore generated files
8    "node_modules/**",
9    "dist/**",
10    "coverage/**"
11  ],
12  "ignoredExtensions": [
13    ".log", ".tmp", ".cache", ".lock"
14  ]
15}

Smart File Filtering:

json
1{
2  "ignoredFiles": [
3    // Large generated files
4    "package-lock.json",
5    "yarn.lock", 
6    "pnpm-lock.yaml",
7    
8    // Build outputs
9    "dist/**",
10    "build/**", 
11    ".next/**",
12    
13    // Test outputs
14    "coverage/**",
15    "test-results/**",
16    
17    // Logs and temps
18    "*.log",
19    "tmp/**",
20    ".cache/**"
21  ]
22}

Caching Strategies

Environment-Based Caching:

bash
1# Cache API responses for development
2export COCO_CACHE_DIR="$HOME/.coco/cache"
3export COCO_CACHE_TTL=3600  # 1 hour cache
4
5# Disable caching in CI
6export COCO_CACHE_DISABLED=true

Model Selection by Context:

bash
1# Use faster model for simple changes
2simple_commit() {
3    COCO_SERVICE_MODEL=gpt-3.5-turbo coco "$@"
4}
5
6# Use better model for complex changes
7complex_commit() {
8    COCO_SERVICE_MODEL=gpt-4o coco --with-previous-commits 3 "$@"
9}

Integration with Development Tools

VS Code Integration

Tasks Configuration (.vscode/tasks.json):

json
1{
2    "version": "2.0.0",
3    "tasks": [
4        {
5            "label": "Coco: Interactive Commit",
6            "type": "shell",
7            "command": "coco",
8            "args": ["-i"],
9            "group": "build",
10            "presentation": {
11                "echo": true,
12                "reveal": "always",
13                "focus": false,
14                "panel": "shared"
15            }
16        },
17        {
18            "label": "Coco: Conventional Commit",
19            "type": "shell", 
20            "command": "coco",
21            "args": ["--conventional", "-i"],
22            "group": "build"
23        },
24        {
25            "label": "Coco: Generate Changelog",
26            "type": "shell",
27            "command": "coco",
28            "args": ["changelog"],
29            "group": "build"
30        }
31    ]
32}

Keybindings (.vscode/keybindings.json):

json
1[
2    {
3        "key": "ctrl+shift+c",
4        "command": "workbench.action.tasks.runTask",
5        "args": "Coco: Interactive Commit"
6    },
7    {
8        "key": "ctrl+shift+alt+c", 
9        "command": "workbench.action.tasks.runTask",
10        "args": "Coco: Conventional Commit"
11    }
12]

JetBrains IDEs Integration

External Tools Configuration:

  1. Go to Settings > Tools > External Tools

  2. Add new tool:

    • Name: Coco Interactive Commit
    • Program: coco
    • Arguments: -i
    • Working Directory: $ProjectFileDir$
  3. Add keyboard shortcut in Settings > Keymap

Terminal Integration

Fish Shell Functions:

fish
1# ~/.config/fish/functions/commit.fish
2function commit
3    if count $argv > /dev/null
4        git add . && coco -a "$argv" -i
5    else
6        git add . && coco -i
7    end
8end
9
10# ~/.config/fish/functions/ccommit.fish  
11function ccommit
12    git add . && coco --conventional --append-ticket
13end

Zsh with Oh My Zsh Plugin:

bash
1# ~/.oh-my-zsh/custom/plugins/coco/coco.plugin.zsh
2alias cc='git add . && coco -i'
3alias ccf='git add . && coco --conventional'
4alias ccl='coco changelog'
5alias ccr='coco recap --yesterday'
6
7# Auto-completion
8_coco_commands() {
9    local commands=(
10        'commit:Generate commit message'
11        'changelog:Generate changelog'
12        'recap:Summarize changes'
13        'review:Code review'
14        'init:Setup wizard'
15    )
16    _describe 'commands' commands
17}
18
19compdef _coco_commands coco

Advanced Git Hooks

Sophisticated Pre-commit Hook

bash
1#!/bin/sh
2# .git/hooks/pre-commit
3
4# Colors for output
5RED='\033[0;31m'
6GREEN='\033[0;32m'
7YELLOW='\033[1;33m'
8NC='\033[0m' # No Color
9
10# Check if coco is available
11if ! command -v coco >/dev/null 2>&1; then
12    echo "${YELLOW}Warning: coco not found. Skipping AI commit generation.${NC}"
13    exit 0
14fi
15
16# Check for staged changes
17if git diff --cached --quiet; then
18    echo "${RED}No staged changes found.${NC}"
19    exit 1
20fi
21
22# Get branch name for context
23branch=$(git branch --show-current)
24ticket=$(echo "$branch" | grep -oE '[A-Z]+-[0-9]+' || echo "")
25
26# Generate commit message based on branch type
27case "$branch" in
28    feature/*)
29        echo "${GREEN}Generating feature commit message...${NC}"
30        suggested_msg=$(coco --conventional --append-ticket -a "Feature implementation")
31        ;;
32    fix/*|bugfix/*)
33        echo "${GREEN}Generating bugfix commit message...${NC}"
34        suggested_msg=$(coco --conventional --append-ticket -a "Bug fix")
35        ;;
36    hotfix/*)
37        echo "${GREEN}Generating hotfix commit message...${NC}"
38        suggested_msg=$(coco --conventional --append-ticket -a "Critical hotfix")
39        ;;
40    *)
41        echo "${GREEN}Generating commit message...${NC}"
42        suggested_msg=$(coco --conventional)
43        ;;
44esac
45
46# Display suggested message
47echo "${YELLOW}Suggested commit message:${NC}"
48echo "$suggested_msg"
49echo
50
51# Save to temporary file for commit-msg hook
52echo "$suggested_msg" > .git/COCO_SUGGESTED_MSG
53
54echo "${GREEN}Commit message saved. Use 'git commit' (no -m) to use suggested message.${NC}"

Smart Commit-msg Hook

bash
1#!/bin/sh
2# .git/hooks/commit-msg
3
4commit_msg_file="$1"
5commit_msg=$(cat "$commit_msg_file")
6
7# Check if using suggested message
8if [ -f .git/COCO_SUGGESTED_MSG ]; then
9    suggested_msg=$(cat .git/COCO_SUGGESTED_MSG)
10    
11    # If commit message is empty or default, use suggested
12    if [ -z "$commit_msg" ] || [ "$commit_msg" = "# Please enter the commit message" ]; then
13        echo "$suggested_msg" > "$commit_msg_file"
14        echo "Using AI-generated commit message."
15    fi
16    
17    # Clean up
18    rm -f .git/COCO_SUGGESTED_MSG
19fi
20
21# Validate with commitlint if available
22if command -v commitlint >/dev/null 2>&1; then
23    if ! commitlint --edit "$commit_msg_file"; then
24        echo "Commit message validation failed."
25        exit 1
26    fi
27fi

Custom Workflows

Release Workflow

bash
1#!/bin/bash
2# release-workflow.sh
3
4set -e
5
6# Get version from package.json or ask user
7if [ -f package.json ]; then
8    current_version=$(node -p "require('./package.json').version")
9    echo "Current version: $current_version"
10    read -p "New version: " new_version
11else
12    read -p "Release version: " new_version
13fi
14
15# Generate changelog since last tag
16echo "Generating changelog..."
17coco changelog --since-last-tag > CHANGELOG_DRAFT.md
18
19# Show changelog
20echo "Generated changelog:"
21cat CHANGELOG_DRAFT.md
22echo
23
24read -p "Proceed with release? (y/n): " -n 1 -r
25echo
26
27if [[ $REPLY =~ ^[Yy]$ ]]; then
28    # Update version if package.json exists
29    if [ -f package.json ]; then
30        npm version "$new_version" --no-git-tag-version
31        git add package.json
32    fi
33    
34    # Add changelog to existing file
35    if [ -f CHANGELOG.md ]; then
36        cat CHANGELOG_DRAFT.md CHANGELOG.md > CHANGELOG_NEW.md
37        mv CHANGELOG_NEW.md CHANGELOG.md
38    else
39        mv CHANGELOG_DRAFT.md CHANGELOG.md
40    fi
41    
42    git add CHANGELOG.md
43    
44    # Create release commit
45    release_msg=$(coco -a "Release version $new_version")
46    git commit -m "$release_msg"
47    
48    # Create tag
49    git tag -a "v$new_version" -m "Release version $new_version"
50    
51    echo "Release v$new_version created successfully!"
52    echo "Push with: git push origin main --tags"
53else
54    rm -f CHANGELOG_DRAFT.md
55    echo "Release cancelled."
56fi

Code Review Workflow

bash
1#!/bin/bash
2# review-workflow.sh
3
4# Get target branch (default to main)
5target_branch="${1:-main}"
6
7# Generate review for current branch vs target
8echo "Generating code review for current branch vs $target_branch..."
9
10# Get diff summary
11diff_summary=$(git diff "$target_branch"...HEAD --stat)
12echo "Changes summary:"
13echo "$diff_summary"
14echo
15
16# Generate AI review
17review_output=$(coco review -b "$target_branch")
18
19# Save review to file
20review_file="code-review-$(date +%Y%m%d-%H%M%S).md"
21cat > "$review_file" << EOF
22# Code Review - $(git branch --show-current)
23
24**Target Branch:** $target_branch
25**Review Date:** $(date)
26**Reviewer:** AI Assistant (coco)
27
28## Changes Summary
29\`\`\`
30$diff_summary
31\`\`\`
32
33## AI Review
34$review_output
35
36## Manual Review Checklist
37- [ ] Code follows project conventions
38- [ ] Tests are included and passing
39- [ ] Documentation is updated
40- [ ] No security vulnerabilities
41- [ ] Performance impact considered
42- [ ] Breaking changes documented
43EOF
44
45echo "Review saved to: $review_file"
46
47# Open in default editor if available
48if command -v code >/dev/null 2>&1; then
49    code "$review_file"
50elif command -v vim >/dev/null 2>&1; then
51    vim "$review_file"
52fi

Monitoring & Analytics

Usage Tracking Script

bash
1#!/bin/bash
2# coco-analytics.sh
3
4# Configuration
5LOG_FILE="$HOME/.coco/usage.log"
6REPORT_FILE="$HOME/.coco/monthly-report.txt"
7
8# Ensure log directory exists
9mkdir -p "$(dirname "$LOG_FILE")"
10
11# Log usage (call this from git hooks or aliases)
12log_usage() {
13    local command="$1"
14    local timestamp=$(date '+%Y-%m-%d %H:%M:%S')
15    local project=$(basename "$(git rev-parse --show-toplevel 2>/dev/null || pwd)")
16    
17    echo "$timestamp,$project,$command" >> "$LOG_FILE"
18}
19
20# Generate usage report
21generate_report() {
22    local month="${1:-$(date '+%Y-%m')}"
23    
24    echo "Coco Usage Report - $month" > "$REPORT_FILE"
25    echo "=================================" >> "$REPORT_FILE"
26    echo >> "$REPORT_FILE"
27    
28    # Total usage
29    total_usage=$(grep "^$month" "$LOG_FILE" | wc -l)
30    echo "Total coco commands: $total_usage" >> "$REPORT_FILE"
31    echo >> "$REPORT_FILE"
32    
33    # Usage by project
34    echo "Usage by project:" >> "$REPORT_FILE"
35    grep "^$month" "$LOG_FILE" | cut -d',' -f2 | sort | uniq -c | sort -nr >> "$REPORT_FILE"
36    echo >> "$REPORT_FILE"
37    
38    # Usage by command
39    echo "Usage by command:" >> "$REPORT_FILE"
40    grep "^$month" "$LOG_FILE" | cut -d',' -f3 | sort | uniq -c | sort -nr >> "$REPORT_FILE"
41    
42    echo "Report saved to: $REPORT_FILE"
43}
44
45# Usage
46case "$1" in
47    log)
48        log_usage "$2"
49        ;;
50    report)
51        generate_report "$2"
52        ;;
53    *)
54        echo "Usage: $0 {log|report} [args]"
55        echo "  log <command>     - Log usage of command"
56        echo "  report [month]    - Generate usage report"
57        ;;
58esac

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.