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:
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:
{
"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:
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.jsonRoot Configuration:
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:
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:
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:
export COCO_MODE=interactive
export COCO_VERBOSE=true
export COCO_SERVICE_TEMPERATURE=0.4 # More creativeProduction/CI Environment:
1export COCO_MODE=stdout
2export COCO_VERBOSE=false
3export COCO_SERVICE_TEMPERATURE=0.2 # More deterministic
4export COCO_SERVICE_TOKEN_LIMIT=1024 # Cost controlTeam Lead Configuration:
export COCO_WITH_PREVIOUS_COMMITS=5 # More context
export COCO_SERVICE_MODEL=gpt-4o # Best qualityAutomation & Scripting
Git Aliases
Add to your .gitconfig:
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:
1git cc # Interactive commit
2git ccf # Fast conventional commit
3git ccc "Fixes login timeout" # Commit with context
4git cl # Generate changelog
5git recap # Weekly summaryShell Functions
Add to your .bashrc or .zshrc:
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:
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."
32fiSmart Branch Workflow:
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 ;;
20esacPerformance Optimization
Token Usage Optimization
Reduce Token Consumption:
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:
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:
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=trueModel Selection by Context:
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):
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):
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:
-
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:
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
13endZsh with Oh My Zsh Plugin:
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 cocoAdvanced Git Hooks
Sophisticated Pre-commit Hook
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
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
27fiCustom Workflows
Release Workflow
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."
56fiCode Review Workflow
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"
52fiMonitoring & Analytics
Usage Tracking Script
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 ;;
58esacThis 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.