GitSpectre

A production-ready, cross-platform CLI tool that uses AI to interpret natural language Git commands, answer questions, execute operations, and handle complex code modifications with intelligent conflict resolution.

Prerequisites

• Python 3.6 or higher
• pip (Python package installer, comes with Python)
• Git repository (for most operations)

Installation

Option 1: Local Installation (Recommended for Development)

1. Clone the repository:

   git clone https://github.com/predat-r/GitSpectre.git
   cd GitSpectre
   

2. Install locally:

   pip install -e .
   

   This installs the package in development mode, allowing you to modify the code.

Option 2: Global Installation

1. Install directly from GitHub:

   pip install git+https://github.com/yourusername/GitSpectre.git
   

   Or if you have the code locally:

   pip install .
   

   This makes spectre available system-wide.

Cross-Platform Notes

The installation works identically on:

• Windows: Use Command Prompt, PowerShell, or Git Bash
• macOS: Use Terminal or iTerm
• Linux: Use your preferred terminal

Setup

You can use either OpenRouter (free options available) or Anthropic (Claude) as the AI provider.

Option 1: OpenRouter (Default - Free Options Available)

1. Get an API Key:

   • Visit OpenRouter.ai
   • Sign up and get your API key
   • This powers the AI functionality with various free models

2. Configure GitSpectre:

   spectre config set api_key your_openrouter_api_key_here
   

Option 2: Anthropic (Claude)

1. Get an API Key:

   • Visit Anthropic Console
   • Sign up and get your API key
   • Provides full access to Claude models

2. Configure GitSpectre:

   spectre --config
   

   Select option 4 to set provider to "anthropic", then option 1 to set your Anthropic API key.

Continue Setup

3. Navigate to a Git Repository:

   cd /path/to/your/git/repo
   

4. Run Commands:

   spectre your natural language command
   

   For help: spectre --help

Features

Core AI Capabilities

• Natural Language Git Commands: Execute complex Git workflows using plain English (e.g., "push my code but resolve any conflicts first")
• Intelligent Code Analysis: Reads, modifies, and validates code files with syntax checking
• Conversational Interface: Ask questions about Git, get explanations, and receive guidance

Advanced Git Operations

• Repository Management: Init, clone, status, branches, commits, merges, diffs
• Conflict Resolution: Automatic detection, analysis, and resolution with user options (keep ours/theirs/merge)
• Stashing & Tagging: Full support for Git stashing, tagging, and advanced operations
• Remote Operations: Push, pull, fetch with conflict handling
• History & Logs: Commit history, blame, log analysis

Code Modification Tools

• File Operations: Read, write, search-replace files with path validation
• Syntax Validation: Python AST parsing for code safety
• Diff Analysis: Intelligent conflict diffing and resolution suggestions

Configuration & Security

• Git Config Management: Set user.name, user.email, and other Git configs
• API Key Management: Secure storage of OpenRouter API keys
• Path Validation: Ensures all operations stay within repository boundaries
• Command Sanitization: Prevents dangerous shell commands

User Experience

• Verbose Mode: --verbose flag shows tool calls, commands, and internal processing
• Colored Output: Syntax highlighting for code, status colors for operations
• Progress Indicators: Spinners and status updates during long operations
• Error Handling: Comprehensive error messages and recovery suggestions
• Async Processing: Non-blocking operations for better responsiveness

Technical Features

• Modular Architecture: Clean separation of CLI, agent, and tools
• Async/Await: Full async support for API calls and long-running tasks
• Logging: Configurable logging levels with file output
• Cross-Platform: Works identically on Windows, macOS, Linux
• Extensible: Plugin-like tool system for adding new capabilities

Installation

Prerequisites

• Python 3.6+
• Git repository (for Git operations)
• OpenRouter or Anthropic API key (for AI functionality)

Install from Source

git clone https://github.com/yourusername/GitSpectre.git
cd GitSpectre
pip install -e .

Get API Key

OpenRouter (default, free options):

1. Visit OpenRouter.ai
2. Sign up and get your API key
3. Set it: spectre config set api_key your_key_here

Anthropic (Claude):

1. Visit Anthropic Console
2. Sign up and get your API key
3. Set it: spectre --config and follow the prompts

Usage

Command Line Options

spectre --help                    # Show help
spectre --verbose <command>       # Show detailed tool calls and processing
spectre config set <key> <value>  # Set configuration
spectre config get <key>          # Get configuration
spectre <natural language>        # Execute AI-powered Git commands

Examples

Basic Git Operations

spectre commit my changes with message 'update readme'
spectre create a new branch called feature-x
spectre merge main into current branch
spectre push my changes to origin
spectre what is my current branch?
spectre show me the status

Conflict Resolution

spectre push my code  # Detects conflicts and explains them
spectre resolve conflicts in my files  # Interactive resolution
spectre merge feature-branch  # Handles conflicts automatically

Code Operations

spectre read the main.py file
spectre search for 'TODO' in all files
spectre validate syntax of utils.py
spectre show diff between branches

Configuration

# OpenRouter (default)
spectre config set api_key your_openrouter_key

# Anthropic - use interactive config
spectre --config

# Set Git config
spectre config set user.name "Your Name"
spectre config set user.email "your.email@example.com"

Advanced Operations

spectre stash my changes with message 'work in progress'
spectre create a tag v1.0 with message 'Release version 1.0'
spectre show diff between HEAD and HEAD~3
spectre reset files to last commit
spectre what changed in the last commit?

Architecture

Core Components

• CLI Layer (cli.py): Click-based command interface
• Agent Layer (agent.py): OpenRouter AI integration with tool calling
• Tool Layer (tools/): Modular Git and file operation functions
• Config Layer (config.py): Settings and API key management
• Utils Layer (utils.py): Logging, validation, formatting

Tool System

GitSpectre uses a comprehensive tool-calling system with 31+ tools:

Git Tools (22 tools)

• Repository: get_repo_status, init_repo, clone_repo
• Branches: get_branches, switch_branch, create_branch
• Commits: create_commit, get_commit_history, amend_commit
• Merging: merge_branch, detect_conflicts, resolve_conflicts, abort_merge
• Remotes: push_changes, pull_changes
• Advanced: stash_changes, apply_stash, create_tag, reset_files, get_diff

File Tools (6 tools)

• Operations: read_file, write_file, search_replace
• Analysis: validate_code, analyze_conflicts, apply_conflict_resolution, get_file_info

Utility Tools (3 tools)

• Config: get_git_config_tool, set_git_config_tool, list_git_configs

AI Integration

GitSpectre supports two AI providers:

OpenRouter (Default)

• Models: GPT-4o-mini, Claude 3.5 Sonnet, and many others
• Many free models available
• Use: spectre config set api_key your_openrouter_key

Anthropic (Claude)

• Models: Claude Sonnet 4, Claude Opus 4, Claude 3.5

• Full access to Claude models

• Use: spectre --config to set provider and API key

• Tool Calling: Function calling for programmatic Git/file operations

• Context Awareness: Repository state passed to AI for informed decisions

• Safety: Command validation and path restrictions

Development

Project Structure

gitspectre/
├── __init__.py
├── main.py          # Entry point
├── cli.py           # Command-line interface
├── agent.py         # AI agent and tool calling
├── config.py        # Configuration management
├── utils.py         # Utilities and logging
├── prompts.json     # AI system prompts
└── tools/
    ├── git_tools.py     # Git operations
    ├── file_tools.py    # File operations
    └── utility_tools.py # Configuration tools

Adding New Tools

1. Create function in appropriate tools/*.py file
2. Add tool schema to *_TOOLS list
3. Update ALL_TOOLS in agent.py
4. Test with verbose mode

Testing

# Run with verbose output
spectre --verbose "test command"

# Check logs
tail ~/.gitspectre/gitspectre.log

Contributing

1. Fork the repository
2. Create a feature branch
3. Add tests for new functionality
4. Ensure verbose mode works for debugging
5. Submit a pull request

Publishing & Distribution

GitSpectre can be installed via multiple package managers:

PyPI (pip)

Automatic Publishing: Releases are automatically published to PyPI via GitHub Actions.

Manual Installation:

pip install gitspectre

Homebrew (macOS/Linux)

Automatic Updates: Homebrew formulas are automatically updated via GitHub Actions when new releases are published.

Installation:

brew install gitspectre

Manual Formula: The Homebrew formula is maintained in the gitspectre.rb file in this repository.

Development Installation

For contributors and developers:

# Clone and install in development mode
git clone https://github.com/predat-r/GitSpectre.git
cd GitSpectre
pip install -e .

CI/CD Workflows

This project uses GitHub Actions for automated publishing:

• .github/workflows/publish-pypi.yml: Builds and publishes to PyPI on release
• .github/workflows/update-homebrew.yml: Updates Homebrew formula on release

Release Process

1. Create a new release on GitHub with a version tag (e.g., v0.1.1)
2. GitHub Actions automatically:
   • Builds the Python package
   • Publishes to PyPI
   • Updates the Homebrew formula
3. Users can install the new version via pip install --upgrade gitspectre or brew upgrade gitspectre

License

MIT License - see LICENSE file for details.

Changelog

v0.1.0 (Current)

• Complete rewrite with modular architecture
• 31+ AI-powered tools for Git and file operations
• Intelligent conflict resolution
• Async processing and robust error handling
• Verbose mode for debugging
• Production-ready code with comprehensive documentation