# Ace — AI-Powered Git Copilot
Author: Jachin Samuel <jachinsamuel007@gmail.com>
```text
 █████╗   ██████╗ ███████╗
██╔══██╗ ██╔════╝ ██╔════╝
███████║ ██║      █████╗  
██╔══██║ ██║      ██╔══╝  
██║  ██║ ╚██████╗ ███████╗
╚═╝  ╚═╝  ╚═════╝ ╚══════╝
```

[![PyPI Version](https://img.shields.io/pypi/v/ace-git-copilot.svg)](https://pypi.org/project/ace-git-copilot/)
[![PyPI Downloads](https://img.shields.io/pypi/dm/ace-git-copilot.svg)](https://pypi.org/project/ace-git-copilot/)
[![Python Version](https://img.shields.io/pypi/pyversions/ace-git-copilot.svg)](https://pypi.org/project/ace-git-copilot/)
[![License: MIT](https://img.shields.io/github/license/jachinsamuel/Ace.svg)](https://opensource.org/licenses/MIT)
[![GitHub Stars](https://img.shields.io/github/stars/jachinsamuel/Ace.svg)](https://github.com/jachinsamuel/Ace/stargazers)
[![GitHub Forks](https://img.shields.io/github/forks/jachinsamuel/Ace.svg)](https://github.com/jachinsamuel/Ace/network/members)
[![GitHub Issues](https://img.shields.io/github/issues/jachinsamuel/Ace.svg)](https://github.com/jachinsamuel/Ace/issues)

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.

![Ace CLI in action](media/cli_in_action.svg)

---

## Features

*   **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 dash` to launch a terminal interface showing current status, branch info, workspace repository listings, and interactive menus.
*   **Repository Health Diagnostics**: Run `ace doctor` to run repository health checks (detached heads, locks, large files) and generate step-by-step AI recovery advice.
*   **Smart Git Hooks**: Run `ace hook install` to register pre-commit code review checks and prepare-commit-msg message drafting.
*   **AI Auto-Squashing & Rebasing**: Run `ace squash` to 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.

---

## Installation

### Option A: Install via standard pip (Recommended)
You can install Ace globally using standard pip:
```bash
pip install ace-git-copilot
```
*Note: If you run into a `command not found` error, you can bypass your system PATH and run the tool directly through Python module execution:*
```bash
python -m ace dash
```

### Option B: Install via pipx (Alternative)
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.

1. Install pipx and configure your system PATH (only needs to be done once):
   ```bash
   pip install pipx
   pipx ensurepath
   ```
   *(Note: If `pipx ensurepath` modified your path, close your current terminal window and open a new one to apply).*

2. Install Ace:
   ```bash
   pipx install ace-git-copilot
   ```

3. Run it directly:
   ```bash
   ace dash
   ```

---

## Configuration and Setup

Run the built-in configuration wizard to select your AI model provider:
```bash
ace setup
```
Ace saves your configuration file to `~/.ace/config.toml`. It supports the following AI model providers:

### 1. Ollama (Local Models)
For a 100% private, offline, and free experience.
* Ensure [Ollama](https://ollama.com/) 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.

### 2. NVIDIA NIM API (Cloud)
Uses cloud-hosted high-performance models.
* You will need an NVIDIA developer API key. Get one for free at [NVIDIA build](https://build.nvidia.com/).
* Default model: `meta/llama-3.3-70b-instruct`

### 3. OpenAI
Uses OpenAI GPT models.
* You will need an OpenAI API key.
* Default model: `gpt-4o-mini`

### 4. Anthropic
Uses Anthropic Claude models.
* You will need an Anthropic API key.
* Default model: `claude-3-5-sonnet-latest`

### 5. Custom OpenAI-Compatible
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`

---

## Usage

### Natural Language Mode

You can speak to Git in plain English. There is no need to use double quotes — simply write your request directly:
```bash
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
```
*(Double quotes are optional, e.g. `ace "stage everything and commit"`).*

### Command-Line Toolchain
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 standup` | — | Generate a professional daily standup update based on your recent commits. |
| `ace blame <file> <line>` | — | AI-powered Git blame: analyze who wrote a line and explain WHY they wrote it. |
| `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 alias <action>` | — | Manage custom command shortcuts (e.g. `ace alias add ship "git add . && ace commit -y"`). |
| `ace undo` | — | Safely revert the last action after checking repository status. |
| `ace workspace` | `ace ws` | Monitor status of multiple repositories and navigate between them. |
| `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. |

---

## Interactive Terminal Dashboard (TUI)

Launch the repository dashboard by running:
```bash
ace dash
```

![Ace TUI Dashboard](media/dashboard.svg)

The 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.

---

## Repository Statistics (`ace stats`)

View beautiful contributor graphs, commit frequency charts, and file extension breakdowns:

![Ace Stats](media/stats.svg)

## License

Distributed under the MIT License. See [LICENSE](LICENSE) for more details.
