🚀 AutoCommitBot (v1.4.0)

Maintain a professional GitHub presence with AI-powered automation and built-in security.

AutoCommitBot is an intelligent CLI tool for developers who want a consistent contribution history without the manual overhead. It monitors your local repositories, generates meaningful commit messages using Google's Gemini AI, and manages the full Git lifecycle automatically — all authenticated through the GitHub CLI so no tokens or passwords ever need to be configured by hand.

🖥️ Preview

🌟 Why AutoCommitBot?

• Zero-friction auth — Piggybacks on your existing gh login; no tokens, no PATs, no manual username entry
• AI Commit Messages — Generates meaningful, context-aware commits instead of generic updates
• Security (Secret Shield) — Prevents accidental exposure of sensitive files and credentials
• Natural Activity Mode — Simulates realistic developer commit patterns
• Manual vs. Background Control — [NEW] Choose between interactive manual runs and strictly automated background heartbeats
• Backup & Restore — Enables complete rollback of local and remote states
• Automated Execution — Runs seamlessly in the background on system logon

✨ Features

Core Capabilities

• GitHub CLI Auth — Identity verified through your active gh session; repos fetched & cloned via gh automatically
• AI Commit Generation — Context-aware commit messages using Gemini with model fallback
• Security Layer (Secret Shield) — Automatic protection against sensitive file and credential exposure
• Interactive Manual Mode — [NEW] Choose whether to commit real work or perform a Heartbeat commit manually
• Strict Background Heartbeats — [NEW] Background tasks now strictly perform "Random Activity" commits to maintain streaks without cluttering code history
• Scheduling Engine — Supports logon, fixed-time, and natural activity-based execution
• Backup & Restore — Pre-commit snapshots with full local and remote rollback capability
• Dashboard & Analytics — CLI-based insights into commit history and activity
• Execution Reliability — Built-in retry logic, conflict handling, and network checks
• Decent CLI Theme — Clean, professional, and subtle color-coded output for repository tracking
• Secret Shield — Now includes refined visual markers for protected and exposed files

⚙️ How It Works

1. Verifies your GitHub identity via the GitHub CLI (gh)
2. Detects changes in tracked repositories
3. Syncs with remote using git pull
4. Analyzes git diff using Gemini AI (in Manual mode)
5. Generates a contextual commit message
6. Runs security checks (Secret Shield)
7. Commits and pushes changes
8. Stores a backup snapshot

All of this runs automatically in the background.

🚀 Getting Started

Prerequisites

Before installing AutoCommitBot, make sure you have all of the following:

Important: AutoCommitBot v1.2.7+ requires the GitHub CLI. It uses your existing gh login to verify who you are and to fetch and clone your repositories — no passwords or personal-access tokens needed.

Step 0 — Install & authenticate the GitHub CLI

If you haven't already:

# macOS (Homebrew)
brew install gh

# Windows (winget)
winget install --id GitHub.cli

# Debian / Ubuntu
sudo apt install gh

Then sign in:

gh auth login

Follow the interactive prompts (choose HTTPS, then authenticate via browser). Confirm it worked:

gh auth status
# → ✓ Logged in to github.com as YourUsername

📦 Installation

Option 1: Via pip (Recommended)

pip install autocommitbot

Option 2: From Source

git clone https://github.com/RohitKSahoo/auto-commit-bot.git
cd auto-commit-bot
pip install -e .

🛠️ First-Time Setup

Run the setup wizard once after installation:

autocommit setup

The wizard will:

1. Verify your GitHub identity via gh auth status — no username prompt
2. Fetch your repositories from GitHub using gh repo list
3. Let you select which repos to automate (multi-select checklist)
4. Ask for a base folder where repos should be cloned if not already present
5. Ask you to pick a schedule (on logon / fixed time / natural activity)
6. Optionally let you enter a Gemini API key for AI commit messages

Tip: Running autocommit setup again on an already-configured machine shows a short menu so you can update just one section (Repositories, Schedule, or AI key) without repeating the full wizard. On a fresh install the full wizard always runs — no menu.

🛠️ Usage

All commands follow the pattern: autocommit <command>

Run autocommit <command> --help for full details on any command.

⚙️ Setup & Config

📁 Repositories

🔁 Automation

📊 History & System

⚠️ Notes

• GitHub CLI required — autocommit setup will exit with a clear error if gh is not installed or you're not logged in
• Automation runs only on tracked repositories
• restore performs a force push — rewrites remote history, use with caution
• run is for manual triggering, not regular use
• Internet connection required for push, version check, and AI commit messages
• On Logon mode caps random activity at 5 per calendar day — real code changes always push through, even after the cap is reached
• Always use autocommit uninstall instead of pip uninstall directly — running pip uninstall alone will leave an orphaned task in Windows Task Scheduler that silently fails on every trigger

🔄 Staying Up to Date

Run the following command to check your current version and see if a newer release is available:

autocommit version

Example output when up to date:

AutoCommitBot  v1.3.0
Checking for updates...
✔ You are on the latest version (1.3.0).

🎉 New in this version (v1.3.0):
  • Fixed background hangs in Task Scheduler by redirecting output to logs
  • Added global timeouts to all Git operations to prevent indefinite stalls
  • Fixed encoding crashes on Windows (UTF-8 support for log files)
  • Optimized Secret Shield performance for faster repository scanning
  • Shortened scheduler commands to fit within Windows path limits

Example output when an update is available:

AutoCommitBot  v1.2.7
Checking for updates...
⚡ New version available: 1.2.8 (you have 1.2.7)

📋 What's New in v1.2.9:
  • Refined, easier-on-the-eyes color theme for better commit and security tracking
  • Setup wizard now pre-selects existing repos and suggests your base folder
  • Fixed a bug in the setup flow that prevented repository updates from saving

Run to update:  pip install --upgrade autocommitbot

To update manually at any time:

pip install --upgrade autocommitbot

🔐 Security Notes

• Your code is not stored externally (only analyzed for commit messages)
• Sensitive files are automatically excluded via .gitignore
• Identity is verified through your local gh session — no credentials are stored by AutoCommitBot
• restore uses force push — use with caution

🆘 Support & Contributions

• Report issues: https://github.com/RohitKSahoo/auto-commit-bot/issues
• Contributions welcome (see CONTRIBUTING.md)
• Additional docs in /docs

👤 Maintainer

Maintained by @RohitKSahoo

📄 License

This project is licensed under the GNU General Public License v3.0.

You are free to use, modify, and distribute this software under the terms of the license. Any derivative work must also be open-sourced under GPL v3.

See the LICENSE file for full details.

🧾 TL;DR

AutoCommitBot is a smart Git automation layer with AI, security, and recovery built in — authenticated entirely through your existing GitHub CLI session.