craigs-buddy

Git-based workflow manager that brings structure and version control to AI-powered coding.

Documentation

• Documentation - Complete guide to using craigs-buddy
• Glossary - Key concepts and terminology
• Coding Style - Code standards and best practices for contributors

Installation

npm install -g craigs-buddy

Shell Integration (Recommended)

# Add to your .zshrc or .bashrc:
eval "$(craigs-buddy shell-init)"

This provides convenient wrapper commands:

• cb-checkout - Clone repository and cd to project/main
• cb-change - Create AI change and cd to worktree (requires changeType and description)
• cb-apply - Apply changes (stays in current worktree)
• cb-merge - Merge changes and return to main
• cb-abandon - Abandon changes and return to main

Tip: Set the EDITOR environment variable to automatically open the prompt.yaml file after creating a change:

export EDITOR=code  # or vim, nano, emacs, etc.

Optional 3-Letter Shortcuts

If you want shorter aliases, use the --with-shortcuts flag:

eval "$(craigs-buddy shell-init --with-shortcuts)"

This adds: cbc (change), cba (apply), cbm (merge), cbd (abandon)

Note: cb-checkout doesn't have a 3-letter shortcut as it's less frequently used.

Custom Templates

When you run craigs-buddy checkout, it automatically creates a .craigs-buddy/templates directory in your project root with copies of the default templates. You can customize these templates to fit your project's needs:

• prompt.hbs - Main prompt template for AI tasks
• generate-metadata.hbs - Template for generating task metadata
• generate-commit-message.hbs - Template for generating commit messages

The tool will automatically use your custom templates from the .craigs-buddy/templates directory. You can also place templates in parent directories - craigs-buddy will search up the directory tree to find the nearest .craigs-buddy/templates folder.

Development

npm run dev       # Run in development mode with tsx
npm run build     # Build TypeScript
npm run test      # Run tests
npm run lint      # Run ESLint
npm run typecheck # Type check without building

Usage

craigs-buddy checkout <repo-url>
craigs-buddy change <changeType> "description of change"
craigs-buddy apply
craigs-buddy merge
craigs-buddy abandon