🤖 The Git Historian

Your git repo has a memory. Now it can speak.

The Git Historian turns raw git history into a compelling story of progress, heart, and lost memories.

🧠 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."

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

📦 Install via npm

The Git Historian is available as a global CLI tool on npm.

Quick Install

npm install -g git-historian

Setup & Run

# 1. Get a free Groq API key at https://console.groq.com

# 2. Go to any git repo
cd your-project

# 3. Create a .env file with your key
echo "GROQ_API_KEY=your_key_here" > .env

# 4. Run
git-historian

No cloning needed. Install once, use in any repo.

🚀 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

_{Daily standup from last 24hrs → STANDUP.md}	_{7-day digest grouped by type → WEEKLY.md}	_{Brutally honest commit review → ROAST.md}
_{TODOs, churn, tech debt → HEALTH.md}	_{Rewrites bad commit messages → COMMIT-SUGGESTIONS.md}	_{Formats standup for Slack & email → SHARE.md}
_{PR description from your changes → PR-SUMMARY.md}	_{GitHub-style commit streak → STREAK.md}	_{Auto-generate changelog → CHANGELOG.md}
_{Single-owner file risk → BUS-FACTOR.md}	_{Show command menu}	_{Quit the agent}

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

At startup, choose a local repo or paste any public GitHub URL - the agent auto-clones it
Agent identity is loaded from SOUL.md, RULES.md, and all 10 SKILL.md files
Git context is pulled live using git log for the relevant time range
Groq LLM processes the identity + context and generates the output
Output is printed to terminal and saved to a .md file automatically
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.

Name		Name	Last commit message	Last commit date
Latest commit History 83 Commits
assets		assets
skills		skills
tools		tools
.gitignore		.gitignore
.npmignore		.npmignore
BUS-FACTOR.md		BUS-FACTOR.md
CHANGELOG.md		CHANGELOG.md
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
COMMIT-SUGGESTIONS.md		COMMIT-SUGGESTIONS.md
CONTRIBUTING.md		CONTRIBUTING.md
GHOSTS.md		GHOSTS.md
HEALTH.md		HEALTH.md
LICENSE		LICENSE
PR-SUMMARY.md		PR-SUMMARY.md
README.md		README.md
ROAST.md		ROAST.md
RULES.md		RULES.md
SHARE.md		SHARE.md
SOUL.md		SOUL.md
STANDUP.md		STANDUP.md
STREAK.md		STREAK.md
VIBE.md		VIBE.md
VISUAL_SPEC.md		VISUAL_SPEC.md
WEEKLY.md		WEEKLY.md
agent.yaml		agent.yaml
hackathon.md		hackathon.md
index.js		index.js
package-lock.json		package-lock.json
package.json		package.json
run.js		run.js

Folders and files

Latest commit

History

Repository files navigation