Metadata-Version: 2.4
Name: gitrama
Version: 1.3.0
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
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 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

```bash
pip install gitrama
```

Or with uv:

```bash
uv pip install gitrama
```

Then authenticate:

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

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

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

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

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.

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

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

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.

```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`** — 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
```

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

---

## License

Proprietary — © 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)

🌿
