gitrama 1.3.0

AI-powered Git workflow automation — smarter commits, branches, PRs, and repo chat

🌿 Gitrama

Git intelligence for developers who care about code health.

Gitrama is a Git intelligence CLI that tells you who owns what, what's fragile, what changed, and why. It surfaces your repo's Stability Index, runs AI-powered code review on staged diffs, and lets you ask plain-language questions about your codebase — all from the terminal.

Works with any AI provider — Anthropic, OpenAI, or local models via Ollama.

---

Install

pip install gitrama

Or with uv:

uv pip install gitrama

Then authenticate:

gtr setup

---

Commands

Intelligence

Command	Description
gtr scan	Run a full repo scan — Stability Index, signal breakdown, fragile modules
gtr review	AI code review of staged or uncommitted changes
gtr diff	Risk-annotated diff with coupling gap analysis
gtr chat	Ask anything about your repo in natural language

Git Workflow

Command	Description
gtr commit	Generate an AI-powered commit message for staged changes
gtr unstage	Interactive file unstager
gtr pr	Generate a PR description from your branch diff
gtr changelog	Generate a changelog between two refs
gtr branch	Create a branch with AI-suggested naming

Streams

Command	Description
gtr stream status	Show the current workflow stream
gtr stream switch <name>	Switch to a stream (creates if new)
gtr stream list	List all streams in the repo

Account

Command	Description
gtr account	Show plan, usage, trial status, and token
gtr setup	Configure API key and AI provider

---

Quick Start

# 1. Scan your repo — get your Stability Index
gtr scan

# 2. Review staged changes before committing
git add src/auth/session.py
gtr review

# 3. Generate a commit message
gtr commit

# 4. Ask about your codebase
gtr chat "who owns the payment module?"
gtr chat "what's the riskiest file right now?"
gtr chat "what changed in the last 3 days?"

---

gtr scan

Runs a full analysis of your repository and produces a Stability Index — a 0–100 score reflecting how maintainable and sustainable your codebase is over time.

gtr scan
gtr scan --html          # open results in browser

Output includes:

• Stability Index score with trend delta
• Three core signals: Churn Rate, Review Coverage, Coupling Gap
• Fragile modules — ranked by risk with per-file breakdown
• Top contributors by change volume
• Scan history with score progression

The scan reads commit metadata, file trees, and blame data. No source code is sent anywhere. See gitrama.ai/methodology for full transparency.

---

gtr review

AI-powered code review of your changes. Analyzes diffs against your repo's history and flags security issues, logic errors, coupling problems, and style concerns.

gtr review                  # review staged changes (default)
gtr review --uncommitted    # include unstaged changes
gtr review --quick          # fast scan, top issues only
gtr review --full           # full repo context, deepest analysis
gtr review --html           # open annotated results in browser

Review output includes inline annotations, severity levels (critical / warning / style), and an Ask G.I.T. entry point for each finding.

---

gtr diff

Risk-ranked diff view with coupling gap annotations — shows which changes are high-risk and why.

gtr diff                    # diff of staged changes
gtr diff --html             # open annotated panel in browser

---

gtr chat

Ask plain-language questions about your repository. Gitrama analyzes commit history, file structure, blame data, and diffs to answer.

gtr chat "who owns the auth module?"
gtr chat "when did we last change the payment logic?"
gtr chat "what's the riskiest file in this repo?"
gtr chat "summarize what happened on this branch"
gtr chat "explain the purpose of src/utils/retry.py"
gtr chat --deep "full history of the session module"

The --deep flag enables full repo history access for more thorough answers on complex questions.

---

gtr commit

Generates a high-quality commit message from your staged diff. Requires files to be staged first.

git add .
gtr commit                              # conventional format (default)
gtr commit --type detailed             # expanded message with body
gtr commit --type simple               # one-line message
gtr commit --context "fixing auth bug" # guide the AI with context

---

gtr pr

Generates a comprehensive PR description from the diff between your current branch and the base.

gtr pr                      # diff against main/master
gtr pr --base develop       # diff against a specific base branch

---

gtr changelog

Generates a human-readable changelog from commit history, grouped by type.

gtr changelog                       # since last tag
gtr changelog --since v1.0.0        # from a specific tag
gtr changelog --since v1.0.0 --until v1.3.0
gtr changelog --format json         # machine-readable output

---

Streams

Streams are Gitrama's workflow context layer. They track what you're working on and sharpen AI suggestions across all commands.

gtr stream status                          # show active stream
gtr stream switch auth-refactor            # switch or create a stream
gtr stream switch payment-v2 --description "rebuilding charge flow"
gtr stream list                            # list all streams

When a stream is active, gtr review and gtr chat use it as additional context — producing more relevant output for your current task.

---

AI Provider Configuration

Gitrama works with Anthropic, OpenAI, and local models via Ollama.

# Interactive setup (recommended)
gtr setup

# Set provider manually
gtr setup --provider anthropic    # default
gtr setup --provider openai
gtr setup --provider ollama

# Override model for a single command
gtr commit --model gpt-4o
gtr review --model claude-opus-4-6
gtr chat --model ollama/llama3

---

What Data Leaves Your Machine

gtr scan — sends commit metadata (author, timestamp, message, file paths, line counts), file tree paths, repo name, and branch name. No source code.

gtr review, gtr diff, gtr commit, gtr chat, gtr pr, gtr changelog — sends the staged diff and relevant context to your configured AI provider (Anthropic, OpenAI, or your local Ollama instance). Gitrama does not store this data. Your source code goes directly to your AI provider under your own API key.

Full details: gitrama.ai/methodology

---

MCP Integration

Use Gitrama directly inside Cursor, Claude Desktop, VS Code, Windsurf, and Zed via the MCP server:

pip install gitrama-mcp

See gitrama-mcp on PyPI or github.com/GitramaLLC/gitrama-mcp.

---

Docker

# Run gtr scan on the current directory
docker run --rm -v $(pwd):/repo -w /repo ghcr.io/gitramallc/gitrama:latest scan

# Add as a shell alias for seamless use
alias gtr='docker run --rm -v $(pwd):/repo -w /repo ghcr.io/gitramallc/gitrama:latest'

---

Account & Billing

gtr account          # show plan, usage bar, trial status

Trial — 14 days, full access, no credit card required.
Free — 50 requests/day after trial.
Pro — unlimited, $12/month. Upgrade at gitrama.ai/upgrade.

---

License

Proprietary — © Gitrama LLC. All rights reserved.
Free to use under the terms of your Gitrama subscription.

---

Built by Gitrama LLC · gitrama.ai · [e-mail]

🌿