autocommitbot 1.4.1

Automatic GitHub commit bot that logs developer activity.

🚀 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

🔍 View Full Feature Breakdown

⚙️ Setup & Configuration

• Identity verified via GitHub CLI (gh auth login) — no username prompt, no tokens
• Repository list fetched with gh repo list (authenticated)
• Interactive multi-select repo setup
• Base folder configuration
• Automatic cloning via gh repo clone (inherits your gh session)
• Git authentication verification
• Backward navigation during setup

---

🕐 Scheduling System

• Logon trigger (Windows Task Scheduler) — Strictly performs Random Activity (Heartbeat) commits in the background
• Fixed-time daily scheduling
• Randomized daily execution (9 AM – 11 PM)
• Natural Activity Mode (probabilistic commits with 48h enforcement)
• Runs with highest privileges
• Works on battery power

---

🔁 Commit Engine

• Smart change detection across repositories
• Manual Run: Interactive menu to choose between User Changes vs. Heartbeat
• Background Run: Strictly Heartbeat (Random Activity) mode
• Automatic pull → merge → push workflow
• Push retry logic on failure

---

🤖 AI Commit System

• Gemini AI integration for commit messages
• AI Key Validation — Real-time verification of your API key during setup
• Model fallback chain: 2.5 Flash → 2.0 Flash → 1.5 Flash → Pro
• Diff truncation for large inputs (8000 chars)

---

💾 Backup & Restore

• ZIP snapshot before every commit
• Configurable backup retention (config-backup)
• Restore command with snapshot selection
• Automatic GitHub rollback via force push
• Clear all backups on demand (clear-backups)

---

📊 Dashboard & Management

• Dashboard with last 50 commits (rich table view)
• Commit classification (User vs Activity)
• Status command for tracked repos
• Add/remove repositories dynamically
• Persistent history tracking (500 entries)
• Clean uninstall command — removes scheduler task before uninstalling
• Version check command — shows installed version and detects available updates

---

🌐 Reliability Layer

• Internet availability check (retry up to 2 minutes)
• Automatic admin privilege escalation
• Resilient Git operations with fallback handling

---

⚙️ 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:

Requirement	Why it's needed	Get it
Python 3.8+	Runtime	python.org
Git	Version control	git-scm.com
GitHub CLI (gh)	Identity verification & repo access	cli.github.com
Gemini API key (optional but recommended)	AI-generated commit messages	aistudio.google.com

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

Command	What it does
autocommit setup	First-time wizard, or edit repos / schedule / AI
autocommit config-backup <days>	Set how long backups are kept

📁 Repositories

Command	What it does
autocommit add [path]	Track a new local git repo
autocommit remove	Stop tracking a repo
autocommit status	List all tracked repos

🔁 Automation

Command	What it does
autocommit run	[Interactive] Commit changes or heartbeat now
autocommit enable	Register the Windows auto-start task
autocommit disable	Remove the Windows auto-start task

📊 History & System

Command	What it does
autocommit dashboard	View commit history & stats
autocommit restore	Roll back a bot commit from snapshot
autocommit clear-backups	Delete all backup snapshots to free disk space
autocommit version	Check installed version & updates
autocommit uninstall	Remove scheduler task then pip uninstall

---

⚠️ 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.