Skip to content

Home

Jump to bottom
Griffen Fargo edited this page Jun 10, 2026 · 22 revisions

🚀 Quick Start

New to coco? Start here for a complete walkthrough from installation to your first AI-generated commit.

📖 Getting Started Guide

  • Installation methods (npm, npx, global vs local)
  • First-time setup with AI provider selection
  • Your first commit walkthrough
  • Essential commands and workflows
  • Quick troubleshooting for beginners

⚙️ Configuration & Setup

Core Configuration

🔧 Configuration Overview

  • Complete configuration reference with all options
  • Multiple configuration methods (CLI, env vars, config files)
  • AI provider setup — seven providers (OpenAI, Anthropic, Ollama, Gemini, Mistral, Azure OpenAI, AWS Bedrock)
  • Priority system and best practices

📁 Ignoring Files & Extensions

  • Advanced pattern matching with minimatch
  • Project-specific ignore configurations
  • Performance optimization through file filtering
  • Real-world examples for different project types

AI Providers

🏠 Using Ollama

  • Complete local AI setup guide
  • Model recommendations by hardware
  • Performance optimization and GPU acceleration
  • Privacy-focused development workflows

👥 Team & Enterprise

🤝 Team Collaboration

  • Shared configuration strategies
  • Git hooks and CI/CD integration
  • Security best practices for API keys
  • Team onboarding and training materials
  • Enterprise-scale deployment

🔧 Advanced Features

⚡ Advanced Usage

  • Custom prompts and templates
  • Multi-project configurations
  • Automation and scripting
  • Performance optimization techniques
  • Integration with development tools

🖥️ Coco UI

  • Use coco ui as a GitKraken-style terminal Git workstation
  • Sixteen top-level views (history, status, diff, compose, branches, tags, stash, worktrees, pull-request, pull-request-triage, issues, conflicts, reflog, bisect, submodules, changelog) with chord-driven navigation
  • Stage files/hunks, compose commits, request explicit AI drafts after confirmation
  • One-keystroke workflows: S split staged changes, L generate a changelog, C create a PR seeded from changelog, E open the commit draft in $EDITOR
  • Just-landed commits get a ▎ marker for ~5s after apply so you can see what an operation just created
  • Keep coco log -i as a supported alias into history mode

🗂️ Coco Workspace

  • coco workspace (alias coco ws) — multi-repo overview TUI for the day's wide context across 3–10 active repos
  • Discovers every git working tree under workspace.roots; per-row branch / dirty / ahead-behind / last-commit / open-PR data
  • Tab-filtered (All / Dirty / Behind / PRs), sortable by recency / name / dirtiness, free-text filter on top
  • enter drills into the cursored repo as a full coco ui session; quitting ui returns to the workspace with the cursor anchored back on the same repo
  • a adds a repo by path with fuzzy tab-completion; R refreshes just the cursored row (vs r for the whole workspace)
  • Per-row spinners while gh pr list is in flight; rail-collapses the sidebar on narrow terminals

🐙 Issue & PR Triage

  • coco issues and coco prs print formatted lists to stdout — composable with grep, jq, and other pipeline tools
  • g i and g P open list-on-left / inspector-on-right triage surfaces inside coco ui
  • Per-row action keys: comment, label, assign, merge, approve, request changes, close, reopen — all destructive verbs gated through y-confirm
  • Canned filter presets cycle with f: open / closed / mine / assigned / draft / merged
  • Debounced per-cursor-rest hydration brings in body, comments, reviews, and status checks without spamming the forge CLI
  • Works across GitHub, GitHub Enterprise, and GitLab — see Multi-Forge Support

🌐 Multi-Forge Support

  • coco prs, coco issues, coco pr create, and the full coco ui triage workstation run against GitHub, GitHub Enterprise, and GitLab
  • Forge auto-detected from the git remote host; self-hosted vanity hosts mapped via the forgeHosts config key
  • Drives gh for GitHub / GitHub Enterprise and glab for GitLab — same flags, same keybindings regardless of forge
  • On GitLab, PR commands operate on merge requests; covers GitLab-specific behavior (request-changes-as-note, squash/rebase merges, push-on-create)

🧭 TUI Navigation

  • Source of truth for the chord set (g h/s/d/c/b/t/z), the navigation stack, and back (< / Esc)
  • Interactive command palette (:) with fuzzy filter and recently-used at the top
  • / global search across history, branches, tags, and stash; help overlay grouped by scope
  • 108 built-in color themes / 109 presets (29 light) with readable selected rows on every theme, NO_COLOR support, accessibility expectations

📜 Interactive Log TUI

  • History-focused guide for coco log -i and coco ui --view history
  • Search with fuzzy-ranked filtering and common lazygit/fzf keybindings
  • Inspect selected commit metadata, changed files, stats, and hunk previews

🧩 Commit Split

  • Plan smaller related commits from broad staged changes
  • Apply file-level and hunk-level split commit groups
  • Inherits your conventional-commits + commitlint + branch-name config — same standards as coco commit
  • Available as a one-keystroke (S) workflow from inside coco ui with animated overlay, per-commit HEAD verification, and a four-pass rescue chain that recovers from common LLM output drift
  • Understand safety checks and fail-closed behavior

🧠 Dynamic Model Routing

  • Use service.model: "dynamic" with provider-specific model profiles
  • Route summarize, commit, changelog, review, recap, repair, and large-diff tasks
  • Customize model choices per task

📝 Documentation Workflow

  • Maintain the wiki locally from .wiki/
  • Keep the wiki as the canonical documentation source
  • Use repository docs only as temporary planning or migration material

🧪 Testing Scenarios

  • 27 named git states (merge / rebase / cherry-pick / revert conflicts, diverged branches, mid-bisect, multi-remote forks, shallow clones, multiple worktrees, …) for manual TUI testing and integration tests
  • npm run scenario create <name> -- --run-ui is the tightest dev loop for trying workstation changes against tricky shapes
  • Drop in describeWithScenario('feature-pr-ready', (getRepo) => …) from the Jest framework adapter for zero-boilerplate fixtures
  • Built on the published @gfargo/git-scenarios package

📚 Reference

📋 Command Reference

  • Complete reference for all commands and flags
  • Includes commit, commit split, amend, pr create, changelog, recap, review, log, ui, issues, prs, and init
  • Common workflows and output mode examples

🌐 Using OpenRouter

  • Access multiple AI providers through a single API
  • Configuration examples for project, git, and environment setups
  • Model switching and cost tracking

🆘 Help & Support

🔍 Troubleshooting Guide

  • Common issues and solutions
  • Diagnostic commands and debugging
  • Platform-specific problems (Windows, macOS, Linux)
  • API and connectivity issues
  • Performance troubleshooting

🎯 Use Cases

Individual Developers

  • Consistent Commits: Never write generic commit messages again
  • Learning Tool: Understand conventional commits through examples
  • Time Saving: Generate contextual messages in seconds
  • Offline Capable: Use Ollama for complete privacy and offline work

Development Teams

  • Standardization: Enforce consistent commit message formats
  • Onboarding: Help new team members learn project conventions
  • Code Review: Better commit messages improve review efficiency
  • Release Management: Conventional commits enable automated changelogs

Enterprise Organizations

  • Compliance: Audit trails and consistent documentation
  • Security: Local AI models keep code completely private
  • Cost Control: Shared Ollama servers eliminate per-request costs
  • Integration: Seamless integration with existing development workflows

🔗 Quick Links

Essential Commands

# Interactive commit (recommended)
coco commit -i

# Conventional commits format
coco commit --conventional

# Add context for complex changes
coco commit -a "Resolves login timeout issue"

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

# Generate changelog
coco changelog

# Open the Git workstation
coco ui

# Browse history interactively through the legacy entrypoint
coco log -i

# Summarize recent work
coco recap --yesterday

Configuration Examples

# Quick setup
coco init

# Project-specific setup
coco init --scope project

# Global user setup
coco init --scope global

Common Workflows

# Daily development
git add .
coco commit -i

# Team workflow with validation
git add .
coco commit --conventional -i

# Release workflow
coco changelog --since-last-tag

📖 Additional Resources

Community & Support

Development

🎉 Get Started Today

Ready to transform your git workflow? Choose your path:

This documentation is continuously updated. For the latest information, visit the GitHub repository or join our Discord community.

Clone this wiki locally