autocommit-forge

v0.5.46

Published

a month ago

⚡ AI Git auto commit generator: intelligent automatic commits with 11 AI providers, free cloud tiers, local Ollama, secret leak guard & 60% diff compression.

AutoCommit Forge ⚡ AI Git Auto Commit Generator

AutoCommit Forge is the intelligent Git auto commit tool and AI commit message generator. Stop writing fix stuff or asdf — automatically produce thoughtful, high-quality conventional commits from staged changes (git diff --cached) using 11 AI providers (including 100% free cloud tiers & local offline Ollama), smart diff compression, and a zero-leak secret scanner.
🚀 Made with ❤️ by Greg Palka.

AutoCommit Forge automates your daily Git commit workflow. It reads your staged changes, strips the boilerplate noise (lockfiles, minified bundles, lone curly braces), scans for credentials so you never leak secrets, and drafts clean conventional commit messages using your favorite provider (free cloud tiers, blazing-fast LPUs, or 100% local offline models).

⚡ Quick Start (In 30 Seconds)

Option 1: Run instantly with zero install

# Run quick generation (auto-detects keys or offers setup)
npx autocommit-forge

# Generate 3 candidates to pick from:
npx autocommit-forge -c 3

Option 2: Install globally and use the short command `acf`

npm install -g autocommit-forge

# Single-entry quick commit:
acf

# Generate 3 candidates:
acf -c 3

# Amend the previous commit:
acf --amend

# Configure native git aliases (`git ac` and `git ai`):
acf alias

$ acf -c 3
✔ Staged 2 files.
✔ Secret scanner: 0 leaks detected.
✔ Generated 3 candidates via groq (llama-3.3-70b-versatile) in 320ms:

? Choose a commit message or action:
❯ 1. ✨ feat(auth): add passkey authentication support (#104)
  2. ♻️ refactor(auth): migrate session tokens to WebAuthn credentials
  3. 🔒 fix(security): prevent session token replay in auth middleware
  ✎  Edit message manually
  🔄 Regenerate new candidates
  ✖  Cancel / Abort

🏆 Why AutoCommit Forge? (The Modern Git Auto Commit Tool)

Comparing popular Git auto commit tools and AI commit generators:

🆓 100% Free AI Options (No Credit Card Required!)

You do not need a paid subscription or credit card to use AutoCommit Forge! Choose from any of the completely free options:

Google Gemini (Official Free Tier):
- Get an official API key from Google AI Studio in under a minute with just a Google account.
- No credit card required.
- Generous free-tier rate limits (up to 15 requests/min and 1,000,000 tokens/min).
- Powered by Google's fastest, smartest models: gemini-2.0-flash, gemini-2.5-flash, and gemini-1.5-flash.
Groq (World's Fastest Inference — Free Tier):
- Create a free account at Groq Console with no credit card required.
- Blazing-fast LPU inference: generates commit messages in ~200-400ms!
- Free access to top open-weight models: llama-3.3-70b-versatile, llama-3.1-8b-instant, mixtral-8x7b-32768, and gemma2-9b-it.
OpenRouter (Free Community Models):
- Create a free account at OpenRouter with no credit card or payment info required.
- Access free models ending with the :free suffix, such as:
  - google/gemini-2.0-flash-exp:free
  - meta-llama/llama-3.3-70b-instruct:free
  - qwen/qwen-2.5-72b-instruct:free
  - meta-llama/llama-3.1-8b-instruct:free
- AutoCommit Forge includes free OpenRouter models directly in the setup selection menu!
Ollama (100% Local, Offline & Private):
- Run models completely offline on your CPU/GPU with Ollama (llama3.1, qwen2.5, mistral, deepseek-r1).
- Zero internet access needed, zero cost, and total privacy for your codebase.

🔒 Zero-Leak Security Architecture

AutoCommit Forge is engineered with strict safeguards so you don't become accidentally famous on Twitter/X for leaking your credentials:

Pre-Commit Secret Scanner: Scans staged diff additions (+) against known signatures for Google Gemini, Groq, OpenAI, DeepSeek, Anthropic, OpenRouter, Together AI, Perplexity, AWS, GitHub PATs, Slack, and private keys. If you accidentally left an API key in your code, we slam the brakes before sending the payload.
In-Memory Redaction: All internal debug loggers (AUTOCOMMIT_FORGE_DEBUG=1), request headers, and error handlers sanitize and mask sensitive tokens (maskSecret) so raw credentials never appear in terminal output, logs, or error stack traces.
Filesystem Hardening: Configuration directory ~/.autocommit-forge is locked to POSIX 0700 (rwx------) and config.json is locked to 0600 (rw-------), ensuring other users on your machine cannot read your keys.
Zero Telemetry: Keys and code diffs are sent exclusively to the endpoint of your chosen provider. AutoCommit Forge has no intermediate proxy, analytics, or collection servers.

Features

Instant Git Auto Commits: Single-entry quick mode (acf or autocommit-forge) to automatically stage, scan, generate, review, and commit in one smooth command.
Multi-Candidate Commit Options: Generate multiple commit message candidates (acf -c 3) and pick the best one with interactive keyboard navigation.
Pre-Commit Secret Scanner: Saves you from the ultimate dev nightmare by catching AWS keys, GitHub tokens, and private keys before they ever leave your machine.
Smart Scope Detection: Automatically determines Conventional Commit scopes from modified file paths (e.g., feat(auth):, fix(cli):, docs:, deps:).
Interactive Review & Iterative Steering: Reject messages and provide custom guidance (e.g., "focus on the refactoring, not the bug fix") for up to 5 regeneration attempts.
Interactive Staging Assistance: Forgot git add again? We detect your unstaged files and offer to stage them for you so you don't have to re-run the command.
11 AI Providers Supported: Google Gemini, Groq, OpenRouter, DeepSeek, Mistral AI, Together AI, OpenAI, Anthropic Claude, Perplexity Agent, Perplexity Chat, and Ollama.
Free Key Support: Built-in direct support for Google Gemini's free tier, Groq's free tier, and OpenRouter's free community models with no payment details required.
Comprehensive API Key Support: Works with AIzaSy..., gsk_..., sk-..., sk-proj-..., sk-ant-..., sk-or-v1-..., pplx-..., tog_..., custom OpenAI-compatible endpoints, or zero-key local models.
Zero-Config Fallbacks: Supports standard environment variables (GEMINI_API_KEY, GROQ_API_KEY, DEEPSEEK_API_KEY, MISTRAL_API_KEY, TOGETHER_API_KEY, OPENROUTER_API_KEY, OPENAI_API_KEY, ANTHROPIC_API_KEY, PERPLEXITY_API_KEY).
Secure File Permissions: Protects API keys with 0600 file permissions and 0700 config directory permissions.
AI-Optimized Diff Compression: Cuts token consumption by ~59% by pruning git headers, noise files, structural brackets, comments, and import statements.
Conventional Commits & Deterministic Emojis: Automatic type inference (feat, fix, docs, refactor, etc.) with clean, predictable emojis.
Custom Project Rules & Few-Shot Examples: Tailor generated commits to your team's guidelines and example formats.
Git Hook Integration: Drop-in prepare-commit-msg hook with smart bypass for manual messages, merges, and rebases.
Signing Support: Supports Git commit sign-offs (-s / --signoff) and cryptographic GPG signing (-S / --gpg-sign).
Animated Terminal UI: Real-time spinner with clean non-TTY fallback for CI/CD environments.

Installation

Install AutoCommit Forge globally via npm:

npm install -g autocommit-forge@latest

Verify that the CLI is accessible:

autocommit-forge --help

Building from Source

git clone https://github.com/Gregu90/AutoCommit-Forge.git
cd AutoCommit-Forge
npm install
npm run build
npm link

Quick Start

1. Configure the CLI (one-time setup)

autocommit-forge setup

The interactive wizard prompts you for your provider, API key, model, tone, length limit, and optional rules.

Tip: Choose Gemini, Groq, or OpenRouter to use completely free AI models without needing a paid account or credit card!

2. Stage your changes

git add src/auth.ts

(If you forget to stage files, AutoCommit Forge will detect your unstaged files and offer to stage them for you!)

3. Generate and commit

autocommit-forge

Review the proposed commit message, press Enter to accept, and your commit is created immediately!

Execution Modes & Workflows

AutoCommit Forge accommodates different developer preferences and automation pipelines:

1. Single-Entry Quick Mode

Simply run the base command without any subcommands:

autocommit-forge

End-to-End Workflow:

Validates that the current directory is a Git repository.
Checks for staged changes. If none exist, checks for unstaged/untracked files and prompts: "Would you like to stage all changes (git add -A) and proceed?"
Runs the Secret Scanner across staged additions to prevent credential leakage.
Detects the primary Conventional Commit scope based on changed paths.
Sends the compressed diff to your configured AI provider with an animated terminal spinner.
Presents the message in an interactive prompt:
- Yes, use this message: Commits staged files with the message (honoring signoff and GPG signing).
- No, regenerate a different message: Asks for optional steering guidance and requests a fresh variation from the AI.

2. Interactive Setup Wizard

autocommit-forge setup

The setup command guides you through:

Provider selection: Choose between Gemini, Groq, OpenRouter, DeepSeek, Mistral, Together AI, OpenAI, Anthropic, Perplexity Agent, Perplexity Chat, or Ollama.
API Key entry: Password-masked input saved securely to ~/.autocommit-forge/config.json.
Dynamic & Curated Model Selection:
- Direct selection of top models (e.g., gemini-2.0-flash, llama-3.3-70b-versatile, deepseek-chat, codestral-latest, gpt-4o-mini, claude-3-5-sonnet).
- Access to free models on OpenRouter (e.g., google/gemini-2.0-flash-exp:free, meta-llama/llama-3.3-70b-instruct:free).
- Option to enter any custom model slug for any provider.
- Dynamic query to Perplexity (/v1/models) and local Ollama (/api/tags).
Conventional Commits: Toggle type(scope): summary format.
Tone: Select default tone (neutral, casual, formal, funny, professional, direct).
Max Commit Length: Character ceiling (default: 150 characters).
Rules:
- Add fixed emote icons per commit type.
- Few-shot format examples (example1 and example2).
- Custom project rule prompt.

3. Manual Generation & Flags

Run autocommit-forge generate with flags for fine-grained control:

# Preview the message without creating a commit (dry-run)
autocommit-forge generate --no-commit

# Commit automatically without interactive confirmation
autocommit-forge generate --auto

# Temporarily override tone
autocommit-forge generate --tone direct

# Enable matching emojis for this commit only
autocommit-forge generate --with-emotes

# Steer format using two few-shot examples
autocommit-forge generate \
  --example-1 "feat(auth): implement oauth2 login" \
  --example-2 "fix(db): handle connection pool timeouts"

# Cryptographically sign commit with GPG and add Signed-off-by trailer
autocommit-forge generate -s -S

# Bypass secret check if committing intentionally mock credentials
autocommit-forge generate --skip-secret-check

4. Git `prepare-commit-msg` Hook

Integrate AutoCommit Forge directly into native git commit commands:

autocommit-forge install-hook

This installs an executable hook at .git/hooks/prepare-commit-msg. When you run:

git add .
git commit

The hook automatically executes AUTOCOMMIT_FORGE_AUTO=1 autocommit-forge generate --hook "$1", pre-filling your commit message in your editor while skipping execution if:

A message was already passed via -m or -F.
The commit is a merge commit or squash commit.
AUTOCOMMIT_FORGE_SKIP_HOOK=1 is set (preventing recursive hook loops).

5. Uninstalling the Git Hook

Decided to switch machines or want manual commit control back? Run:

autocommit-forge uninstall-hook

If the hook was exclusively installed by AutoCommit Forge, the file is cleanly deleted from .git/hooks/prepare-commit-msg. If chained with other tools (like Husky or custom shell scripts), AutoCommit Forge surgically strips its lines and leaves the rest of your hooks untouched.

Interactive Features & Steering

Interactive Review & Iterative Guidance

When a commit message is generated, AutoCommit Forge displays:

feat(auth): implement biometric passkey authentication

? Are you happy with this commit message, or would you like to regenerate it?
❯ Yes, use this message
  No, regenerate a different message

Selecting "No, regenerate a different message" opens a guidance input:

? What should the new message focus on? (optional - press Enter to skip)
> emphasize the WebAuthn API refactoring rather than passkeys

The AI receives your guidance along with the list of previously rejected attempts, preventing repetitive suggestions and steering generation toward your exact intent (up to 5 attempts).

Automatic Unstaged Changes Detection & Interactive Staging

Forgot to run git add before typing autocommit-forge? Don't sweat it. Instead of blowing up with an error, AutoCommit Forge inspects your working tree and presents a 3-way choice:

No staged changes found, but 3 unstaged/untracked file(s) detected:
  M  src/auth.ts
  M  src/types.ts
  ?? tests/auth.test.ts

? No staged changes found. How would you like to stage changes?
❯ Stage all changes (git add -A)
  Pick specific files to stage
  Cancel / Abort

Selecting "Pick specific files to stage" presents an interactive checkbox list where you can toggle exactly which files you want staged with Space and confirm with Enter.

Branch Issue / Ticket Auto-Detection

Working in an agile team with Jira, Linear, or GitHub Issues? AutoCommit Forge automatically inspects your active branch name and extracts ticket identifiers, embedding them cleanly into your commit message:

Custom override: Pass --ticket PROJ-5678 to specify or override the ticket manually.
Disable per run: Pass --no-ticket to omit ticket identifiers for hotfixes or generic changes.
Disable globally: Set "autoDetectTicket": false in your configuration.

Detailed Multi-Line Commit Mode

For complex architectural changes, PRs, or large feature drops, a single line doesn't always tell the whole story. Use --detailed (or --body):

autocommit-forge generate --detailed
# Or shorthand alias:
autocommit-forge generate --body

This instructs the model to produce a structured, multi-line commit message following Git best practices:

A concise, 72-character subject line.
A blank separating line.
2–4 concise bullet points explaining what changed and why.

When combined with emoji rules (--with-emotes), AutoCommit Forge smartly prefixes only the subject line with the relevant emoji, leaving your detailed bullet points crisp and clean.

Automatic Fallback Provider Chain

Never let a provider rate limit (429), temporary outage (503), or network blip interrupt your commit workflow. Configure a secondary fallback provider and model:

{
  "provider": "gemini",
  "model": "gemini-2.0-flash",
  "fallbackProvider": "groq",
  "fallbackModel": "llama-3.3-70b-versatile"
}

If your primary provider runs into an unexpected API error, rate limit, or timeout, AutoCommit Forge seamlessly retries your request with your backup provider without dropping your staged diff or making you start over.

Project-Local Configuration & Zero-Leak Security

Want team-wide conventions or project-specific models without forcing everyone to change their global settings? Place a .autocommit-forge.json or .forge.json file in your repository root:

{
  "provider": "groq",
  "model": "llama-3.3-70b-versatile",
  "defaultTone": "professional",
  "detailed": true,
  "rules": {
    "addEmoteIcons": true
  }
}

🛡️ Bulletproof Key Security:

To prevent accidental credential leaks into version control, AutoCommit Forge strictly sanitizes project-local configs on load: any apiKey or fallbackApiKey declared inside .autocommit-forge.json or .forge.json is completely ignored and stripped. API keys must always live safely in your global user configuration (~/.autocommit-forge/config.json, protected with 0600 permissions) or in environment variables. You can commit your project configuration to Git with total peace of mind.

Smart Conventional Commit Scope Detection

AutoCommit Forge inspects file paths in the diff and identifies the architectural scope:

If at least 40% of changed files share a common module or category, the scope is passed to the AI prompt automatically.

Pre-Commit Secret Scanning Guard

Before sending any code diff over the network to an AI provider, AutoCommit Forge scans all added lines (+) against known credential signatures:

Google / Gemini API Keys: Standard AIzaSy[a-zA-Z0-9_-]{30,} keys
Groq API Keys: gsk_[a-zA-Z0-9]{40,} keys
OpenAI, OpenRouter & DeepSeek API Keys: sk-... (20+ chars) and sk-or-v1-... (32+ chars)
Anthropic API Keys: sk-ant-... (20+ chars)
Together AI Keys: tog_[a-zA-Z0-9]{30,}
Perplexity API Keys: pplx-[a-zA-Z0-9]{20,}
Private Keys: RSA, EC, OpenSSH, PGP, DSA private key headers (-----BEGIN ... PRIVATE KEY-----)
AWS Access Keys: Standard AKIA[0-9A-Z]{16} access keys
GitHub Personal Access Tokens: Classic (ghp_...) and Fine-grained (github_pat_...)
Slack Tokens: Bot, user, app tokens (xoxb-, xoxp-, xoxa-, xoxr-, xoxs-)
High-Entropy Secret Assignments: Inline credential assignments (api_key = "...", password: "...")

Protection Behavior:

Interactive Mode: Warns in yellow with line numbers and masked previews (AIzaSy****xyz), asking: "Do you want to proceed and send this diff to the AI provider anyway?" (defaults to No).
Auto Mode (--auto): Immediately aborts with exit code 1 to safeguard CI/CD pipelines and background scripts. Bypass only with --skip-secret-check.

Deterministic Emoji Integration

When emote icons are enabled (--with-emotes or in setup), AutoCommit Forge does not let the LLM randomly guess emojis. Instead, it parses the Conventional Commit type and prepends the exact deterministic emoji:

| Type | Emoji | Description | | :--- | :---: | :--- | | feat | ✨ | New feature | | fix | 🐛 | Bug fix | | docs | 📚 | Documentation changes | | style | 💎 | Code style / formatting (no logic change) | | refactor | ♻️ | Code refactoring | | perf | 🚀 | Performance improvement | | test | 🚨 | Adding or updating tests | | build | 📦 | Build system or dependencies | | ci | 👷 | CI/CD configuration | | chore | 🔧 | Maintenance and auxiliary tasks | | revert | ⏪ | Reverting a previous commit |

CLI Commands & Options Reference

Commands

Options for `autocommit-forge generate` (or `acf`)

AI Providers & API Key Types

AutoCommit Forge supports eleven distinct provider backends, covering free cloud tiers, high-performance LPU inference, multi-provider routing gateways, specialized code models, frontier APIs, and private local models.

Provider & Key Comparison Matrix

1. Google Gemini (`gemini`) - Free Tier

Google Gemini provides one of the fastest, most generous free AI tiers available today.

Cost: $0.00 — 100% free with no credit card required.
Where to obtain: Google AI Studio API Keys
API Key Format: Starts with AIzaSy (39 characters total, e.g. AIzaSyD-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx)
Supported Models:
- gemini-2.0-flash (Default & Recommended: ultra-fast, highly accurate, large context window)
- gemini-2.5-flash
- gemini-1.5-flash
- gemini-2.5-pro
- Or enter any custom Gemini model ID during setup!
Environment Variable: GEMINI_API_KEY, GOOGLE_API_KEY, or GOOGLE_GENAI_API_KEY
Underlying Protocol: Official Google Gemini OpenAI-compatible endpoint (https://generativelanguage.googleapis.com/v1beta/openai).

2. Groq (`groq`) - Ultra-Fast & Free Tier

Groq runs open-weight models on custom LPU chips, delivering sub-second commit messages at 500+ tokens/second.

Cost: $0.00 — 100% free tier with no credit card required.
Where to obtain: Groq Console API Keys
API Key Format: Starts with gsk_ (e.g. gsk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx)
Supported Models:
- llama-3.3-70b-versatile (Default & Recommended: smart and fast)
- llama-3.1-8b-instant (Instantaneous generation)
- mixtral-8x7b-32768
- gemma2-9b-it
Environment Variable: GROQ_API_KEY
Underlying Protocol: OpenAI-compatible endpoint (https://api.groq.com/openai/v1).

3. OpenRouter (`openrouter`) - Multi-Provider & Free Models

OpenRouter allows you to access hundreds of models across all major AI labs (Meta, Google, Mistral, Qwen, DeepSeek, OpenAI, Anthropic) through a single unified API key.

Free Key & Free Models:
- Sign up for free at OpenRouter API Keys without needing to add a credit card.
- OpenRouter hosts dedicated free tier models with the :free suffix that cost $0.
API Key Format: Starts with sk-or-v1- (e.g. sk-or-v1-abcdef0123456789...)
Supported Models:
- Pre-configured shortcuts in setup:
  - google/gemini-2.0-flash-exp:free (Free tier)
  - meta-llama/llama-3.3-70b-instruct:free (Free tier)
  - qwen/qwen-2.5-72b-instruct:free (Free tier)
  - openai/gpt-4o-mini
  - anthropic/claude-3.5-sonnet
  - google/gemini-2.0-flash
- Custom Model ID Support: Choose "Enter a custom OpenRouter model ID" in setup to use any model from OpenRouter Models.
Environment Variable: OPENROUTER_API_KEY
Underlying Protocol: OpenAI-compatible chat completion client pointed to https://openrouter.ai/api/v1.

4. DeepSeek (`deepseek`) - SOTA Code & Budget Friendly

DeepSeek models are widely praised for industry-leading code benchmark results at ultra-low API costs.

Where to obtain: DeepSeek Platform API Keys
API Key Format: Starts with sk- (32 characters, e.g. sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx)
Supported Models:
- deepseek-chat (Default: DeepSeek-V3 flagship model)
- deepseek-reasoner (DeepSeek-R1 reasoning model)
Environment Variable: DEEPSEEK_API_KEY
Underlying Protocol: OpenAI-compatible endpoint (https://api.deepseek.com/v1).

5. Mistral AI (`mistral`) - Codestral Specialized Code Model

Mistral offers codestral-latest, a model specifically trained on code syntax, version control diffs, and developer workflows.

Where to obtain: Mistral Console API Keys
API Key Format: Alphanumeric 32-character key
Supported Models:
- codestral-latest (Default: purpose-built code model)
- mistral-small-latest
- mistral-large-latest
- open-mistral-7b
Environment Variable: MISTRAL_API_KEY or CODESTRAL_API_KEY
Underlying Protocol: OpenAI-compatible endpoint (https://api.mistral.ai/v1).

6. Together AI (`together`) - Open Models Platform

Access popular open-source models with high reliability and throughput.

Where to obtain: Together AI Settings
API Key Format: Starts with tog_ or 64-char hex key
Supported Models:
- meta-llama/Llama-3.3-70B-Instruct-Turbo (Default)
- deepseek-ai/DeepSeek-V3
- Qwen/Qwen2.5-Coder-32B-Instruct
Environment Variable: TOGETHER_API_KEY
Underlying Protocol: OpenAI-compatible endpoint (https://api.together.xyz/v1).

7. OpenAI (`openai`)

API Key Format:
- User / Legacy keys: starts with sk-
- Project-scoped keys: starts with sk-proj-
- Service account keys: starts with sk-admin-
Where to obtain: OpenAI Platform API Keys
Supported Models: gpt-4o-mini, gpt-4o, o3-mini, gpt-4-turbo.
Environment Variable: OPENAI_API_KEY
Underlying Protocol: Official OpenAI Chat Completions SDK (v1/chat/completions).

8. Anthropic (`anthropic`)

API Key Format: Starts with sk-ant- (e.g. sk-ant-api03-abcdef123456...)
Where to obtain: Anthropic Console API Keys
Supported Models: claude-3-5-sonnet-latest, claude-3-5-haiku-latest, claude-3-opus-latest.
Environment Variable: ANTHROPIC_API_KEY
Underlying Protocol: Direct HTTP POST to Anthropic Messages API (/v1/messages).

9. Perplexity Agent API (`perplexity-agent`)

Perplexity Agent mode utilizes Perplexity's specialized agent architecture with dedicated instruction framing and input diff parameters.

API Key Format: Starts with pplx-
Where to obtain: Perplexity API Settings
Supported Models: Auto-discovered live from https://api.perplexity.ai/v1/models during setup (perplexity/sonar, perplexity/sonar-pro, perplexity/sonar-reasoning-pro).
Environment Variables: PERPLEXITY_API_KEY or PPLX_API_KEY
Endpoint: https://api.perplexity.ai/v1/agent

10. Perplexity Chat API (`perplexity`)

Perplexity legacy chat completion mode using Sonar models via OpenAI-compatible endpoints.

API Key Format: Starts with pplx-
Where to obtain: Perplexity API Settings
Supported Models: sonar-pro (default), sonar, sonar-reasoning-pro.
Environment Variables: PERPLEXITY_API_KEY or PPLX_API_KEY
Endpoint: https://api.perplexity.ai/v1/sonar

11. Ollama (`ollama`) - Local & LAN

Run local open-source LLMs on your own hardware with zero data leaving your machine or local network.

API Key Format: None required. No external credentials, account, or credit cards needed.
Where to obtain Ollama: Ollama Official Website

How to install models:

ollama pull llama3.1
ollama pull qwen2.5
ollama pull mistral
ollama pull codellama

Local Machine Setup: Default URL is http://localhost:11434. Auto-detects installed models via /api/tags.
LAN / Network Machine Setup: Host Ollama on a LAN GPU machine (OLLAMA_HOST=0.0.0.0:11434 ollama serve) and connect via IP (e.g. http://192.168.1.150:11434).

12. Custom & Self-Hosted OpenAI-Compatible Endpoints

AutoCommit Forge can communicate with any server or gateway that implements the OpenAI /chat/completions specification by editing ~/.autocommit-forge/config.json:

{
  "provider": "openai",
  "apiKey": "your-api-key",
  "apiBaseUrl": "http://localhost:1234/v1",
  "model": "your-model-name"
}

Works out of the box with LM Studio, LocalAI, vLLM, and internal gateways.

API Key Resolution & Priority Hierarchy

When authenticating, AutoCommit Forge resolves keys using the following strict precedence:

Explicit configuration key: Value of apiKey in ~/.autocommit-forge/config.json (configured via autocommit-forge setup).
Provider-specific environment variables:
- GEMINI_API_KEY or GOOGLE_API_KEY (for gemini)
- GROQ_API_KEY (for groq)
- OPENROUTER_API_KEY (for openrouter)
- DEEPSEEK_API_KEY (for deepseek)
- MISTRAL_API_KEY or CODESTRAL_API_KEY (for mistral)
- TOGETHER_API_KEY (for together)
- OPENAI_API_KEY (for openai)
- ANTHROPIC_API_KEY (for anthropic)
- PERPLEXITY_API_KEY or PPLX_API_KEY (for perplexity / perplexity-agent)
No Key Required: Ollama bypasses authentication headers unless an optional key is supplied.

Key Storage Security & Unix File Permissions

API keys saved through autocommit-forge setup are written to ~/.autocommit-forge/config.json. AutoCommit Forge sets POSIX file system permissions automatically:

Directory ~/.autocommit-forge: 0700 (rwx------ — accessible only by your user account).
File config.json: 0600 (rw------- — readable and writable only by your user account).

This prevents other local non-root users on shared machines from inspecting your API keys.

⚡ Smart Diff Compression (59%+ Token Savings)

Raw git diffs are packed with noise that burns your token budget without adding any real insight. Nobody needs to feed 5,000 lines of package-lock.json or rearranged import statements to an LLM just to write a commit message. AutoCommit Forge cleans up the diff before sending requests:

Comparison

Standard Git Diff (verbose, token-heavy):

diff --git a/src/auth/login.ts b/src/auth/login.ts
index abc1234..def5678 100644
--- a/src/auth/login.ts
+++ b/src/auth/login.ts
@@ -1,10 +1,15 @@
+import { validateEmail } from '../utils/validation';
+import { hashPassword } from '../utils/crypto';
+
 export function login(email: string, password: string) {
-  // TODO: implement validation
-  return { success: true };
+  if (!validateEmail(email)) {
+    throw new Error('Invalid email');
+  }
+  const hashed = hashPassword(password);
+  return authenticateUser(email, hashed);
 }

AutoCommit Forge AI-Optimized Format:

1 files: +7 -2

Modified (1):
  src/auth/login.ts
    + if (!validateEmail(email)) {
    + const hashed = hashPassword(password);
    + return authenticateUser(email, hashed);
    - // TODO: implement validation
    - return { success: true };

What Gets Filtered & Excluded

Git Metadata Stripping: Removes diff --git, index, ---, +++, and @@ hunk headers.
Boilerplate Suppression:
- Skips import and require statements (import ..., const ... = require(...)).
- Filters bracket-only and punctuation lines ({, }, );).
- Filters comment-only lines (// ..., * ...).
Semantic File Categorization: Groups changes into New, Modified, Deleted, and Renamed.
Smart Line Sampling: For large changes, samples representative lines rather than bloating context.
Automatic File Exclusions:
- Lock files: package-lock.json, yarn.lock, pnpm-lock.yaml, Cargo.lock, Gemfile.lock, composer.lock, poetry.lock, Podfile.lock
- Build artifacts: dist/, build/, out/, .next/, .nuxt/, target/
- Minified & bundles: *.min.js, *.min.css, *.bundle.js
- Source maps: *.map, *.js.map, *.css.map
- Compiled binaries: *.pyc, *.pyo, *.class, *.o, *.so, *.dll
- Dependencies: node_modules/, vendor/, .venv/, venv/

Provider Context Budgets

Context budgets dynamically adapt to prevent provider context-overflow errors:

Gemini: up to 150,000 characters
Anthropic Claude: up to 180,000 characters
DeepSeek: up to 128,000 characters
Mistral AI: up to 128,000 characters
OpenAI: up to 120,000 characters
Groq: up to 100,000 characters
Together AI: up to 100,000 characters
Perplexity & Perplexity Agent: up to 100,000 characters
OpenRouter: up to 100,000 characters
Ollama: up to 30,000 characters (adjusted for local hardware constraints)

Configuration File Reference (`config.json`)

The configuration is stored at ~/.autocommit-forge/config.json. Below is an annotated example of all supported options:

{
  "provider": "gemini",
  "apiKey": "AIzaSyxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "apiBaseUrl": "https://generativelanguage.googleapis.com",
  "model": "gemini-2.0-flash",
  "fallbackProvider": "groq",
  "fallbackModel": "llama-3.3-70b-versatile",
  "autoDetectTicket": true,
  "detailed": false,
  "conventionalCommits": true,
  "defaultTone": "professional",
  "autoMode": false,
  "maxCommitLength": 120,
  "rules": {
    "addEmoteIcons": true,
    "similarFormatExamples": {
      "first": "feat(auth): implement passkey authentication",
      "second": "fix(api): handle token refresh race conditions"
    },
    "customRule": "Focus on high-level impact rather than implementation details"
  },
  "usageCount": 42,
  "signoff": true,
  "gpgSign": false
}

Configuration Fields

provider: Active provider (gemini, groq, openrouter, deepseek, mistral, together, openai, anthropic, perplexity-agent, perplexity, ollama).
apiKey: Stored provider API key (optional if using environment variables).
apiBaseUrl: Custom API endpoint URL (optional; used for custom proxies or Ollama LAN IPs).
model: Exact model name string.
fallbackProvider: Optional secondary provider to retry if the primary fails (rate limit, 503, timeout).
fallbackModel: Exact model name to use when switching to fallbackProvider.
autoDetectTicket: When true (default), extracts ticket identifiers (e.g. PROJ-1234, #42) from branch name.
detailed: When true, defaults to multi-line commit messages (subject + blank line + bullet points).
conventionalCommits: When true, enforces type(scope): summary structure.
defaultTone: Tone applied when --tone is not passed.
autoMode: When true, commits without interactive review prompt.
maxCommitLength: Maximum character length of commit summary (default: 150).
rules.addEmoteIcons: When true, adds deterministic emoji matching the commit type.
rules.similarFormatExamples: Few-shot format examples for style alignment.
rules.customRule: Free-text custom instruction injected into the prompt.
signoff: When true, passes --signoff to git commit.
gpgSign: When true, passes -S to git commit.
usageCount: Cumulative count of successful commits created with the tool.

Environment Variables

Commit Style & Tone Presets

AutoCommit Forge supports six distinct tone presets:

neutral (default): Objective, concise, standard open-source tone.
casual: Friendly, straightforward tone.
formal: Strictly structured and traditional engineering phrasing.
funny: Lighthearted while remaining accurate to code changes.
professional: Polished, enterprise-ready tone suitable for corporate codebases.
direct: Ultra-minimalist, terse, imperative verbs with zero filler words.

Testing & Verification

AutoCommit Forge includes a comprehensive automated test suite:

# Run all automated tests (unit tests, integration diff tests, compression checks)
npm test

# Or run individual test suites:
# 1. Secret scanner, branch ticket detection, local config security, quiet mode, hooks
npx tsx test-improvements.ts

# 2. Test diff compression algorithms and large diff handling
npx tsx test-diff-compression.ts

# 3. Test token savings and noise elimination
npx tsx test-ai-optimization.ts

# 4. Run mock git diff end-to-end integration tests
npx tsx test-integration.ts

# 5. Interactively test live API connectivity across all 11 providers
npx tsx test-all-providers.ts

Troubleshooting

1. `Error: Not inside a Git repository`

Ensure you are running the command within a valid Git repository root or subdirectory:

git status

2. `No changes found in working directory`

Stage the desired files or ensure modified files exist:

git status
git add <files>
autocommit-forge

3. `401 Unauthorized` or `Authentication Error`

Check that your API key is valid and active.
For Gemini: verify your API key is from Google AI Studio.
For Groq: verify your API key is from Groq Console.
For OpenRouter: ensure your key is valid and you selected a :free model or have credits.
If using environment variables, verify they are exported in your current shell:
```
echo $GEMINI_API_KEY
echo $GROQ_API_KEY
```

4. `Failed to fetch Perplexity models`

Check internet connectivity to api.perplexity.ai or verify that your Perplexity API key is active. AutoCommit Forge will automatically fall back to preset Sonar models.

5. `Connection Refused` on Ollama (`http://localhost:11434`)

Ensure Ollama is installed and actively running:

# Verify daemon status
curl http://localhost:11434/api/tags

# Start Ollama service
ollama serve

👤 Author & Maintainer

AutoCommit Forge was created and is actively maintained by Greg Palka (@Gregu90).

🌐 GitHub: https://github.com/Gregu90
📦 Project Repository: https://github.com/Gregu90/AutoCommit-Forge
🐛 Issues & Feedback: https://github.com/Gregu90/AutoCommit-Forge/issues
☕ Support: https://buymeacoffee.com/gregu90

If you find this project useful, please consider giving it a ⭐ on GitHub — it directly boosts discoverability for other developers searching for auto commits tools!

Support

After every 7 successful commits, AutoCommit Forge displays a small support milestone. If this project saves you time and streamlines your development workflow, consider buying me a coffee:

☕ Buy me a coffee: https://buymeacoffee.com/gregu90

License

This project is licensed under the MIT License.