It all started by noticing a repeating manual task that I had to do over and over again. Which was re-reading my commit history for the past week and writing my weekly progress report and sending it to my team members and client.
I was required to write two types of reports:
- A technical report: which summarize what i’ve done in every individual commit or pull request.
- A business report: which is a bullet point report of what i’ve done in every individual day during the week.
I always thought that it’s some kind of a robot task, which can be automated and done by a simple script or tool which will read my commit history in a smart way and generate the well formatted reports which i can then copy and paste to my email.
So I’ve decided to go with that and start coding this tool in a bunch of coding sessions.
So far, i’ve recorded 4 streams of coding sessions which are available at both twitch and youtube:
This blog post discusses the progress which we’ve mad so far duing the last 4 streams.
The tool is opensource and available at Github.
The cli tool is published on as an npm package which is available at package link.
How to use it?
- Just navigate into the project directory which you want to scan for commits
- Run the following command:
npx ai-commit-report-generator-cli
npx ai-commit-report-generator-cli
-
After running the command, you’ll be prompted to enter your Gemini API key, which is free to get from Google AI Studio
-
After entering your key, it will be added into a .env file int the root directory of your project.
If you choose the run Scan option from the previously listed options you’ll be prompted to enter:
- Do you want to scan the local directory or a custom directory.
- If you choose to scan the local directory, it will be the current directory by default.
- If you choose to scan a custom directory, you’ll be prompted to enter the path to the directory which you want to scan.
- Enter the date interval in which the commits should be scanned either in weeks or days.
Then the tool will fetch the commits from the selected directory based on the selected filters(authors,days or weeks to consider starting from today…).
The CLI tool will then show a progress bar while it scans the commits one by one and generates the technical report.
Just after the that you’ll see another progress bar which tells you that the tool is processing the generated technical commit summaries for every individual day and generating the business or daily bullet points report.
When the process is completed you can get back to the cli menu and choose to view one of the generated reports(Technical or business report).
The Business report will look like this:
And the Technical report will look like this:
How does the Scan works?
Commit Fetcher
The tool First fetches the commits from the selected directory and filters them based on the selected filters(authors,days or weeks to consider starting from today…).
Under the hood the CLI tool is using the git log command to fetch, filter the commits from the selected local directory.
After that the CLI tool parse the results of the git log commands applies other filters and proceeds to the next step.
Commit Statistics Fetcher
For every commit the CLI tool will fetch the list of the files which were modified in the commit with their corresponding insertions, deletion and total changes statistics.
To do that we are using the git show –stat command.
Below you can see an output example of the git show –stat command.Git show stat output
What’s a large language model or LLM?
Before diving deeper into the commit analyzer, let’s understand what’s a large language model or LLM.
An LLM or Language Model is a machine learning model that can be trained on a large amount of text data and can generate text based on that data.
Some examples of LLMs include:
- OpenAI’s ChatGPT
- Anthropic’s Claude
- Google’s Gemini which is the LLM which we will be using in this project.
LLMs can do any kind of general tasks like chatting with humans, generating text, writing code, etc.
But in this project we need a way to instruct those LLMs to perform specific tasks.
That’s where the prompt comes in.
A prompt is a set of clear instructions written in natural language which will help us to instruct the LLM to do a specific task like classification, summmarization, etc.
What’s an Agent?
An agent is a program that is capable of interacting with the environment and performing tasks based on its own logic, knowledge and goals.
An agent can use tools to perform actions on the environment.
The tools are like the bridge between the agent and the environment. Each tool gives the agent special abilities to perform observe/actions on the environment.
-
Observe : Process and understand input data.
-
Plan/Reason/Think : Determine the next actions to take and which tools to use to perform them.
-
Act : Perform the selected action on the environment via the tools.
-
Repeat : Repeat the cycle until the goal is met.
Commit AI Processor Agent
After generating the commit statistics, the CLI tool will use the commit analyzer agent to generate a summary of each commit given its details and file changes statistics.
We could have used just an LLM to summarize the commit and the file changes given the LLM a list of all the files which have been changed during the commit.
But that will be costy and unefficient because a single commit can have a lot of file changes in it.
Since we can’t feed all file changes to the LLM at once (imagine a commit from running prettier across your entire codebase!), we need a smarter approach. That’s where our intelligent agent comes in.
The agent acts as a smart intermediary, strategically deciding which file changes deserve closer inspection.
By looking at only the important changes, we get better results while using less resources.
- First, it receives the commit’s basic data (message, hash, and file changes statistics)
- Using the LLM as its reasoning engine, it analyzes the commit’s purpose
- Based on the previous analysis, it selectively examines specific file changes using the “file_diffs_tool”.
- It then feeds relevant information back to the LLM.
- It repeats (3) and (4) as needed to get a complete understanding of the commit
- Finally, it produces a focused, meaningful summary of the commit’s impact
This selective approach ensures efficient processing – we only dive deep into changes that matter, avoiding information overload while still capturing the commit’s true significance.
The prompt which was used to power the agent is the following:
You are a commit analyzer. Follow these steps in order:
1. Here is the commit information:n
- Commit message: {message}
- Commit hash: {hash}
- Global stats: {statistics}
2. Depending on the commit attributes and statistics decide to use the "file_diffs_tool" to get
the diffs or the code changes of a specific file in the commit statistics,
You can use the tool as many times as needed before proceeding to the next step.n
3. Analyse the commit attributes, statistics and code changes to generate a summary of the commit.n
4. The final summary should respect the format instructions below.n
{format_instructions}
Generating An Agentic AI Summary for every commit.
So our Commit AI Processor Agent will process all the commits sequentially one by one and then generate an AI summary entry for each commit.
The shape of the AI summary entry is as follows:
{
"changes": [
{
"type": "enum of: feature, fix, breaking change, or refactor",
"description": "detailed description of what was changed"
}
],
"summary": "a comprehensive paragraph describing the overall changes and their impact",
"called_tools": [
{
"name": "name of the tool that was used",
"description": "description of what the tool was used for",
"called_at": "timestamp of when the tool was called"
}
]
}
Let’s break down the structure of the AI summary:
-
changes : An array of changes identified in the commit, where each change contains:
-
summary : A comprehensive paragraph that describes the overall changes and their impact
-
called_tools : A list of tools used during the analysis, where each tool entry contains:
The called tools key is used for debugging purposes. It allows us to see which tools were used to generate the AI summary for each commit.
Report Generation
Now, we have enough data to generate the technical report but we need more processing steps to generate the business or bullet points based report.
Technical Report Rendering
All we need to do now to render our technical report is to use our previously generated AI Summary entries, read them sequentially and then render the report on the terminal.
Business or Daily Bullet points Report Generation
The business report concist of a set of bullet points which summarize what we’ve done in every individual day.
So before processing our commits with their corresponding AI summary entries, we need to group them by the day where they were committed.
AI Report Generator.
Now, we need a way to generate the daily bullet points report. Given the commits and their corresponding AI summary entries of a specific day, we need to generate a bullet point report which summarizes what we’ve done in that day.
That’s were the AI Report Generator comes in.
The AI Report Generator will take all the commits and their corresponding AI summaries and generate a bullet point report which has the following structure:
{
"date": "ISO datetime string of the day",
"bulletPoints": [
{
"short": "brief, non-technical description of the change",
"long": "detailed, business-focused explanation of the change and its benefits"
}
]
}
Let’s break down the structure:
- date : The ISO datetime string representing when these changes were made
-
bulletPoints : An array of changes where each bullet point contains:
-
short: A concise, non-technical summary of the change -
long: A detailed explanation focusing on business value and user benefits
-
Each bullet point should be free of any technical jargon and should be easy to understand by someone with no technical background.
To effectively achieve all of this we’ve used the following prompt:
You're a business report writer who specializes in making complex technical changes easy to understand for non-technical stakeholders. Your task is to create a clear, simple summary of the changes made.
Follow these steps:
1. Review the list of changes below:
{commits}
2. Create a bullet-point report that:
- Uses simple, everyday language
- Avoids technical terms and jargon
- Focuses on business value and user-facing improvements
- Explains changes in terms of what they mean for users/stakeholders
- Groups related changes together when possible
- Includes specific improvements and their benefits
3. Make sure each bullet point is:
- Written in plain English
- Easy to understand by someone with no technical background
- Focused on what was improved rather than how it was done
4. The number of bullet points should be equal to {numberOfCommits}
5. Follow this format:
{format_instructions}
Rendering the Business
All we need to do now is to use our previously generated AI Daily Report Entries, read them sequentially and then render the report on the terminal.
Conclusion
In this first dev log, we’ve explored how we turned a repetitive manual task into an automated solution using AI. The AI Commit Report Generator CLI tool demonstrates the power of combining:
- Git commands for fetching commit data
- LLMs for intelligent analysis
- Agents for smart decision-making
- Structured prompts for generating targeted outputs
This is just the beginning – there’s more to come in future dev logs where we’ll explore additional features and improvements.
Contact & Resources
Feel free to reach out if you have questions, suggestions, or want to contribute to the project!
Source link
lol
