🧠 What is this?

the-git-historian (formerly git-standup-agent) is an AI agent that lives inside your git repository - defined using the gitagent open standard. It reads your commit history and turns raw git data into useful, human-readable intelligence.

What makes it different? While others just list commits, the Historian understands the vibe of your team and tracks lost thoughts in the reflog. Just paste any public GitHub URL at startup and the agent clones it, analyzes it, and lets you run all 12 commands on it - without ever leaving your terminal.

"Stop copying commit hashes into Slack. Let your repo speak for itself."

📚 Table of Contents

• What is this?
• Features
• Demo
• Screenshots
• Quick Start
• Commands
• How It Works
• Configuration
• Built With
• Contributing
• License

✨ Features

| Command | What it does | Output | |---|---|---| | vibe check 🧠 | Team morale & sentiment analysis | VIBE.md | | ghost hunter 👻 | Finds lost work via git reflog | GHOSTS.md | | standup | Daily standup from last 24hrs of commits | STANDUP.md | | weekly summary | 7-day digest grouped by type | WEEKLY.md | | roast me 🔥 | Brutally honest commit review | ROAST.md | | health report 📊 | Code health scan - TODOs, churn, debt | HEALTH.md | | suggest commits 🎯 | Rewrites bad commit messages | COMMIT-SUGGESTIONS.md | | share 📧 | Formats standup for Slack & email | SHARE.md | | pr summary 🔮 | Summarizes your changes as a PR description | PR-SUMMARY.md | | streak ⏰ | Tracks your commit streak like GitHub | STREAK.md | | changelog 🧩 | Auto-generates CHANGELOG.md from all commits | CHANGELOG.md | | bus factor 🚨 | Identifies single-owner files - knowledge risk | BUS-FACTOR.md |

🎬 Demo

Click the thumbnail below to watch the full demo.

📸 Screenshots

🔗 Repo Selection - Local or Any Public GitHub URL

At startup, the agent asks for a repo. Press Enter to use your local repo, or paste any public GitHub URL to analyze it instantly. The agent auto-clones it, reads the git history, and loads the command menu with live repo stats.

🧠 Vibe Check - Team Morale & Sentiment

Measure the emotional heartbeat of your team. The Git Historian analyzes commit messages for frustration, excitement, and urgency, giving you a real-time sentiment score and insight into the team's' mental state.

👻 Ghost Hunter - Finding Lost Fragments

The Git Historian deep-dives into the repository's reflog to find "ghosts"—commits that were lost due to hard resets, rebases, or deleted branches. Never lose a brilliant idea again.

📋 Standup - Daily Progress Report

Turn your last 24 hours of commits into a clean daily standup, grouped by feature, fix, and chore. Perfect for sharing in team channels without manually digging through git history.

📅 Weekly Summary - 7-Day Digest

Get a full week of work summarized into a readable digest, grouped by type - features shipped, bugs fixed, and maintenance done. A simple way to review what actually got done.

🔥 Roast Me - Brutal Commit Review

Get a brutally honest, funny AI review of your commit habits. Flags vague messages, lazy WIP commits, missing prefixes, and more - with a score out of 10 and one genuine compliment.

📊 Health Report - Code Health Scan

Scan your repository for TODOs, FIXMEs, high-churn files, revert commits, and tech debt signals. Get a structured report with 🔴 Critical, 🟡 Warning, and 🟢 Healthy sections - plus an overall health score.

🎯 Suggest Commits - Better Commit Messages

Reviews your last 10 commit messages and rewrites any that are vague, lazy, or don't follow conventional commit format. Shows the original, the rewrite, and why it's better - with a Commit Quality Score.

📧 Share - Slack & Email Ready

Takes your last standup and reformats it into two ready-to-paste formats - a Slack message with emoji and bold headers, and a professional email with subject line and sign-off.

🔮 PR Summary - Auto PR Description

Analyzes your recent commits and changed files to generate a polished pull request description - what changed, why it changed, files affected, risks, and a suggested PR title.

⏰ Streak Tracker - GitHub-Style Commit Streaks

Calculates your current commit streak, longest streak ever, most productive day of the week, most active time of day, and this week vs last week commit velocity. Ends with a motivational message.

🧩 Auto Changelog - CHANGELOG.md Generator

Reads your entire commit history and generates a professional CHANGELOG.md following the Keep a Changelog format - grouped by version or month, with Added, Changed, Fixed, and Removed sections.

🚨 Bus Factor - Knowledge Risk Analysis

Identifies files that only one contributor has ever touched. Flags 🔴 high-risk files (single owner), 🟡 medium-risk (one person owns 80%+), and 🟢 healthy files - with an overall Bus Factor Score and recommendations.

🚀 Quick Start

Prerequisites

• Node.js 18+
• Git
• A free Groq API key (takes 2 minutes, no card needed)

Installation

# 1. Clone the agent
git clone https://github.com/JexanJoel/Git-Standup-Agent.git
cd Git-Standup-Agent

# 2. Install dependencies
npm install

# 3. Add your API key
echo "GROQ_API_KEY=your_key_here" > .env

# 4. Run
node index.js

At startup, you'll see:

┌─────────────────────────────────────────────────────────┐
│              git-standup-agent                          │
├─────────────────────────────────────────────────────────┤
│  Enter a public GitHub repo URL to analyze it,          │
│  or press Enter to use the current local repo.          │
└─────────────────────────────────────────────────────────┘

🔗 Repo URL (or Enter to skip): https://github.com/expressjs/express

⏳ Cloning...
✅ Cloned successfully! Analyzing: express

Then the full command menu loads with live repo stats and you're ready to go.

Running via gitclaw SDK

# Install gitclaw
npm install -g gitclaw

# Run directly with a prompt
gitclaw --dir . --model groq:llama-3.3-70b-versatile "generate my standup for today"
gitclaw --dir . --model groq:llama-3.3-70b-versatile "roast my recent commits"
gitclaw --dir . --model groq:llama-3.3-70b-versatile "give me a health report"

Validate the agent spec

# Install gitagent CLI
npm install -g @shreyaskapale/gitagent

# Validate
npx @shreyaskapale/gitagent validate
npx @shreyaskapale/gitagent info
npx @shreyaskapale/gitagent export --format system-prompt

Expected output:

✓ agent.yaml - valid
✓ SOUL.md - valid
✓ tools/git-log.yaml - valid
✓ skills/ - valid
✓ Validation passed (0 warnings)

🤖 Commands

You: standup

🏗️ How It Works

flowchart TD
    START["🔗 Startup\nEnter GitHub URL or local path"]:::start

    R1["📁 Local Repo\n(current dir)"]:::git
    R2["🌐 Public GitHub Repo\n(auto-cloned via git clone)"]:::git

    A["🧠 Agent Identity"]:::identity
    A1["SOUL.md\nPersonality"]:::file
    A2["RULES.md\nConstraints"]:::file
    A3["10x SKILL.md\nCapabilities"]:::file

    B["⚙️ index.js\nRuntime"]:::runtime
    C["📜 git log\nCommit History"]:::gitlog
    D["🤖 Groq LLM\nllama-3.3-70b"]:::llm

    E["📄 Output Files"]:::output
    E1["STANDUP.md"]:::outfile
    E2["ROAST.md"]:::outfile
    E3["HEALTH.md"]:::outfile
    E4["CHANGELOG.md"]:::outfile
    E5["BUS-FACTOR.md"]:::outfile
    E6["+ 5 more..."]:::outfile

    START --> R1 & R2
    R1 & R2 --> C
    A1 & A2 & A3 --> A
    C --> B
    A --> B
    B --> D
    D --> E
    E --> E1 & E2 & E3 & E4 & E5 & E6

    classDef start fill:#064e3b,stroke:#10b981,color:#d1fae5
    classDef identity fill:#1e1b4b,stroke:#6366f1,color:#e0e7ff
    classDef file fill:#312e81,stroke:#818cf8,color:#c7d2fe
    classDef runtime fill:#1e3a5f,stroke:#38bdf8,color:#e0f2fe
    classDef git fill:#14532d,stroke:#4ade80,color:#dcfce7
    classDef gitlog fill:#1a2e05,stroke:#84cc16,color:#ecfccb
    classDef llm fill:#7c2d12,stroke:#fb923c,color:#ffedd5
    classDef output fill:#1f2937,stroke:#6b7280,color:#f3f4f6
    classDef outfile fill:#111827,stroke:#374151,color:#9ca3af

1. At startup, choose a local repo or paste any public GitHub URL - the agent auto-clones it
2. Agent identity is loaded from SOUL.md, RULES.md, and all 10 SKILL.md files
3. Git context is pulled live using git log for the relevant time range
4. Groq LLM processes the identity + context and generates the output
5. Output is printed to terminal and saved to a .md file automatically
6. Temp clones are automatically cleaned up on exit

🔧 Configuration

Environment Variables

| Variable | Required | Description | |---|---|---| | GROQ_API_KEY | ✅ Yes | Your Groq API key - get one free |

Model

The agent uses llama-3.3-70b-versatile via Groq by default. You can change the model in agent.yaml:

model:
  preferred: "groq:llama-3.3-70b-versatile"
  fallback:
    - "anthropic:claude-sonnet-4-5-20250929"
    - "openai:gpt-4o"

🧩 Built With

| Technology | Purpose | |:---:|:---| | | Git-native agent standard | | | LLM inference (free tier) | | | Agent runtime SDK | | | Runtime environment |

🤝 Contributing

Contributions, issues, and feature requests are welcome! See CONTRIBUTING.md to get started.

📄 License