Skip to content

Commit 5fb3018

Browse files
hkv-31hkv-31
committed
Updated readme.md
1 parent f4a4c1d commit 5fb3018

1 file changed

Lines changed: 84 additions & 61 deletions

File tree

‎README.md‎

Lines changed: 84 additions & 61 deletions
Original file line numberDiff line numberDiff line change
@@ -1,24 +1,30 @@
1+
<div align="center">
2+
3+
<img src="https://img.shields.io/badge/GitAgent-Hackathon-black?style=for-the-badge&logo=github" />
4+
<img src="https://img.shields.io/badge/Powered%20by-Groq-orange?style=for-the-badge" />
5+
<img src="https://img.shields.io/badge/License-MIT-blue?style=for-the-badge" />
6+
17
# Code Explainer Bot
28

3-
A GitAgent that lives in your GitHub repo and responds to `@gitagent` commands
4-
in PR comments. Tag it on any file or function and it explains the code in plain
5-
English — or generates unit tests instantly.
9+
### A GitAgent that lives inside your PRs — explains code and generates tests on demand.
10+
11+
**Just comment `@gitagent explain` or `@gitagent test` on any PR. Done.**
12+
13+
[View Demo PR →](https://github.com/hkv-31/Code-Explainer-Git-Agent/pull/1)
614

7-
Built for the [GitAgent Hackathon](https://hackculture.dev) by HackCulture.
15+
</div>
816

917
---
1018

11-
## Demo
19+
## What it does
1220

13-
On any PR or issue comment, type:
21+
Drop a comment on any pull request and the bot replies instantly — no setup, no context switching, no copy-pasting into ChatGPT.
1422

1523
```
1624
@gitagent explain src/auth/token.js#L20-L45
1725
```
1826

19-
The bot replies in-thread:
20-
21-
> ### What this code does
27+
> **What this code does**
2228
>
2329
> This function validates a JWT token and extracts the user payload. It checks
2430
> the signature against the secret key and throws if the token is expired.
@@ -28,101 +34,118 @@ The bot replies in-thread:
2834
> - The `ignoreExpiration` flag is intentionally false here
2935
> - Returns a plain JS object, not a class instance
3036
>
31-
> **Watch out for:** If `JWT_SECRET` is undefined in env, this will throw a
32-
> confusing `secretOrPrivateKey` error rather than a missing env error.
37+
> **Watch out for:** If `JWT_SECRET` is undefined in env, this will throw a confusing `secretOrPrivateKey` error rather than a missing env error.
3338
34-
Or generate tests:
39+
Or generate tests instantly:
3540

3641
```
3742
@gitagent test src/utils/format.js
3843
```
3944

4045
---
4146

42-
## Setup (5 minutes)
43-
44-
### 1. Add this repo as a GitHub Actions dependency
45-
46-
Copy `.github/workflows/agent.yml` into your target repository.
47+
## Commands
4748

48-
### 2. Add secrets
49+
| Command | What it does |
50+
|---|---|
51+
| `@gitagent explain <file>` | Explains an entire file in plain English |
52+
| `@gitagent explain <file>#L10-L30` | Explains a specific line range |
53+
| `@gitagent test <file>` | Generates unit tests (auto-detects Jest, pytest, RSpec, etc.) |
4954

50-
In your repo → Settings → Secrets → Actions, add:
55+
---
5156

52-
| Secret | Where to get it |
53-
|---|---|
54-
| `GROQ_API_KEY` | (https://console.groq.com/keys) — free tier, no card needed |
55-
| `GITHUB_TOKEN` | Auto-provided by GitHub Actions — nothing to do |
57+
## Setup in 3 steps
5658

57-
### 3. Install the agent (optional local use)
59+
### 1. Copy the workflow into your repo
5860

5961
```bash
60-
npm install -g @open-gitagent/gitagent
61-
gitagent validate # confirm agent.yaml is valid
62-
gitagent info # see agent summary
62+
mkdir -p .github/workflows
63+
curl -o .github/workflows/agent.yml \
64+
https://raw.githubusercontent.com/hkv-31/Code-Explainer-Git-Agent/main/.github/workflows/agent.yml
6365
```
6466

65-
### 4. Try it
67+
### 2. Add your Groq API key as a secret
6668

67-
Open a PR, drop a comment with `@gitagent explain <filepath>`, and watch the bot reply.
69+
Go to your repo → **Settings → Secrets → Actions → New repository secret**
6870

69-
---
71+
| Secret name | Value |
72+
|---|---|
73+
| `GROQ_API_KEY` | Get free at [console.groq.com/keys](https://console.groq.com/keys) — no card required |
7074

71-
## Commands
75+
`GITHUB_TOKEN` is auto-provided by GitHub Actions. Nothing else needed.
7276

73-
| Command | Example | What it does |
74-
|---|---|---|
75-
| `@gitagent explain <file>` | `@gitagent explain src/api.js` | Explains the whole file |
76-
| `@gitagent explain <file>#L<n>-L<m>` | `@gitagent explain src/api.js#L10-L30` | Explains a specific line range |
77-
| `@gitagent test <file>` | `@gitagent test src/utils.js` | Generates unit tests for the file |
77+
### 3. Open a PR and try it
78+
79+
Comment `@gitagent explain <any-file.js>` and watch the bot reply in seconds.
7880

7981
---
8082

81-
## Architecture
83+
## How it works
84+
85+
```
86+
PR comment → GitHub Actions trigger → fetch file via GitHub API
87+
→ send to Groq (Llama 3) → post explanation as comment reply
88+
```
89+
90+
Built on the [gitagent open standard](https://github.com/open-gitagent/gitagent) — fully framework-agnostic.
8291

8392
```
84-
code-explainer-bot/
85-
├── agent.yaml # gitagent manifest (model, skills, triggers)
86-
├── SOUL.md # agent identity and communication style
87-
├── RULES.md # hard constraints
88-
├── index.js # runtime: parses comments, calls Gemini, posts replies
93+
Code-Explainer-Git-Agent/
94+
├── agent.yaml # gitagent manifest
95+
├── SOUL.md # agent identity & tone
96+
├── RULES.md # hard constraints
97+
├── index.js # runtime logic (~120 lines)
8998
├── skills/
90-
│ ├── explain-code/ # explain skill definition
91-
│ └── generate-tests/ # test generation skill definition
99+
│ ├── explain-code/SKILL.md # explain skill
100+
│ └── generate-tests/SKILL.md # test generation skill
92101
└── .github/workflows/
93-
└── agent.yml # GitHub Actions trigger
102+
└── agent.yml # GitHub Actions trigger
94103
```
95104

96-
The agent is framework-agnostic — export to any supported adapter:
105+
Export to any framework with zero code changes:
97106

98107
```bash
99-
gitagent export --format system-prompt # plain system prompt
100-
gitagent export --format openai # OpenAI Agents SDK
101-
gitagent export --format claude-code # Claude Code
102-
gitagent run . --adapter lyzr # Lyzr Studio
108+
npm install -g @open-gitagent/gitagent
109+
110+
gitagent validate # confirm spec compliance
111+
gitagent export --format system-prompt # plain system prompt
112+
gitagent export --format openai # OpenAI Agents SDK
113+
gitagent export --format claude-code # Claude Code
114+
gitagent run . --adapter lyzr # Lyzr Studio
103115
```
104116

105117
---
106118

107119
## Why this matters
108120

109-
- **Onboarding**: new engineers understand unfamiliar code in seconds instead of hours
110-
- **Code review**: reviewers can tag confusing sections and get instant context
111-
- **Test coverage**: generate test stubs for any file without leaving the PR
121+
**For new engineers:** Understand unfamiliar code in seconds instead of hours. No more "what does this even do?" blocking a review.
122+
123+
**For code reviewers:** Tag confusing sections mid-review and get instant context without leaving the PR.
124+
125+
**For test coverage:** Generate test stubs for any file without switching tools or breaking flow.
112126

113127
---
114128

115-
## Free tier usage
129+
## 100% free to run
116130

117-
This agent runs entirely on free credits:
118-
- **Groq**: 1000+ tokens/day free
119-
- **GitHub Actions**: 2,000 free minutes/month on public repos
120-
- **GitHub API**: 5,000 requests/hour with a standard token
131+
| Tool | Free tier |
132+
|---|---|
133+
| **Groq** (Llama 3.3 70B) | ~14,400 req/day on free tier |
134+
| **GitHub Actions** | 2,000 min/month on public repos |
135+
| **GitHub API** | 5,000 req/hour |
121136

122-
Zero cost to run for a typical engineering team.
137+
Zero cost for a typical engineering team.
123138

124139
---
125140

126-
## License
141+
## Built for
142+
143+
[GitAgent Hackathon](https://hackculture.dev) by HackCulture — April 2026
144+
145+
---
146+
147+
<div align="center">
148+
149+
Made with coffee and one too many `@gitagent explain` comments
127150

128-
MIT
151+
</div>

0 commit comments

Comments
 (0)