gitrama 1.5.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's about to break, and why. It surfaces your repo's Stability Index, forecasts failure hotspots before they happen, 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, Grok, Gemini, or local models via Ollama.

---

Install

pip install gitrama

Or with uv:

uv pip install gitrama

Then authenticate:

gtr setup

No token? No problem. Run up to 5 free requests before signing up.

---

Commands

Intelligence

Command	Description
gtr scan	Run a full repo scan — Stability Index, signal breakdown, fragile modules
gtr predict	Forecast failure hotspots from commit patterns — timestamped, verifiable
gtr watch	Monitor predicted high-risk files for new commits — alerts when one lands
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
gtr summary	Quick summary of staged changes

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
gtr stream finish	Merge current stream into default branch

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. Forecast failure hotspots before they happen
gtr predict

# 3. Monitor predicted files for new commits
gtr watch

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

# 5. Generate a commit message
gtr commit

# 6. Ask about your codebase
gtr chat "who owns the payment module?"
gtr chat "what's the riskiest file right now?"
gtr chat --deep "as a new CTO, what are my top risks?"

---

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 --verbose      # show affected modules per signal
gtr scan --format json  # machine-readable output

Three structural decay signals:

• Continuity Risk — inactive ownership, bus factor, knowledge concentration
• Boundary Entropy — cross-module coupling, architecture drift
• Recurrence Risk — hotfix patterns, revert frequency, recurring failures

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

---

gtr predict

Analyzes commit history to forecast which files are most likely to experience incidents in the next N days. Four signals combined into a prediction score — no AI guessing, pure deterministic math on commit patterns.

gtr predict                    # forecast next 90 days (default)
gtr predict --horizon 30       # tighter 30-day window
gtr predict --format json      # machine-readable output
gtr predict --no-save          # don't persist to disk

Four prediction signals:

• Recurrence velocity — is patch frequency accelerating?
• Churn concentration — who owns this file, and are they still active?
• Coupling exposure — risk propagation from co-changed files
• Decay trajectory — is the fix commit ratio rising over time?

Every prediction gets a timestamped ID (pred_YYYYMMDD_xxxxxx) saved to ~/.gitrama/predictions.json. Run gtr predict on a public repo, post the ID publicly, and you have a verifiable record. When an incident hits a predicted file — the timestamp proves you called it.

gtr predict

  RANK  LEVEL       FILE                           SCORE   HORIZON    SIGNAL
  ─────────────────────────────────────────────────────────────────────────────
  1     🔴 CRITICAL  ssl/ssl_lib.c                  94      ~23 days   recurrence ↑↑ + coupling
  2     🟠 HIGH      crypto/x509/x509_vfy.c         87      ~41 days   churn accel + ownership gap
  3     🟡 MEDIUM    providers/fips/fipsprov.c      79      ~67 days   single owner inactive 34d

  Prediction ID: pred_20260331_a4f2c1
  Timestamp:     2026-03-31T16:42:00Z

---

gtr watch

Monitors the files flagged by gtr predict and fires an alert the moment any of them are touched. Closes the prediction loop.

gtr watch                   # monitor continuously (Ctrl+C to stop)
gtr watch --once            # check once and exit
gtr watch --interval 60     # poll every 60 seconds (default: 300)

Reads from .gitrama/last_predict.json written by gtr predict. Falls back to last_scan.json fragile modules if no prediction exists. All alerts are logged to ~/.gitrama/alerts.json.

The closed loop:

gtr predict   # → flags ssl_lib.c at 94% risk, saves pred_20260331_a4f2c1
gtr watch     # → monitoring ssl_lib.c, x509_vfy.c, fipsprov.c

# 23 days later:
# ⚠  BREACH ALERT — ssl_lib.c touched
# Commit: e6e01f00 — "fix null pointer dereference"
# This file was flagged CRITICAL by your last prediction.
# Run gtr scan to update your risk assessment.

---

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"
gtr chat --deep "as a new CTO, what are my top risks?"

The --deep flag enables full repo history access for CTO-level briefings and architectural analysis.

---

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.5.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
gtr stream finish                          # merge stream → default branch (auto-detects)
gtr stream finish main                     # merge stream → main explicitly

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

---

Free Tier

No token required to get started. Run up to 5 free requests across gtr chat, gtr scan, and gtr ask before signing up.

pip install gitrama
gtr chat "what's the riskiest file in this repo?"   # request 1 of 5

When you're ready:

gtr setup   # or: gtr config set gitrama_token YOUR_TOKEN

Get your free token at gitrama.ai.

---

AI Provider Configuration

Gitrama works with Anthropic, OpenAI, Grok, Gemini, 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 and gtr predict — 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

Free — 5 requests before token required. Trial — 14 days, full access, no credit card required. Pro — unlimited, $19/month. Upgrade at gitrama.ai/upgrade.

---

License

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

---

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

🌿