Metadata-Version: 2.4
Name: gitrama
Version: 1.4.1
Summary: AI-powered Git workflow automation — smarter commits, branches, PRs, and repo chat
Home-page: https://gitrama.ai
Author: Alfonso Harding
Author-email: Alfonso Harding <contact@gitrama.ai>
License:  /*************************************************************************
         * 
         * GITRAMA CONFIDENTIAL
         * __________________
         * 
         *  [2026] - [PRESENT] Gitrama LLC
         *  All Rights Reserved.
         * 
         * NOTICE:  All information contained herein is, and remains
         * the property of Gitrama LLC and its suppliers,
         * if any.  The intellectual and technical concepts contained
         * herein are proprietary to Gitrama LLC
         * and its suppliers and may be covered by U.S. and Foreign Patents,
         * patents in process, and are protected by trade secret or copyright law.
         * Dissemination of this information or reproduction of this material
         * is strictly forbidden unless prior written permission is obtained
         * from Gitrama LLC.
         */
        
Project-URL: Homepage, https://gitrama.ai
Project-URL: Documentation, https://gitrama.ai/docs.html
Project-URL: Bug Reports, https://github.com/ahmaxdev/gitrama-cli/issues
Project-URL: Source, https://github.com/ahmaxdev/gitrama-cli
Project-URL: Changelog, https://github.com/ahmaxdev/gitrama-cli/releases
Keywords: git,ai,automation,cli,workflow,developer-tools,commit,branch,pull-request,productivity,openai,anthropic,llm,askgit
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Topic :: Software Development :: Version Control :: Git
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Utilities
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Operating System :: OS Independent
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX :: Linux
Classifier: Operating System :: MacOS
Classifier: Environment :: Console
Classifier: Natural Language :: English
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: typer>=0.9.0
Requires-Dist: rich>=13.0.0
Requires-Dist: requests>=2.31.0
Requires-Dist: pyperclip>=1.8.2
Requires-Dist: httpx>=0.27.0
Requires-Dist: annotated-doc>=0.0.4
Dynamic: author
Dynamic: home-page
Dynamic: license-file
Dynamic: requires-python

# 🌿 Gitrama

> Git intelligence for developers who care about code health.

[![PyPI](https://img.shields.io/pypi/v/gitrama)](https://pypi.org/project/gitrama/)
[![Python](https://img.shields.io/pypi/pyversions/gitrama)](https://pypi.org/project/gitrama/)
[![License](https://img.shields.io/badge/License-Proprietary-green.svg)](https://gitrama.ai)

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

```bash
pip install gitrama
```

Or with uv:

```bash
uv pip install gitrama
```

Then authenticate:

```bash
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

```bash
# 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.

```bash
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](https://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.

```bash
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.

```bash
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:**

```bash
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.

```bash
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.

```bash
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.

```bash
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.

```bash
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.

```bash
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.

```bash
gtr changelog                       # since last tag
gtr changelog --since v1.0.0        # from a specific tag
gtr changelog --since v1.0.0 --until v1.4.1
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.

```bash
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.

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

When you're ready:

```bash
gtr setup   # or: gtr config set gitrama_token YOUR_TOKEN
```

Get your free token at [gitrama.ai](https://gitrama.ai).

---

## AI Provider Configuration

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

```bash
# 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](https://gitrama.ai/methodology)

---

## MCP Integration

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

```bash
pip install gitrama-mcp
```

See [gitrama-mcp on PyPI](https://pypi.org/project/gitrama-mcp/) or [github.com/GitramaLLC/gitrama-mcp](https://github.com/GitramaLLC/gitrama-mcp).

---

## Docker

```bash
# 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

```bash
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](https://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](https://gitrama.ai) · [gitrama.ai](https://gitrama.ai) · [contact@gitrama.ai](mailto:contact@gitrama.ai)

🌿
