giton 0.1.12

Local AI layer for git: orchestrates policies & plugins between commit and push.

giton

AI Cost Tracking

• 🤖 LLM usage: $1.5328 (13 commits)
• 👤 Human dev: ~$466 (4.7h @ $100/h, 30min dedup)

Generated on 2026-05-31 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:

• interacts with the user right after commit,
• proposes code fixes as additional commits (fixup!),
• cleans up history before push,
• integrates plugins via MCP/REST/CLI/gRPC.

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

• MVP 1: hooks + policy engine + interactive CLI
• MVP 2: patching + fixup workflow + pre-push autosquash
• MVP 3: stable plugin API and MCP/REST/CLI/gRPC integrations

Install

pip install giton

Development

Setup

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

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

Dependencies

Runtime:

• typer>=0.12
• rich>=13.7
• PyYAML>=6.0

Development:

• pytest>=8.0
• goal>=2.1.0
• costs>=0.1.20
• pfix>=0.1.60

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

giton/
├── 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

Use Cases

1. Standardizing Commit Messages

Giton automatically validates commit messages against Conventional Commits spec:

# ❌ Blocked - doesn't follow conventional commits
git commit -m "fix bug"

# ✅ Allowed - follows conventional commits
git commit -m "fix(auth): handle null session token"

2. Preventing Secrets in Code

Giton scans staged files for sensitive data before commit:

# ❌ Blocked - AWS key detected
git add config.py
git commit -m "add config"
# giton: Found AWS key in config.py:4

3. Code Quality Gates

Automatically run linting and type checking before commits:

# With pyqual plugin installed
git commit -m "feat: add feature"
# giton: Running pyqual gates...
# giton: Type errors found in src/main.py:15

4. Safe History Cleanup

Use fixup commits and autosquash to clean up history before push:

# Create a fixup commit
giton fixup --target HEAD~1

# Clean up history before push
giton history clean --base main

5. Pre-push Validation

Run tests and generate test coverage before pushing:

# With testless plugin installed
git push origin feature-branch
# giton: Running testless scan...
# giton: All tests passed (42/42)

Getting Started

Step 1: Install

pip install giton

Step 2: Initialize in Your Repository

cd your-project
giton init

This installs git hooks and default plugins (pyqual, vallm, testless).

Step 3: Configure (Optional)

Create .giton/config.yaml to customize policies:

policies:
  conventional_commits:
    max_subject_length: 100
  no_wip_commits:
    enabled: false  # allow WIP commits during development
hooks:
  pre-commit:
    fail_on_policy: true

Step 4: Start Working

# Work as usual - giton will check automatically
git add .
git commit -m "feat: add new feature"

# Check status
giton status

# View available plugins
giton plugin catalog

# Install additional plugins
giton plugin install mypy

Daily Workflow

A typical development day with giton:

# Morning: start working
git checkout -b feature/new-api

# During development: commit frequently
git add src/api.py
git commit -m "wip: add endpoint"  # blocked by no_wip_commits policy
git commit -m "feat(api): add endpoint"  # allowed

# After review: fix issues
git add src/api.py
giton fixup --target HEAD~1  # create fixup commit

# Before push: clean up history
giton history clean --base main

# Push
git push origin feature/new-api

Working with Multiple Plugins

Giton supports installing and running multiple plugins across different triggers. Here's how to set up a comprehensive plugin ecosystem:

Install by Category

Install all plugins for a specific category at once:

# Install all Python-related plugins
giton plugin install-category lang:python

# Install all autofix plugins
giton plugin install-category task:autofix

# Install all security plugins
giton plugin install-category task:security

View Installed Plugins

giton plugin list

Output shows all plugins with their triggers and status:

┏━━━━━━━━━┳━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━┓
┃ name    ┃ category      ┃ triggers    ┃ command            ┃ status          ┃
┡━━━━━━━━━╇━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━┩
│ pyqual  │ lang:python   │ pre-commit  │ pyqual run         │ enabled / cmd:✓ │
│ prefact │ task:autofix  │ pre-commit  │ prefact scan       │ enabled / cmd:✓ │
│ vallm   │ task:validate │ post-commit │ vallm batch        │ enabled / cmd:✓ │
│ testless│ task:test     │ pre-push    │ testless scan      │ enabled / cmd:✓ │
└─────────┴───────────────┴─────────────┴────────────────────┴─────────────────┘

Multi-Plugin Workflow Example

With multiple plugins installed, giton runs them in sequence based on their triggers:

# 1. Pre-commit: pyqual + prefact run automatically
git add src/main.py
git commit -m "feat: add feature"
# → pyqual runs: checks code quality
# → prefact runs: scans for LLM-introduced issues
# → policies check: validates commit message

# 2. Post-commit: vallm + tagi run after commit
# → vallm runs: validates LLM-generated code
# → tagi runs: scans and groups uncommitted changes for next commits

# 3. Pre-push: testless runs before push
git push origin feature-branch
# → testless runs: scans tests and coverage

Commit Grouping with tagi

The tagi plugin provides automatic change grouping and commit orchestration:

# Install tagi for commit grouping
giton plugin install tagi

# After installation, tagi automatically scans changes on each commit
# and shows grouped analysis via post-commit hook

# Manual tagi commands:
tagi scan . --grouped        # Scan and group uncommitted changes
tagi list-groups .           # List available change groups
tagi send . small docs       # Send specific groups in order
tagi auto .                  # Auto-scan, order, commit and push

Install Additional Plugins

# Install specific plugins
giton plugin install domd          # Markdown linter
giton plugin install code2llm      # LLM context packer
giton plugin install tagi          # Commit grouping and orchestration
giton plugin install redsl         # Auto-fix lint issues
giton plugin install pfix          # Generic patch fixer
giton plugin install todocs        # Docs generator
giton plugin install prellm        # Pre-LLM security gate

Plugin Categories

Browse available plugins by category:

giton plugin catalog

Categories include:

• Languages: lang:python, lang:markdown, lang:any
• Tasks: task:validate, task:test, task:refactor, task:autofix, task:fix, task:docs, task:security
• Integrations: integration:mcp

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
testless	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:

• languages: lang:python, lang:markdown, lang:any
• tasks: task:validate, task:test, task:refactor, task:autofix, task:fix, task:docs, task:security
• integrations: integration:mcp

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:

• conventional_commits — subject must match type(scope)?: subject and stay within max_subject_length.
• no_wip_commits — blocks subjects matching wip, tmp, xxx, fixme.
• no_secrets — scans staged additions for AWS keys, private-key headers and api_key=/secret= patterns.
• max_file_size — rejects staged files larger than kb (default 512 KB).

Inspect or customize them per repo:

giton policy list                    # show active policies
giton policy check -t pre-commit     # evaluate without running plugins
giton policy fix                     # apply auto-fixes from the last check
giton policy init                    # write .giton/config.yaml

Policies that can be auto-fixed (e.g. conventional_commits, no_wip_commits) generate a git commit --amend -m "…" command. Run giton policy fix to apply it interactively, or pass --yes to skip the prompt.

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

• examples/basic - Basic usage example showing how to use giton as a Python library to collect git context, run triggers, and handle policy findings and plugin results. Can be run directly or with pytest.

• examples/advanced - Advanced usage example demonstrating plugin management (add, remove, list), custom policy configuration, hook installation/uninstallation, and running multiple triggers in sequence.

• examples/testing - Testing example with pytest integration and Docker support. Shows how to integrate giton into CI/CD pipelines with containerized testing environments. Includes Dockerfile and docker-compose.yml for easy setup.

• examples/plugins - Plugin lifecycle example. Demonstrates how to register a custom shell-script plugin in an isolated repo, execute it via giton hook pre-commit, and verify that placeholders ({paths}, {root}) are expanded and output is captured. Useful for authors who want to build their own plugins.

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.