AI-Powered Commit Workflow

Nanx can generate commit messages by analyzing your code changes using AI, following the ACCID format (Atomic Conventional Consistent Immutable Durable). This guide covers setup, usage, and best practices for AI-powered commits.

Prerequisites

1. Configure an AI provider (Anthropic, OpenAI, Google, OpenCode, or Ollama)
2. Have API credentials ready (or use OpenCode's auto-detection)
3. Enable AI commit generation in config

See AI Providers Setup for detailed configuration.

Quick Start

# 1. Configure AI provider (one-time setup)
nanx config edit

# Add your provider:
providers:
  - type: anthropic
    api_key: sk-ant-...
    models:
      - claude-3-5-sonnet-20241022

# 2. Stage your changes
nanx r a .

# 3. Generate commit message
nanx r c --gm

# Or use the composite command
nanx r cgm

How It Works

The Generation Process

1. Analyze Changes - Nanx runs git diff --staged
2. Send to AI - Diff is sent to your configured AI provider
3. Generate Message - AI analyzes changes and generates message (with animated progress indicator New in v0.3.0 )
4. Review & Edit - You can review and modify the message
5. Commit - Changes are committed with final message

What the AI Sees

The AI receives:

• Full staged diff (git diff --staged)
• File names and paths
• Added/removed/modified lines
• Your commit message format preference
• Optional: project context from .repo.yml

What Gets Generated

The AI generates:

• Commit message following your configured format
• Summary of changes (what changed)
• Reasoning for changes (why it changed)
• Proper conventional commit tags
• Optional: multi-line body with details

Configuration

Basic Configuration

# config.yaml
repo:
  commit:
    generate_message:
      enabled: true
      provider: anthropic
      model: claude-3-5-sonnet-20241022

Advanced Configuration

# config.yaml
repo:
  commit:
    generate_message:
      default_provider: anthropic
      format: accid                    # accid (default), conventional, or custom
      rules_file: .nanx/rules.md       # Optional: custom rules or @extends
      auto_stage: false
      max_tokens: 500
      temperature: 0.7                 # 0.0-1.0 (lower = more deterministic)

Configuration Options

Embedded Formats & Custom Rules

Nanx comes with two built-in commit message formats embedded in the binary: ACCID (default) and Conventional Commits. You can use these formats as-is, or extend them with your own custom rules.

Using Built-in Formats

ACCID Format (Default)

The default format when no configuration is specified. Provides rich context with URIs, issue IDs, and structured change descriptions.

# No config needed - ACCID is default
# Or explicitly:
repo:
  commit:
    generate_message:
      format: accid

Conventional Commits Format

Standard Conventional Commits format as defined by conventionalcommits.org.

repo:
  commit:
    generate_message:
      format: conventional

Extending with Custom Rules

You can extend the built-in formats with project-specific rules in two ways:

Method 1: Config-Based Extension

Specify both format and rules_file in your config:

repo:
  commit:
    generate_message:
      format: accid
      rules_file: .nanx/commit-rules.md

Create .nanx/commit-rules.md:

## Project-Specific Rules

- Always include Jira ticket ID (PROJ-XXX format)
- Use emoji prefixes for commit types
- Reference related PRs in footer
- Mention breaking changes explicitly

Method 2: File-Based Extension

Use the @extends directive in your custom rules file:

repo:
  commit:
    generate_message:
      rules_file: .nanx/commit-rules.md

Create .nanx/commit-rules.md with @extends:

# @extends accid-commit

## Project-Specific Rules

- Include Jira ticket ID in format PROJ-XXX
- Use emoji prefixes:
  - 🎉 for feat
  - 🐛 for fix
  - 📝 for docs
  - ♻️ for refactor
- Reference PRs as "Refs: #123"

Extending Conventional Commits

# @extends conventional-commit

## Custom Rules

- Always wrap header at 50 characters
- Include [BREAKING] prefix for breaking changes
- Use scopes consistently: auth, api, ui, db
- Add migration notes in footer when needed

Custom Format (No Base Spec)

If you want complete control, use format: custom:

repo:
  commit:
    generate_message:
      format: custom
      rules_file: .nanx/my-format.md

Your my-format.md defines the entire commit format from scratch.

Rules File Resolution

Rules files are resolved in this order:

1. Absolute path: /path/to/rules.md
2. Relative to config file location
3. Relative to git repository root
4. Relative to current directory

Available Extends Directives

Usage Patterns

Basic Workflow

# Make changes
# ... edit files ...

# Stage changes
nanx r a .

# Generate and commit
nanx r c --gm

# Review message in editor
# Save to commit

With Context Hint

# Provide additional context
nanx r cgm "fixing bug in user authentication"

# AI uses your hint to generate better message

Quick One-Liner

# Stage, generate, and commit in one command
nanx r acgm

# Or with context
nanx r acgm "implement dark mode toggle"

Generate + Push

# Stage, commit with AI, and push
nanx r acgmp

# Or just generate + push (if already staged)
nanx r cgmp

Message Formats

ACCID Format (Recommended)

format: accid

Example generated message:

#123 [auth] feat: implement OAuth 2.0 login flow

- [auth::services::AuthService] add OAuth provider integration
- [auth::controllers] add /oauth/callback endpoint
- [auth::models::User] add oauth_provider and oauth_id fields

Implements standard OAuth 2.0 authorization code flow with PKCE.
Supports Google, GitHub, and Microsoft providers.

See ACCID Format Guide for details.

Conventional Commits Format

format: conventional

Example generated message:

feat(auth): implement OAuth 2.0 login flow

Add OAuth provider integration with support for Google, GitHub,
and Microsoft. Implements standard OAuth 2.0 authorization code
flow with PKCE for enhanced security.

BREAKING CHANGE: Authentication endpoints have moved to /auth/v2

Simple Format

format: simple

Example generated message:

Add OAuth 2.0 authentication support

Implements OAuth login flow with Google, GitHub, and Microsoft
providers. Uses PKCE for security.

Best Practices

1. Make Focused Commits

AI works best with clear, focused changes:

# Good: Single feature
nanx r a src/auth/oauth.ts src/auth/providers/
nanx r cgm

# Avoid: Mixed unrelated changes
nanx r a .  # (100 files across multiple features)

2. Provide Context Hints

# Without hint - AI guesses
nanx r cgm

# With hint - AI has better context
nanx r cgm "fix race condition in session cleanup"

3. Review Before Committing

Always review the generated message:

• Verify accuracy of description
• Check for sensitive information
• Ensure proper formatting
• Add additional context if needed

4. Use Appropriate Temperature

# More consistent (recommended)
temperature: 0.3

# More creative (may vary)
temperature: 0.7

# Completely deterministic
temperature: 0.0

5. Configure Fallback Provider

generate_message:
  provider: anthropic
  fallback_provider: openai  # If primary fails

Cost Management

Understanding Costs

Each AI-generated commit uses tokens:

• Input tokens: Your diff + context (~500-2000 tokens)
• Output tokens: Generated message (~100-300 tokens)
• Estimated cost: $0.01-0.05 per commit

Cost Optimization Tips

1. Use cheaper models for simple commits
2. Limit max_tokens - Shorter messages = lower cost
3. Use local models - Ollama is free
4. Batch commits - One larger commit vs many small
5. Monitor usage - nanx monitor ai

Model Cost Comparison

Troubleshooting

No AI Provider Configured

Error: No AI provider configured

# Solution: Configure provider
nanx config edit

providers:
  - type: anthropic
    api_key: sk-ant-...

API Rate Limit

Error: Rate limit exceeded

# Solution 1: Wait and retry
sleep 60 && nanx r cgm

# Solution 2: Use fallback provider
generate_message:
  fallback_provider: openai

Poor Quality Messages

# Try:
# 1. Provide more context
nanx r cgm "context about what you're fixing"

# 2. Use better model
model: claude-3-5-sonnet-20241022  # vs claude-3-haiku

# 3. Lower temperature for consistency
temperature: 0.2

Message Too Long

# Reduce max tokens
generate_message:
  max_tokens: 300  # vs 500

# Or use simple format
format: simple

Examples

Feature Development

# Work on feature
# ... implement OAuth login ...

# Stage changes
nanx r a src/auth/

# Generate commit with context
nanx r cgm "implement OAuth login with Google provider"

# Review and commit
# Message generated:
# feat(auth): implement OAuth 2.0 with Google provider

Bug Fix

# Fix bug
# ... fix session cleanup race condition ...

# Quick commit
nanx r acgm "fix race condition"

# Message generated:
# fix(session): prevent race condition in cleanup task

Refactoring

# Refactor code
# ... extract UserService ...

nanx r acgm "extract user service"

# Message generated:
# refactor(user): extract business logic to UserService

Advanced Topics

Custom Prompts

Coming soon: Custom prompt templates for domain-specific messages.

Team Conventions

Share config across team:

# .repo.yml (committed to git)
commit:
  template: accid
  require_issue_id: true

# Team members inherit settings

CI/CD Integration

Use AI commits in automated workflows:

# In CI pipeline
nanx repo acgm "automated dependency update" --yes

Next Steps

• Setup AI Providers
• ACCID Commit Specification
• Repository Commands
• Monitor AI Usage