giton

AI Cost Tracking

PyPI Version Python License AI Cost Human Time Model

Generated on 2026-05-27 using openrouter/qwen/qwen3-coder-next

giton is a local AI layer for Git that works between commit and push. It helps standardize commits, propose safe code fixes, and orchestrate external tools via plugins.

Does something like this already exist?

Partially: there are tools for AI commit messages, git hooks, and commit-history rewriting. What is still missing is one local operator that:

Proposed direction for giton

  1. Local-first with safe defaults
    • AI proposes changes, user approves them.
    • Prefer fixup! commits over automatic history rewriting.
  2. Git hook layer
    • pre-commit: policy validation and quick fixes.
    • post-commit: inspect the fresh commit and propose follow-up patches.
    • pre-push: standardize history (autosquash, commit naming, final checks).
  3. Plugin architecture
    • Shared input/output contract (JSON schema).
    • Plugin adapters: MCP, REST, CLI shell, gRPC/protobuf.

MVP usage example

After giton init, hooks are installed and run automatically from Git lifecycle events. The commands below show equivalent manual execution for demonstration/debugging.

# 1) initialize hooks in the repository
giton init

# 2) user makes a normal commit
git add -p
git commit -m "update stuff"

# 3) equivalent manual run: post-commit hook logic
giton hook post-commit

# 4) equivalent manual run: pre-push hook logic
giton hook pre-push

Example interaction:

giton: Found 2 issues (example: null check, commit message policy).
giton: Apply patch and add commit "fixup! ..."? [Y/n]

MVP plan

Install

pip install giton

Development

Setup

# Clone the repository
git clone <repo-url>
cd gix

# Install in development mode
pip install -e .[dev]

Dependencies

Runtime:

Development:

Testing

# Run all tests
pytest

# Run specific test file
pytest tests/test_history.py

# Run with coverage
pytest --cov=src/giton

Environment Variables

Create a .env file in the project root (see .env.example):

Variable Default Description
OPENROUTER_API_KEY (not set) Required: OpenRouter API key (https://openrouter.ai/keys)
LLM_MODEL openrouter/qwen/qwen3-coder-next Model to use for AI operations
PFIX_AUTO_APPLY true Automatically apply fixes without asking
PFIX_AUTO_INSTALL_DEPS true Automatically pip/uv install dependencies
PFIX_AUTO_RESTART false Restart process after fix using os.execv
PFIX_MAX_RETRIES 3 Maximum retry attempts
PFIX_DRY_RUN false Run in dry-run mode without making changes
PFIX_ENABLED true Enable automatic fixing
PFIX_GIT_COMMIT false Automatically commit fixes
PFIX_GIT_PREFIX pfix: Commit message prefix for fixes
PFIX_CREATE_BACKUPS false Create backups in .pfix_backups/ directory

Project Structure

gix/
├── src/giton/           # Main source code
│   ├── __init__.py      # Package initialization
│   ├── __main__.py      # Entry point for `python -m giton`
│   ├── catalog.py       # Plugin catalog management
│   ├── cli.py           # Command-line interface (Typer)
│   ├── config.py        # User plugin configuration
│   ├── context.py       # Git context collection
│   ├── history.py       # Safe history operations (fixup, autosquash)
│   ├── hooks.py         # Git hook installation
│   ├── interactive.py   # Interactive prompts
│   ├── plugins.py       # Plugin installation/management
│   ├── policies.py      # Built-in policy engine
│   ├── repo_config.py   # Repository configuration
│   ├── runner.py        # Plugin execution runner
│   └── shell.py         # Interactive REPL shell
├── tests/               # Test suite
│   ├── test_basic.py    # Basic functionality tests
│   ├── test_history.py  # History operations tests
│   └── test_policies.py # Policy engine tests
├── examples/            # Usage examples
│   ├── basic/           # Basic library usage
│   ├── advanced/        # Advanced features demo
│   └── testing/         # CI/CD integration example
├── pyproject.toml       # Project configuration
├── README.md            # This file
├── SUMD.md              # System documentation (SUMD)
├── TODO.md              # Auto-generated TODO list
└── CHANGELOG.md         # Version history

Quick start

giton init                # install git hooks + 3 default plugins
giton shell               # interactive REPL
giton plugin catalog      # browse all available plugins
giton plugin install domd # install a specific extension
giton plugin install-category lang:python   # install everything for a language

Default plugins

The 3 plugins activated by giton init cover the most common day-to-day needs in a commit → push loop:

name category trigger role
pyqual lang:python pre-commit Python lint / type / complexity checks
vallm task:validate post-commit Validate AI-generated code/patches
pretest task:test pre-push Run / generate tests before push

Quick-extend categories

Each plugin in the catalog is tagged with a category, so you can install groups at once:

giton plugin install-category task:autofix

Interactive shell

$ giton shell
giton> help
giton> install-defaults
giton> hook pre-commit
giton> catalog
giton> install prefact

Built-in policies

giton ships with a small zero-dependency policy engine that runs on every hook trigger — even before any plugin is installed:

Inspect or customize them per repo:

giton policy list                    # show active policies
giton policy check -t pre-commit     # evaluate without running plugins
giton policy init                    # write .giton/config.yaml

.giton/config.yaml is a deep-merge over the defaults — disable a single check or tweak max_subject_length without restating everything:

policies:
  no_wip_commits:
    enabled: false
  conventional_commits:
    max_subject_length: 100
hooks:
  post-commit:
    fail_on_policy: true   # turn advisory checks into blocking

Plugin contract

A plugin is any executable command (CLI). The catalog entry declares its trigger, category, install target (PyPI/local path) and command template. The runner expands {paths}, {diff_file} and {root} placeholders with the current git context before invocation.

Future exec types (mcp, rest) will share the same JSON in/out contract: input = git context + policy findings, output = list of proposed actions (patches, fixup commits, warnings).

Examples

The examples/ directory contains working demonstrations of giton:

Running examples with Docker

All examples include Dockerfiles for containerized execution:

# Basic example
docker build -f examples/basic/Dockerfile -t giton-example-basic .
docker run --rm -v $(pwd)/examples/basic/logs:/app/logs giton-example-basic

# Advanced example
docker build -f examples/advanced/Dockerfile -t giton-example-advanced .
docker run --rm -v $(pwd)/examples/advanced/logs:/app/logs giton-example-advanced

# Testing example
docker build -f examples/testing/Dockerfile -t giton-test .
docker run --rm -v $(pwd)/examples/testing/logs:/app/logs giton-test

See each example’s README.md for detailed usage instructions.

License

Licensed under Apache-2.0.

This site is open source. Improve this page.