aico

An intelligent AI-powered CLI tool that generates high-signal git commit messages and branch names using OpenAI models. Built with TypeScript and designed for developer productivity.

🎯 Overview

AICO (AI Commits) analyzes your git changes and generates conventional commit messages that follow best practices. It uses structured git context (name-status, numstat, and limited snippets) and enforces a subject-first format where the body is optional and typically omitted unless needed.

✨ Key Features

🤖 AI-Powered Generation: Uses OpenAI models with structured git context
📝 Conventional Commits: Follows Conventional Commits specification
🔄 Interactive Workflow: Preview, edit, regenerate, or accept generated messages
🌳 Smart Context: Uses branch hints and structured diff signals for consistent subjects
🌿 Branch Name Generation: Creates semantic branch names from descriptions
🧾 PR Title + Description: Generates PR copy from branch diffs
⚡ Performance Optimized: Uses GPT-4o-mini by default for speed and cost efficiency
🛡️ Secure Configuration: Safe API key storage in user config directory
🎨 Rich CLI Experience: Colorful interface with figlet banners and progress indicators

🏗️ Architecture

The project follows a layered architecture with clear separation of concerns:

Core Services

Config.service.ts - Configuration management and API key storage
Git.service.ts - Git operations and diff collection
OpenAI.service.ts - OpenAI API client and model interaction
UI.service.ts - User prompts and interactive workflows
Logger.service.ts - Structured logging infrastructure

Orchestration Layer

Workflow.service.ts - High-level application flow coordination
CommitGenerator.service.ts - Commit generation pipeline
DiffOrchestrator.service.ts - Diff processing and optimization

Analysis Layer

CommitHeuristics.ts - Commit type and scope classification
ScopeInferrer.ts - Intelligent scope inference from file paths
Diff.processor.ts - Diff filtering, chunking, and signal extraction

Validation Layer

CommitValidator.ts - Conventional Commits format validation
SubjectRepairer.ts - Subject repair and fallback templates

Prompt & Context

PromptBuilder.ts - Prompt construction and context formatting
openai.constants.ts - System prompts and patterns
patterns.ts - Regex patterns for parsing

Entry Point

cli.ts - CLI argument parsing and program initialization

🚀 Quick Start

Prerequisites

Node.js 16+
npm 7+
Git
OpenAI API key (Get one here)

Installation

Clone and build:

git clone https://github.com/EthanDM/aico.git
cd aico
npm install
npm run build

Make globally available:
```
chmod +x dist/cli.js
npm link
```
Set up your API key (one-time setup):
```
aico --set-api-key YOUR_OPENAI_API_KEY
```

Basic Usage

# Stage your changes
git add .

# Generate and apply commit message
aico

# Generate with interactive context prompt
aico -c

# Generate with inline context
aico -c "fix authentication bug with JWT validation"

# Generate with positional context (no flags needed)
aico "optimize database queries for better performance"

# Generate branch name with context
aico -b -c "add user profile feature"

# Generate PR title + description (uses branch diff)
aico -p -c "add cache invalidation for profile pages"

Context Usage Patterns

AICO supports three ways to provide context for better commit message generation:

1. Interactive Context (Traditional)

aico -c
# Prompts: "Add context to help guide the AI:"
# Best for: When you want to see the diff first, then decide what context to add

2. Inline Context (Fast)

aico -c "fix memory leak in event handlers"
aico --context "refactor authentication to use OAuth2"
# Best for: When you know exactly what context you want to provide upfront

3. Positional Context (Fastest)

# With quotes (recommended for complex context)
aico "implement user preferences dashboard"
aico "resolve merge conflicts in user service"

# Without quotes (works great for simple context)
aico fix authentication bug
aico optimize database queries
aico add new feature

# Best for: Ultimate speed - no flags needed when you have context

Context Tips:

Quotes are optional! Use them when your context contains special characters or you want to be explicit
Keep context concise but descriptive (under 100 characters works best)
Focus on the "why" rather than the "what" (the diff shows the "what")
Examples: "fix production bug", "improve performance", "add new feature"

🛠️ Configuration

Command Line Options

aico [options] [context]

Options:
  -d, --debug              Enable debug logging with detailed output
  -f, --full               Use GPT-4o model instead of default GPT-4o-mini
  -c, --context [context]  Provide context for AI guidance (interactive if no value given)
  --no-auto-stage          Disable automatic staging of changes
  --merge                  Generate merge commit message
  --set-default-model      Set default model (gpt-4o | gpt-4o-mini)
  --set-api-key            Save OpenAI API key to config
  -b, --branch             Generate branch name instead of commit message
  -p, --pull-request       Generate PR title and description from branch diff
  -h, --help              Display help information
  -v, --version           Show version number

Arguments:
  context                  Context to guide AI generation (alternative to -c flag)

Configuration File

AICO stores configuration in ~/.config/aico/config.json:

{
  "openai": {
    "model": "gpt-4o-mini", // Model selection
    "maxTokens": 200, // Response length limit
    "temperature": 0.3, // Creativity level (0-1)
    "topP": 0.9, // Response diversity
    "frequencyPenalty": 0, // Repetition penalty
    "presencePenalty": 0 // Topic novelty penalty
  },
  "commit": {
    "maxTitleLength": 72, // Commit title character limit
    "maxBodyLength": 200, // Commit body character limit
    "wrapBody": 72, // Body text wrapping column
    "includeBody": "auto", // "auto" | "never" | "always"
    "includeFooter": false, // Footer handling is not emphasized
    "scopeRules": [], // Optional { scope, match } regex rules
    "enableBehaviorTemplates": false // Enable minimal generic fallback templates
  },
  "debug": {
    "enabled": false, // Debug mode toggle
    "logLevel": "INFO" // Logging verbosity level
  }
}

Scope rules are optional regex mappings for stable scope inference. If empty or invalid, AICO falls back to generic scope rules. Behavior templates are minimal fallback templates applied only when a generated subject is invalid or overly vague.

Model Selection Strategy

GPT-4o-mini (default): Faster, cost-effective, ideal for most commits
GPT-4o (via -f flag): Higher quality for complex changes
Auto-prompting: Large diffs (>30K chars) may trigger a model selection prompt

Environment Variables

OPENAI_KEY: Alternative to saved configuration (optional)

🔄 Interactive Workflow

Analysis Phase:
- Detects unstaged changes and prompts for staging
- Builds structured git signals (name-status, numstat, snippets)
- Considers branch context and optional user guidance
Generation Phase:
- Processes diff through intelligent filtering
- Sends optimized context to OpenAI API
- Attempts deterministic local repairs before retrying the model
- Generates conventional commit message
Review Phase:
- Displays generated message with syntax highlighting
- Offers actions: Accept, Edit, Regenerate, or Cancel
- Handles user modifications and re-generation
Commit Phase:
- Executes git commit with final message
- Provides confirmation and next steps

📝 Generated Commit Format

AICO generates commits following the Conventional Commits specification, with a subject-first default and optional notes only when needed:

<type>(<scope>): <description>

- <optional note 1>
- <optional note 2>

Commit Types:

feat: New features or functionality
fix: Bug fixes (explicitly visible in diff)
docs: Documentation updates
style: Code formatting and style changes
refactor: Code restructuring without behavior change
test: Test additions or modifications
chore: Maintenance tasks, dependencies, configuration
build: Build system or dependency changes
ci: CI/CD pipeline modifications
revert: Reverting previous commits

🔀 Merge Commit Handling

When a merge is detected (or --merge is provided), AICO generates a deterministic merge message without calling OpenAI:

merge: <source> into <target>

If branches cannot be determined, it falls back to merge: resolve conflicts.

🌿 Branch Name Generation

Generate semantic branch names from natural language descriptions:

aico -b -c
# Input: "Add user authentication with JWT tokens"
# Output: feat/add-user-authentication-jwt-tokens

Diff context is optional and only used when staged changes are present; branch naming primarily follows user intent.

Branch naming follows the pattern: <type>/<kebab-case-description>

🔧 Advanced Usage

Development Workflow Integration

# High-quality commits for important features
git add .
aico -f -c

# Quick commits during development
git add .
aico

# Merge commit handling
git merge feature-branch
aico --merge

# Branch creation workflow
aico -b -c
git checkout -b $(aico -b -c --output-only)

Large Diff Handling

For large changes (>30K characters), AICO will:

Analyze diff size and structured signals
Prompt for model selection (GPT-4o vs GPT-4o-mini)
Suggest breaking into smaller commits if needed
Apply fallback strategies when summaries are necessary

Debug Mode

Enable detailed logging for troubleshooting:

aico -d  # Debug mode with verbose output

Debug output includes:

Git diff analysis results
OpenAI API request/response details
Configuration loading steps
Processing time metrics

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for:

Development setup instructions
Code style guidelines
Testing requirements
Pull request process

📋 Development

Local Development Setup

# Clone repository
git clone https://github.com/EthanDM/aico.git
cd aico

# Install dependencies
npm install

# Build in watch mode
npm run watch

# Test locally
npm run start -- --help

Available Scripts

npm run build: Compile TypeScript to JavaScript
npm run watch: Build in watch mode for development
npm run start: Run the CLI locally
npm run test: Run test suite (Jest)
npm run lint: Run ESLint for code quality
npm run prepare: Pre-commit build hook

Technology Stack

TypeScript: Type-safe development
Commander.js: CLI framework and argument parsing
Inquirer.js: Interactive command-line interfaces
OpenAI SDK: GPT model integration
simple-git: Git operations wrapper
Zod: Runtime type validation
Chalk: Terminal color styling
Figlet: ASCII art banners

📄 License

🆘 Support

📋 Issues: Bug reports and feature requests
💬 Discussions: Questions and community support
📖 Wiki: Extended documentation

Built with ❤️ for developers who care about clean commit history

Name		Name	Last commit message	Last commit date
Latest commit History 149 Commits
.github		.github
src		src
.gitignore		.gitignore
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
config.example.json		config.example.json
package-lock.json		package-lock.json
package.json		package.json
test.txt		test.txt
tsconfig.json		tsconfig.json

License

EthanDM/aico

Folders and files

Latest commit

History

Repository files navigation