A convenient TUI for managing git repositories with interactive menus.

📚 Read the full documentation

Git Maestro observes the current state of your git repository, both local and remote, and presents you with context-aware actions to help you quickly set up and manage your projects. No more typing countless git commands and switching in and out of the browser - just select from a beautiful menu and let Git Maestro handle the rest!

• 🎯 Context-Aware Actions: Only shows actions that are relevant to your current repository state
• 🎨 Beautiful CLI Interface: Built with Rich and Prompt Toolkit for a polished user experience
• 🔧 Modular Design: Easy to extend with new actions
• ⚡ Fast Setup: Quickly initialize repos, add READMEs, .gitignore files, and remote repositories
• 🎭 Works as Git Plugin: Can be called as git maestro after installation
• 🔌 MCP Integration: Seamlessly works with Model Context Protocol for AI-powered workflows

pip install git-maestro

# Clone the repository
git clone https://github.com/benhuckvale/git-maestro.git
cd git-maestro

# Install with PDM
pdm install

# Run in development mode
pdm run git-maestro

After installation, you can run git-maestro from anywhere, or use it as a git plugin with git maestro.

📖 Installation Guide

Simply navigate to any directory and run:

git-maestro

Or use it as a git plugin:

git maestro

Git Maestro will:

1. Detect the current state of the directory
2. Show you what's configured and what's missing
3. Present a menu of applicable actions
4. Execute your selected action
5. Refresh and show updated options

📖 Quick Start Guide

• Initialize Git Repository 🎬: Run git init in a non-git directory
• Add README.md 📝: Create a README with basic project structure
• Add .gitignore 🚫: Add a .gitignore file with templates for Python, Node.js, or Generic projects
• Setup Remote Repository 🌐: Configure GitHub or GitLab as your remote origin

Git Maestro runs as a Model Context Protocol (MCP) stdio server, enabling AI assistants (like Claude) to access git and GitHub Actions data outside their sandboxes.

AI assistants can now autonomously:

• Monitor CI/CD: Check GitHub Actions job status without downloading full logs
• Debug Failures: Fetch job logs and analyze test failures
• Create Closed Loops: Make code fixes, push commits, and monitor new CI runs until tests pass
• Understand Pipeline Complexity: See job dependencies and understand which failures are root causes vs cascading

# Start the MCP server
git-maestro mcp

An AI assistant can then:

1. Make code changes and push them
2. Poll check_github_actions_job_status() to wait for CI to complete
3. Fetch failing job logs with download_github_actions_job_logs()
4. Analyze failures and make targeted fixes
5. Loop until all tests pass—without any human intervention

• list_github_actions_runs(count) - Get recent workflow runs
• get_github_actions_run_jobs(run_id) - View job structure and details
• check_github_actions_job_status(run_id, [job_id]) - Lightweight polling (fast status checks)
• download_github_actions_job_logs(run_id, job_id) - Fetch logs for specific jobs
• download_job_traces() - Download all failed job logs from the latest run

Add to your Claude Code mcp.json:

{
  "mcpServers": {
    "git-maestro": {
      "command": "git-maestro",
      "args": ["mcp", "--github"]
    }
  }
}

Use --github, --azure, or --gitlab flags to enable only the platforms you need. This reduces the number of tools exposed, saving context window tokens. Omit all flags to enable all platforms.

📖 Full MCP Documentation

• Python >= 3.9
• Git installed on your system
• Dependencies (automatically installed):
  • rich >= 13.7.0
  • prompt-toolkit >= 3.0.43
  • gitpython >= 3.1.40

# Install with dev dependencies
pdm install -d

# Run tests
pdm run pytest

# Run tests with verbose output
pdm run pytest -v

# Run tests with coverage
pdm run pytest --cov=git_maestro

# Format code
pdm run black .

# Lint
pdm run ruff check .

Git Maestro has a comprehensive test suite with 28+ tests covering:

• Repository state detection
• SSH configuration detection
• Action applicability logic
• CLI functionality

See tests/README.md for more details.

Git Maestro stores tokens in ~/.config/git-maestro/tokens.conf (outside the repository). The .gitignore file blocks common sensitive patterns (*.token, .env, credentials.json, etc.). Unit tests use mocks and don't require real tokens.

To add a new action:

1. Create a new file in git_maestro/actions/ (e.g., your_action.py)
2. Inherit from the Action base class
3. Implement is_applicable() and execute() methods
4. Add your action to git_maestro/actions/__init__.py
5. Register it in git_maestro/cli.py in the get_all_actions() function

Example:

from .base import Action
from git_maestro.state import RepoState

class YourAction(Action):
    def __init__(self):
        super().__init__()
        self.name = "Your Action Name"
        self.description = "What your action does"
        self.emoji = "🎯"

    def is_applicable(self, state: RepoState) -> bool:
        # Return True if this action should be shown
        return state.is_git_repo

    def execute(self, state: RepoState) -> bool:
        # Perform your action
        # Return True if successful
        return True

MIT

Contributions are welcome! Please feel free to submit a Pull Request in accordance with the contributing guidelines.

Works with GitHub.