Author: Jachin Samuel jachinsamuel007@gmail.com
█████╗ ██████╗ ███████╗
██╔══██╗ ██╔════╝ ██╔════╝
███████║ ██║ █████╗
██╔══██║ ██║ ██╔══╝
██║ ██║ ╚██████╗ ███████╗
╚═╝ ╚═╝ ╚═════╝ ╚══════╝
Ace is an intelligent command-line tool that brings AI assistance directly to your Git workflow. Talk to Git in plain English — Ace translates your intents into Git commands, explains what it is doing, and runs them safely. It also features a fully interactive terminal user interface (TUI) dashboard to help manage your repositories with ease.
- Natural Language Git Commands: Translate commands like "undo my last commit but keep changes" or "create a branch login-page" into clean, standard Git actions.
- AI-Powered Commits: Analyzes staged diffs and generates Conventional Commit messages automatically.
- Automated Code Review: Rates code quality and points out bugs, security flaws, or styling issues inside staged or unstaged diffs.
- Merge Conflict Resolution: Interactively walks you through conflict blocks and suggests correct merges.
- Rich Repo Stats and Changelogs: Instantly computes repository statistics (commits, additions, deletions, file counts) and generates markdown release notes since the last tag.
- Semantic Commit Search & Checkout: Search commits by natural language queries and interactively inspect diffs, checkout commits, or create branches.
- Interactive TUI Dashboard: Run
ace dashto launch a terminal interface showing current status, branch info, workspace repository listings, and interactive menus. - Repository Health Diagnostics: Run
ace doctorto run repository health checks (detached heads, locks, large files) and generate step-by-step AI recovery advice. - Smart Git Hooks: Run
ace hook installto register pre-commit code review checks and prepare-commit-msg message drafting. - AI Auto-Squashing & Rebasing: Run
ace squashto automatically analyze branch commits and run automated interactive rebases. - Safety Features: Classifies actions into safe, moderate, or destructive levels, and requests confirmation before running destructive operations.
For Python command-line applications like Ace, it is highly recommended to install using pipx. pipx automatically installs the application in an isolated environment and manages your system PATH so the executable works globally without conflict.
-
Install pipx and configure your system PATH (only needs to be done once):
pip install pipx pipx ensurepath
(Note: If
pipx ensurepathmodified your path, close your current terminal window and open a new one to apply). -
Install Ace:
pipx install ace-git-copilot
-
Run it directly:
ace dash
You can also install Ace globally using standard pip:
pip install ace-git-copilotNote: If you run into a command not found error, you can bypass your system PATH and run the tool directly through Python module execution:
python -m ace dashRun the built-in configuration wizard to select your AI model provider:
ace setupAce saves your configuration file to ~/.ace/config.toml. It supports the following AI model providers:
Uses cloud-hosted high-performance models.
- You will need an NVIDIA developer API key. Get one for free at NVIDIA build.
- Default model:
meta/llama-3.3-70b-instruct
For a 100% private, offline, and free experience.
- Ensure Ollama is installed and running on your system.
- Default model:
qwen2.5-coder:7b - If the selected model is not downloaded yet, Ace will automatically pull it for you during setup.
Uses OpenAI GPT models.
- You will need an OpenAI API key.
- Default model:
gpt-4o-mini
Uses Anthropic Claude models.
- You will need an Anthropic API key.
- Default model:
claude-3-5-sonnet-latest
Allows using any custom endpoint that supports the OpenAI API schema (e.g. Groq, OpenRouter, Together AI).
- You will need the provider's API key and custom API base URL (e.g.
https://api.groq.com/openai/v1). - Default model:
custom-model
Run natural language requests directly in quotes:
ace "stage everything and commit with a message about authentication"
ace "undo my last commit but keep the files"
ace "switch to a new branch called design-updates"Ace has dedicated subcommands for specific tasks. Here is the complete command list:
| Command | Shorthand | Description |
|---|---|---|
ace setup |
— | Launch the initial setup wizard to configure AI models. |
ace stage [files] |
ace add |
Stage specific files or all untracked changes. |
ace commit |
— | Generate Conventional Commit messages from diffs and commit. |
ace review |
— | Run code review on staged, unstaged, or branch changes. |
ace resolve |
— | Step-by-step interactive merge conflict resolver. |
ace explain <query> |
— | Explain complex Git commands or repository errors. |
ace doctor |
— | Run repository diagnostics and generate step-by-step AI recovery recipes. |
ace hook <action> |
— | Install or uninstall pre-commit and prepare-commit-msg Git hooks. |
ace stats |
— | Rich visualization of repo statistics, extension breakdowns, and history. |
ace changelog |
— | Compile release changelogs since the last tag. |
ace pr |
— | Draft a Markdown pull request title and description. |
ace search <query> |
— | Semantically search commit history with interactive checkout options. |
ace squash |
— | Automatically analyze commit history and run AI-guided interactive rebases. |
ace ignore <rule> |
— | Generate and append standard templates to .gitignore. |
ace undo |
— | Safely revert the last action after checking repository status. |
ace dash |
— | Launch the interactive repository management console (TUI). |
ace config |
— | Print out active configuration settings. |
ace help |
— | Show user guide and help information on how to use Ace. |
Launch the repository dashboard by running:
ace dashThe dashboard features:
- A start-up logo.
- Active branch info, tracking status, and repository charts.
- Interactive shortcuts for one-key commits, reviews, undos, and configuration management.
Distributed under the MIT License. See LICENSE for more details.
- Implemented streaming progress and download percentages for Ollama model pulls to prevent thread hangs.
- Added atomic file saves and rollback backups for merge conflict resolutions and config modifications to prevent data corruption.
- Fixed merge/rebase detection in git worktrees and submodules by resolving the authoritative
git_dirdynamically. - Added
shlexcommand splitting to safely parse and execute quoted arguments in Git commands. - Created python module entry point (
python -m ace) for nested execution support.
- Resolved Windows-specific UTF-8 encoding issues in E2E tests and log parsers.
- Fixed subprocess natural language command execution paths to execute nested ace commands through Python interpreter contexts.
- Refactored CLI error panel formatting to match expected exception names.
- Fixed invisible key labels (
[c],[r], etc.) in the dashboard and search menus caused by Rich markup tag conflicts. - Fixed
[Y/n]confirmation prompt rendering invisibly.
- Rewrote all UI output modules (
display.py,prompts.py,dashboard.py,themes.py) for a polished, professional look. - Removed all unprofessional emojis; replaced with clean ASCII status symbols (
>>,**,!!,EE). - Dashboard panels now use consistent
ROUNDEDborders, colour-coded file lists (+staged,~unstaged,?untracked), and a styled commit history table. - Execution plan table uses
SIMPLE_HEADstyle with colour-highlightedgitandacecommand prefixes. - Commit message panel shows character count badge coloured green/amber/red relative to the 72-char limit.
- AI code review score rendered as a styled badge based on score range.
- Added
[tool.ruff]configuration to exclude.agents/scratch folder from lint checks.
- Fixed broken
pyproject.tomlTOML syntax (invalid inlineurlstable). - Added full
authorsand[project.urls]metadata visible on PyPI.
- Implemented lazy-loading for all heavy LangChain imports — CLI startup under 200 ms.
- Added
ace switchcommand for switching between sibling repositories from the dashboard.
- Added
ace doctor,ace hook, andace squashcommands. - Comprehensive E2E test suite added under
tests/e2e/.