hermes-git 0.2.4 → 0.3.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +155 -420
- package/dist/index.js +13332 -1020
- package/package.json +13 -9
package/README.md
CHANGED
|
@@ -4,627 +4,362 @@
|
|
|
4
4
|
|
|
5
5
|
**Intent-driven Git, guided by AI**
|
|
6
6
|
|
|
7
|
+
[](https://www.npmjs.com/package/hermes-git)
|
|
7
8
|
[](https://opensource.org/licenses/MIT)
|
|
8
9
|
[](https://www.typescriptlang.org/)
|
|
9
|
-
[](https://github.com/github/copilot-cli)
|
|
10
10
|
|
|
11
11
|
*Turn natural language intent into safe, explainable Git operations*
|
|
12
12
|
|
|
13
|
-
[Installation](#installation) • [
|
|
13
|
+
[Installation](#installation) • [Quick Start](#quick-start) • [Commands](#commands) • [Configuration](#configuration)
|
|
14
14
|
|
|
15
15
|
</div>
|
|
16
16
|
|
|
17
17
|
---
|
|
18
18
|
|
|
19
|
-
##
|
|
19
|
+
## What it does
|
|
20
20
|
|
|
21
|
-
Hermes is
|
|
21
|
+
Hermes is a CLI that translates what you want to do in Git into the correct, safe sequence of commands — and explains every step.
|
|
22
22
|
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
- **🧠 Context-Aware:** Learns your project patterns and enforces team conventions
|
|
29
|
-
- **📊 Built-in Analytics:** See your productivity gains, command usage, and Git efficiency improvements
|
|
30
|
-
- **🔄 Workflow Shortcuts:** Turn 50+ commands into 5 with intelligent macros
|
|
31
|
-
- **🛡️ Safety First:** Auto-backup, pre-flight checks, and explainable operations
|
|
32
|
-
- **👥 Team-Ready:** Share config and workflows across your entire team
|
|
33
|
-
|
|
34
|
-
### Why Hermes?
|
|
35
|
-
|
|
36
|
-
Git is powerful, but unforgiving. Even experienced developers regularly:
|
|
37
|
-
|
|
38
|
-
- 🔀 Rebase the wrong branch
|
|
39
|
-
- ⚠️ Panic during merge conflicts
|
|
40
|
-
- 🤔 Forget what state their repository is in
|
|
41
|
-
- 🌳 Avoid worktrees because they feel dangerous
|
|
42
|
-
|
|
43
|
-
**Hermes doesn't replace Git.** It stands beside you, explaining where you are, what's risky, and what your safest next move is.
|
|
44
|
-
|
|
45
|
-
> Think of Hermes as your guide at every crossing—the messenger between you and Git's complexity.
|
|
46
|
-
|
|
47
|
-
---
|
|
48
|
-
|
|
49
|
-
## Core Principles
|
|
23
|
+
```bash
|
|
24
|
+
hermes start "add oauth login"
|
|
25
|
+
# → Picks the right base branch
|
|
26
|
+
# → Creates feature/add-oauth-login
|
|
27
|
+
# → Switches and sets upstream
|
|
50
28
|
|
|
51
|
-
|
|
52
|
-
|
|
29
|
+
hermes sync
|
|
30
|
+
# → Evaluates rebase vs merge based on your branch state
|
|
31
|
+
# → Explains the tradeoff before doing anything
|
|
53
32
|
|
|
54
|
-
|
|
55
|
-
|
|
33
|
+
hermes conflict explain
|
|
34
|
+
# → Reads the conflict markers
|
|
35
|
+
# → Explains what each side was trying to do
|
|
36
|
+
# → Suggests a resolution strategy
|
|
56
37
|
|
|
57
|
-
|
|
58
|
-
|
|
38
|
+
hermes wip
|
|
39
|
+
# → Decides commit vs stash based on your repo state
|
|
40
|
+
# → Saves your work safely
|
|
41
|
+
```
|
|
59
42
|
|
|
60
|
-
|
|
61
|
-
No UI, no context switching. Just clarity where you already work.
|
|
43
|
+
No magic. Every command shows exactly what git operations it runs.
|
|
62
44
|
|
|
63
45
|
---
|
|
64
46
|
|
|
65
47
|
## Installation
|
|
66
48
|
|
|
67
|
-
### Prerequisites
|
|
68
|
-
|
|
69
|
-
- **Node.js** 18.0 or higher
|
|
70
|
-
- **Git** (obviously!)
|
|
71
|
-
- **[GitHub Copilot CLI](https://github.com/github/copilot-cli)** (with active subscription)
|
|
72
|
-
|
|
73
|
-
### Install Hermes
|
|
74
|
-
|
|
75
49
|
```bash
|
|
76
50
|
npm install -g hermes-git
|
|
77
51
|
```
|
|
78
52
|
|
|
79
|
-
|
|
53
|
+
**Requires:** Node.js 18+, Git
|
|
80
54
|
|
|
81
|
-
|
|
55
|
+
### Set up your AI provider
|
|
82
56
|
|
|
83
|
-
|
|
84
|
-
# Install Copilot CLI from GitHub releases
|
|
85
|
-
# https://github.com/github/copilot-cli
|
|
86
|
-
|
|
87
|
-
# Authenticate
|
|
88
|
-
copilot login
|
|
89
|
-
```
|
|
90
|
-
|
|
91
|
-
### Verify Installation
|
|
57
|
+
Hermes works with Anthropic, OpenAI, or Google Gemini — bring your own API key.
|
|
92
58
|
|
|
93
59
|
```bash
|
|
94
|
-
hermes
|
|
95
|
-
hermes --help
|
|
60
|
+
hermes config setup
|
|
96
61
|
```
|
|
97
62
|
|
|
98
|
-
|
|
63
|
+
This walks you through selecting a provider and saving your key to `~/.config/hermes/config.json` (chmod 600).
|
|
99
64
|
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
### 1. Initialize Your Project
|
|
65
|
+
Or set it manually:
|
|
103
66
|
|
|
104
67
|
```bash
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
Sets up project context, branch naming patterns, and preferences. Config is shareable across your team.
|
|
68
|
+
# Anthropic (Claude)
|
|
69
|
+
hermes config set provider anthropic
|
|
70
|
+
hermes config set anthropic-key sk-ant-...
|
|
109
71
|
|
|
110
|
-
|
|
72
|
+
# OpenAI (GPT-4o)
|
|
73
|
+
hermes config set provider openai
|
|
74
|
+
hermes config set openai-key sk-...
|
|
111
75
|
|
|
112
|
-
|
|
113
|
-
hermes
|
|
114
|
-
|
|
115
|
-
# Switches from correct base branch
|
|
116
|
-
# Tracks time saved
|
|
76
|
+
# Google Gemini
|
|
77
|
+
hermes config set provider gemini
|
|
78
|
+
hermes config set gemini-key AIza...
|
|
117
79
|
```
|
|
118
80
|
|
|
119
|
-
|
|
81
|
+
Verify it worked:
|
|
120
82
|
|
|
121
83
|
```bash
|
|
122
|
-
hermes
|
|
123
|
-
|
|
124
|
-
╔══════════════════════════════════════════════════════╗
|
|
125
|
-
║ Hermes Efficiency Report - Last 30 Days ║
|
|
126
|
-
╚══════════════════════════════════════════════════════╝
|
|
127
|
-
|
|
128
|
-
⏱️ Time Saved: 12.4 hours
|
|
129
|
-
🚀 Commands Run: 847 → 123 (85% reduction)
|
|
130
|
-
📈 Efficiency Gain: +34% compared to raw Git
|
|
84
|
+
hermes config list
|
|
131
85
|
```
|
|
132
86
|
|
|
133
87
|
---
|
|
134
88
|
|
|
135
|
-
##
|
|
136
|
-
|
|
137
|
-
### 🎯 Essential Commands
|
|
138
|
-
|
|
139
|
-
### `hermes init [--quick]`
|
|
140
|
-
|
|
141
|
-
**Initialize Hermes for your project.**
|
|
89
|
+
## Quick Start
|
|
142
90
|
|
|
143
91
|
```bash
|
|
144
|
-
|
|
145
|
-
|
|
146
|
-
|
|
147
|
-
|
|
148
|
-
**Creates:**
|
|
149
|
-
- `.hermes/config.json` - Project configuration (commit this!)
|
|
150
|
-
- Branch naming patterns
|
|
151
|
-
- Workflow shortcuts
|
|
152
|
-
- Team preferences
|
|
153
|
-
|
|
154
|
-
**Why this matters:** Consistency across your entire team, automatic convention enforcement.
|
|
155
|
-
|
|
156
|
-
---
|
|
157
|
-
|
|
158
|
-
### `hermes stats [-d <days>]`
|
|
92
|
+
# 1. Install and configure
|
|
93
|
+
npm install -g hermes-git
|
|
94
|
+
hermes config setup
|
|
159
95
|
|
|
160
|
-
|
|
96
|
+
# 2. Initialize your project (optional, enables team config sharing)
|
|
97
|
+
cd your-project
|
|
98
|
+
hermes init
|
|
161
99
|
|
|
162
|
-
|
|
163
|
-
hermes
|
|
164
|
-
hermes stats -d 7 # Last week
|
|
165
|
-
hermes stats --all-time
|
|
100
|
+
# 3. Start working
|
|
101
|
+
hermes start "user authentication"
|
|
166
102
|
```
|
|
167
103
|
|
|
168
|
-
**Shows:**
|
|
169
|
-
- Time saved vs raw Git
|
|
170
|
-
- Command reduction percentage
|
|
171
|
-
- Success rate
|
|
172
|
-
- Most-used commands
|
|
173
|
-
- Productivity streak
|
|
174
|
-
|
|
175
|
-
**Why this matters:** Quantify your efficiency improvements, see where Hermes helps most.
|
|
176
|
-
|
|
177
104
|
---
|
|
178
105
|
|
|
179
|
-
|
|
106
|
+
## Commands
|
|
107
|
+
|
|
108
|
+
### `hermes config`
|
|
180
109
|
|
|
181
|
-
|
|
110
|
+
Manage API keys and provider settings.
|
|
182
111
|
|
|
183
112
|
```bash
|
|
184
|
-
hermes
|
|
185
|
-
hermes
|
|
186
|
-
hermes
|
|
113
|
+
hermes config setup # Interactive wizard
|
|
114
|
+
hermes config list # Show current config (keys masked)
|
|
115
|
+
hermes config set provider openai
|
|
116
|
+
hermes config set openai-key sk-...
|
|
117
|
+
hermes config get provider
|
|
118
|
+
hermes config unset gemini-key
|
|
187
119
|
```
|
|
188
120
|
|
|
189
|
-
|
|
121
|
+
Config is stored in `~/.config/hermes/config.json`. You can also use environment variables or a `.env` file — see [Configuration](#configuration).
|
|
190
122
|
|
|
191
123
|
---
|
|
192
124
|
|
|
193
125
|
### `hermes plan "<intent>"`
|
|
194
126
|
|
|
195
|
-
|
|
127
|
+
Analyze repo state and propose a safe Git plan. **Makes no changes.**
|
|
196
128
|
|
|
197
129
|
```bash
|
|
198
|
-
hermes plan "bring main into my branch without losing my
|
|
130
|
+
hermes plan "bring main into my branch without losing my work"
|
|
131
|
+
hermes plan "clean up before submitting a PR"
|
|
199
132
|
```
|
|
200
133
|
|
|
201
|
-
**Output includes:**
|
|
202
|
-
- Current repository state (clean, conflicted, mid-rebase, etc.)
|
|
203
|
-
- Recommended strategy (merge vs rebase) with reasoning
|
|
204
|
-
- Potential risks and safety considerations
|
|
205
|
-
- Step-by-step next actions
|
|
206
|
-
|
|
207
|
-
**No changes are made.** This is analysis only.
|
|
208
|
-
|
|
209
134
|
---
|
|
210
135
|
|
|
211
136
|
### `hermes start "<task>"`
|
|
212
137
|
|
|
213
|
-
|
|
138
|
+
Start a new piece of work safely.
|
|
214
139
|
|
|
215
140
|
```bash
|
|
216
|
-
hermes start "
|
|
141
|
+
hermes start "payment refactor"
|
|
142
|
+
# → Picks correct base branch
|
|
143
|
+
# → Creates and switches to feature/payment-refactor
|
|
217
144
|
```
|
|
218
145
|
|
|
219
|
-
**Hermes will:**
|
|
220
|
-
- Choose the correct base branch
|
|
221
|
-
- Generate a conventional branch name
|
|
222
|
-
- Create and switch to the new branch
|
|
223
|
-
- Set upstream tracking if needed
|
|
224
|
-
- Explain what it did and why
|
|
225
|
-
|
|
226
146
|
---
|
|
227
147
|
|
|
228
|
-
### `hermes
|
|
148
|
+
### `hermes sync [--from <branch>]`
|
|
229
149
|
|
|
230
|
-
|
|
150
|
+
Bring your branch up to date.
|
|
231
151
|
|
|
232
152
|
```bash
|
|
233
|
-
hermes
|
|
153
|
+
hermes sync
|
|
154
|
+
hermes sync --from develop
|
|
234
155
|
```
|
|
235
156
|
|
|
236
|
-
|
|
237
|
-
- Create a WIP commit, or
|
|
238
|
-
- Stash changes with a meaningful label
|
|
239
|
-
|
|
240
|
-
Based on repository state and what's safest. **No lost work. Ever.**
|
|
157
|
+
Hermes evaluates whether rebase or merge is safer given your branch state and explains before executing.
|
|
241
158
|
|
|
242
159
|
---
|
|
243
160
|
|
|
244
|
-
### `hermes
|
|
161
|
+
### `hermes wip [-m "<message>"]`
|
|
245
162
|
|
|
246
|
-
|
|
163
|
+
Save work in progress.
|
|
247
164
|
|
|
248
165
|
```bash
|
|
249
|
-
hermes
|
|
250
|
-
hermes
|
|
166
|
+
hermes wip
|
|
167
|
+
hermes wip -m "checkpoint before sync"
|
|
251
168
|
```
|
|
252
169
|
|
|
253
|
-
|
|
254
|
-
- Whether the branch is shared (has remote tracking)
|
|
255
|
-
- Whether rebase is safe
|
|
256
|
-
- Whether merge is preferable
|
|
257
|
-
|
|
258
|
-
If a risky operation is detected, Hermes explains before proceeding.
|
|
170
|
+
Decides commit vs stash based on what's safest in your current state.
|
|
259
171
|
|
|
260
172
|
---
|
|
261
173
|
|
|
262
174
|
### `hermes conflict explain`
|
|
263
175
|
|
|
264
|
-
|
|
176
|
+
Understand why a conflict exists.
|
|
265
177
|
|
|
266
178
|
```bash
|
|
267
179
|
hermes conflict explain
|
|
268
180
|
```
|
|
269
181
|
|
|
270
|
-
|
|
271
|
-
- List all conflicted files
|
|
272
|
-
- Summarize each side's intent (ours vs theirs)
|
|
273
|
-
- Identify common causes (refactor, rename, move)
|
|
274
|
-
- Suggest a resolution strategy
|
|
275
|
-
|
|
276
|
-
This is explanation, not guesswork. Make informed decisions.
|
|
182
|
+
For each conflicted file: what each side was doing, why they conflict, and how to approach resolution.
|
|
277
183
|
|
|
278
184
|
---
|
|
279
185
|
|
|
280
186
|
### `hermes conflict apply`
|
|
281
187
|
|
|
282
|
-
|
|
188
|
+
Resolve conflicts file by file with AI assistance.
|
|
283
189
|
|
|
284
190
|
```bash
|
|
285
191
|
hermes conflict apply
|
|
286
192
|
```
|
|
287
193
|
|
|
288
|
-
|
|
289
|
-
- Proposes a merged version
|
|
290
|
-
- Shows a diff preview
|
|
291
|
-
- Lets you choose: accept, edit manually, or skip
|
|
292
|
-
|
|
293
|
-
**Hermes never auto-commits without your consent.**
|
|
194
|
+
For each file: shows a proposed resolution, lets you accept, edit manually, or skip. Never auto-commits.
|
|
294
195
|
|
|
295
196
|
---
|
|
296
197
|
|
|
297
|
-
### `hermes
|
|
198
|
+
### `hermes workflow <name>`
|
|
298
199
|
|
|
299
|
-
|
|
200
|
+
One-command workflows for common patterns.
|
|
300
201
|
|
|
301
202
|
```bash
|
|
302
|
-
hermes
|
|
203
|
+
hermes workflow pr-ready # fetch → rebase → push --force-with-lease
|
|
204
|
+
hermes workflow daily-sync # fetch all → show status → suggest next action
|
|
205
|
+
hermes workflow quick-commit # generate commit message from staged diff
|
|
206
|
+
hermes workflow list # show available workflows
|
|
303
207
|
```
|
|
304
208
|
|
|
305
|
-
**Hermes will:**
|
|
306
|
-
- Create a branch
|
|
307
|
-
- Create a worktree in a predictable location
|
|
308
|
-
- Track active worktrees
|
|
309
|
-
- Help prevent committing in the wrong place
|
|
310
|
-
|
|
311
209
|
---
|
|
312
210
|
|
|
313
|
-
|
|
314
|
-
|
|
315
|
-
### Example Workflows
|
|
211
|
+
### `hermes worktree new "<task>"`
|
|
316
212
|
|
|
317
|
-
|
|
213
|
+
Create a Git worktree safely.
|
|
318
214
|
|
|
319
215
|
```bash
|
|
320
|
-
|
|
321
|
-
|
|
322
|
-
hermes init
|
|
323
|
-
|
|
324
|
-
# Answer a few questions:
|
|
325
|
-
# - Project name?
|
|
326
|
-
# - Main branch? (main)
|
|
327
|
-
# - Feature branch pattern? (feature/{description})
|
|
328
|
-
# - Enable auto-backup? (yes)
|
|
329
|
-
|
|
330
|
-
# Config saved and ready for your team!
|
|
216
|
+
hermes worktree new "fix memory leak"
|
|
217
|
+
# → Creates branch, worktree at ../repo-fix-memory-leak
|
|
331
218
|
```
|
|
332
219
|
|
|
333
|
-
|
|
334
|
-
|
|
335
|
-
```bash
|
|
336
|
-
# Morning: check status
|
|
337
|
-
hermes workflow daily-sync
|
|
338
|
-
|
|
339
|
-
# Start new feature
|
|
340
|
-
hermes start "oauth2-login"
|
|
341
|
-
# → Creates: feature/oauth2-login
|
|
342
|
-
# → Tracks time: saved ~60s vs manual Git
|
|
343
|
-
|
|
344
|
-
# Work on code...
|
|
345
|
-
|
|
346
|
-
# Save progress
|
|
347
|
-
hermes wip -m "checkpoint"
|
|
348
|
-
# → Decides: commit vs stash based on state
|
|
349
|
-
# → Auto-backup if configured
|
|
350
|
-
|
|
351
|
-
# Sync with main
|
|
352
|
-
hermes sync
|
|
353
|
-
# → Evaluates: rebase vs merge
|
|
354
|
-
# → Explains why before executing
|
|
355
|
-
|
|
356
|
-
# Handle conflicts
|
|
357
|
-
hermes conflict explain
|
|
358
|
-
hermes conflict apply
|
|
359
|
-
|
|
360
|
-
# Ready for PR
|
|
361
|
-
hermes workflow pr-ready
|
|
362
|
-
# → Fetch, rebase, push --force-with-lease
|
|
220
|
+
---
|
|
363
221
|
|
|
364
|
-
|
|
365
|
-
hermes stats
|
|
366
|
-
# 🎉 Time saved today: 24 minutes!
|
|
367
|
-
```
|
|
222
|
+
### `hermes init [--quick]`
|
|
368
223
|
|
|
369
|
-
|
|
224
|
+
Initialize project-level config (`.hermes/config.json`). Commit this to share branch patterns and workflows with your team.
|
|
370
225
|
|
|
371
|
-
**Scenario 1: Safe branch sync**
|
|
372
226
|
```bash
|
|
373
|
-
|
|
374
|
-
|
|
375
|
-
🔍 Analyzing repository state...
|
|
376
|
-
|
|
377
|
-
📋 Recommended Plan:
|
|
378
|
-
Your branch is 5 commits behind main. Rebase is safe because:
|
|
379
|
-
- No remote tracking (local-only branch)
|
|
380
|
-
- Working directory is clean
|
|
381
|
-
- No ongoing operations
|
|
382
|
-
|
|
383
|
-
Recommended: git fetch && git rebase origin/main
|
|
227
|
+
hermes init # Interactive
|
|
228
|
+
hermes init --quick # Use defaults
|
|
384
229
|
```
|
|
385
230
|
|
|
386
|
-
|
|
387
|
-
```bash
|
|
388
|
-
$ hermes conflict explain
|
|
389
|
-
|
|
390
|
-
🔍 Analyzing conflicts...
|
|
231
|
+
---
|
|
391
232
|
|
|
392
|
-
|
|
393
|
-
• src/auth/login.ts
|
|
233
|
+
### `hermes stats [-d <days>]`
|
|
394
234
|
|
|
395
|
-
|
|
396
|
-
main refactored the authentication flow to use async/await,
|
|
397
|
-
while your branch updated error handling with try-catch.
|
|
235
|
+
Show command usage and success rate.
|
|
398
236
|
|
|
399
|
-
|
|
400
|
-
|
|
401
|
-
|
|
237
|
+
```bash
|
|
238
|
+
hermes stats
|
|
239
|
+
hermes stats -d 7
|
|
240
|
+
hermes stats --all-time
|
|
402
241
|
```
|
|
403
242
|
|
|
404
243
|
---
|
|
405
244
|
|
|
406
|
-
##
|
|
407
|
-
|
|
408
|
-
Hermes uses **GitHub Copilot CLI** as its reasoning engine to:
|
|
245
|
+
## Configuration
|
|
409
246
|
|
|
410
|
-
|
|
411
|
-
- 📊 Analyze repository state
|
|
412
|
-
- 🔧 Generate safe Git command sequences
|
|
413
|
-
- 💬 Explain decisions in human-readable terms
|
|
247
|
+
Hermes resolves config in this priority order:
|
|
414
248
|
|
|
415
|
-
|
|
249
|
+
| Source | Example |
|
|
250
|
+
|--------|---------|
|
|
251
|
+
| Environment variable | `export ANTHROPIC_API_KEY=sk-ant-...` |
|
|
252
|
+
| `.env` file in current dir | `ANTHROPIC_API_KEY=sk-ant-...` |
|
|
253
|
+
| `~/.config/hermes/config.json` | set via `hermes config set` |
|
|
416
254
|
|
|
417
|
-
|
|
255
|
+
**Supported env vars:**
|
|
418
256
|
|
|
419
|
-
|
|
420
|
-
|
|
421
|
-
|
|
257
|
+
| Variable | Description |
|
|
258
|
+
|----------|-------------|
|
|
259
|
+
| `HERMES_PROVIDER` | Pin provider: `anthropic`, `openai`, or `gemini` |
|
|
260
|
+
| `ANTHROPIC_API_KEY` | Anthropic API key |
|
|
261
|
+
| `OPENAI_API_KEY` | OpenAI API key |
|
|
262
|
+
| `GEMINI_API_KEY` / `GOOGLE_API_KEY` | Google Gemini API key |
|
|
422
263
|
|
|
423
|
-
Hermes
|
|
264
|
+
If `HERMES_PROVIDER` is not set, Hermes auto-detects by using whichever key it finds first (Anthropic → OpenAI → Gemini).
|
|
424
265
|
|
|
425
|
-
|
|
426
|
-
You can always see the commands Hermes runs. No abstraction, no magic.
|
|
266
|
+
**Supported providers and models:**
|
|
427
267
|
|
|
428
|
-
|
|
429
|
-
|
|
430
|
-
|
|
431
|
-
|
|
432
|
-
|
|
433
|
-
|
|
434
|
-
**You can always drop down to raw Git.** Hermes exists to guide, not to obscure.
|
|
268
|
+
| Provider | Model | Get a key |
|
|
269
|
+
|----------|-------|-----------|
|
|
270
|
+
| Anthropic | claude-sonnet-4-6 | [console.anthropic.com](https://console.anthropic.com/) |
|
|
271
|
+
| OpenAI | gpt-4o | [platform.openai.com/api-keys](https://platform.openai.com/api-keys) |
|
|
272
|
+
| Google | gemini-2.0-flash | [aistudio.google.com/app/apikey](https://aistudio.google.com/app/apikey) |
|
|
435
273
|
|
|
436
274
|
---
|
|
437
275
|
|
|
438
|
-
##
|
|
276
|
+
## How it works
|
|
439
277
|
|
|
440
|
-
|
|
441
|
-
|
|
442
|
-
|
|
278
|
+
1. **Reads your repo state** — branch, commits, dirty files, conflicts, remote tracking
|
|
279
|
+
2. **Sends context + intent to an AI** — using your configured provider
|
|
280
|
+
3. **Validates the response** — all returned commands must start with `git`, destructive flags are blocked
|
|
281
|
+
4. **Executes with display** — shows every command before running it
|
|
282
|
+
5. **You always stay in control** — interactive prompts for anything irreversible
|
|
443
283
|
|
|
444
284
|
---
|
|
445
285
|
|
|
446
|
-
##
|
|
447
|
-
|
|
448
|
-
### Hermes vs Raw Git
|
|
286
|
+
## Philosophy
|
|
449
287
|
|
|
450
|
-
|
|
451
|
-
|------|---------|--------|
|
|
452
|
-
| **Sync branch** | Remember rebase vs merge rules, check if shared | `hermes sync` - evaluates and explains |
|
|
453
|
-
| **Start feature** | Think of branch name, remember base branch | `hermes start "feature name"` - handles conventions |
|
|
454
|
-
| **Save WIP** | Decide commit vs stash, write message | `hermes wip` - chooses safest option |
|
|
455
|
-
| **Resolve conflict** | Parse diff markers, guess intent | `hermes conflict explain` - AI explains both sides |
|
|
288
|
+
**Never hide Git.** Every command Hermes runs is shown. You can drop to raw Git at any point.
|
|
456
289
|
|
|
457
|
-
|
|
290
|
+
**Never surprise.** Risky operations include an explanation before execution.
|
|
458
291
|
|
|
459
|
-
|
|
460
|
-
- No context switching from your terminal workflow
|
|
461
|
-
- Every operation is a learning opportunity
|
|
462
|
-
- Works over SSH, in Docker, anywhere Git works
|
|
463
|
-
- Integrates with your existing Git knowledge
|
|
292
|
+
**Bring your own AI.** No proprietary backend. Works with any provider you already pay for.
|
|
464
293
|
|
|
465
294
|
---
|
|
466
295
|
|
|
467
296
|
## Troubleshooting
|
|
468
297
|
|
|
469
|
-
|
|
298
|
+
**No AI provider configured**
|
|
470
299
|
|
|
471
300
|
```bash
|
|
472
|
-
|
|
301
|
+
hermes config setup
|
|
473
302
|
```
|
|
474
303
|
|
|
475
|
-
**
|
|
476
|
-
|
|
477
|
-
### Authentication Required
|
|
304
|
+
**Wrong provider selected**
|
|
478
305
|
|
|
479
306
|
```bash
|
|
480
|
-
|
|
307
|
+
hermes config set provider anthropic
|
|
308
|
+
hermes config list # verify
|
|
481
309
|
```
|
|
482
310
|
|
|
483
|
-
**
|
|
311
|
+
**Key saved but not working**
|
|
484
312
|
|
|
485
|
-
|
|
313
|
+
```bash
|
|
314
|
+
# Check what Hermes sees
|
|
315
|
+
hermes config list
|
|
486
316
|
|
|
487
|
-
|
|
488
|
-
|
|
489
|
-
|
|
490
|
-
|
|
317
|
+
# Environment variables override saved config
|
|
318
|
+
# Check for conflicting vars:
|
|
319
|
+
echo $ANTHROPIC_API_KEY
|
|
320
|
+
```
|
|
491
321
|
|
|
492
|
-
|
|
322
|
+
**General debugging**
|
|
493
323
|
|
|
494
324
|
```bash
|
|
495
|
-
# Check Hermes version
|
|
496
325
|
hermes --version
|
|
497
|
-
|
|
498
|
-
|
|
499
|
-
copilot --version
|
|
500
|
-
|
|
501
|
-
# Test in a clean repo
|
|
502
|
-
cd /tmp && git init test && cd test
|
|
503
|
-
hermes plan "test"
|
|
326
|
+
hermes config list
|
|
327
|
+
git status
|
|
504
328
|
```
|
|
505
329
|
|
|
506
330
|
---
|
|
507
331
|
|
|
508
332
|
## Contributing
|
|
509
333
|
|
|
510
|
-
Contributions are welcome! Please see [DEVELOPMENT.md](DEVELOPMENT.md) for:
|
|
511
|
-
|
|
512
|
-
- Project structure
|
|
513
|
-
- Development setup
|
|
514
|
-
- Adding new commands
|
|
515
|
-
- Testing guidelines
|
|
516
|
-
- Code style
|
|
517
|
-
|
|
518
|
-
### Quick Start for Contributors
|
|
519
|
-
|
|
520
334
|
```bash
|
|
521
|
-
|
|
522
|
-
|
|
523
|
-
cd hermes
|
|
335
|
+
git clone https://github.com/simandebvu/hermes-cli.git
|
|
336
|
+
cd hermes-cli
|
|
524
337
|
bun install
|
|
525
|
-
|
|
526
|
-
# Run in dev mode
|
|
527
338
|
bun run dev --help
|
|
528
|
-
|
|
529
|
-
# Build
|
|
530
339
|
bun run build
|
|
531
|
-
|
|
532
|
-
# Test
|
|
533
340
|
bun run typecheck
|
|
534
341
|
```
|
|
535
342
|
|
|
536
|
-
|
|
537
|
-
|
|
538
|
-
## FAQ
|
|
539
|
-
|
|
540
|
-
**Q: Does Hermes send my code to AI services?**
|
|
541
|
-
A: Only repository state metadata (branch names, file lists, status) is sent. File contents are not transmitted unless explicitly needed for conflict resolution. See [SECURITY.md](docs/SECURITY.md) for details.
|
|
542
|
-
|
|
543
|
-
**Q: Does Hermes require a GitHub Copilot subscription?**
|
|
544
|
-
A: Yes. Hermes uses the GitHub Copilot CLI, which requires an active Copilot subscription.
|
|
545
|
-
|
|
546
|
-
**Q: Can I use Hermes without internet?**
|
|
547
|
-
A: No. Hermes requires internet connectivity to communicate with GitHub Copilot's AI models.
|
|
548
|
-
|
|
549
|
-
**Q: Will Hermes work with my existing Git workflow?**
|
|
550
|
-
A: Yes! Hermes is designed to complement your workflow, not replace it. Use it when you need guidance, fall back to raw Git anytime.
|
|
551
|
-
|
|
552
|
-
**Q: What if Hermes suggests something wrong?**
|
|
553
|
-
A: Hermes never executes commands without showing them first. You always have the final say. If a suggestion seems wrong, don't proceed and use raw Git instead.
|
|
554
|
-
|
|
555
|
-
---
|
|
556
|
-
|
|
557
|
-
## Efficiency Metrics
|
|
558
|
-
|
|
559
|
-
Real-world time savings reported by users:
|
|
560
|
-
|
|
561
|
-
| Task | Raw Git | With Hermes | Time Saved |
|
|
562
|
-
|------|---------|-------------|------------|
|
|
563
|
-
| **Start feature** | 2-3 min | 30 sec | ~2 min |
|
|
564
|
-
| **Sync branch** | 3-5 min | 45 sec | ~3 min |
|
|
565
|
-
| **Resolve conflict** | 10-15 min | 5 min | ~8 min |
|
|
566
|
-
| **Daily workflows** | 15-20 min | 5 min | ~12 min |
|
|
567
|
-
|
|
568
|
-
**Average:** **10-15 hours saved per developer per month**
|
|
569
|
-
|
|
570
|
-
---
|
|
571
|
-
|
|
572
|
-
## Roadmap
|
|
573
|
-
|
|
574
|
-
### Current (v0.2) ✨
|
|
575
|
-
- ✅ 10 commands including efficiency features
|
|
576
|
-
- ✅ GitHub Copilot CLI integration
|
|
577
|
-
- ✅ Project context awareness (`hermes init`)
|
|
578
|
-
- ✅ Analytics dashboard (`hermes stats`)
|
|
579
|
-
- ✅ Workflow shortcuts (`hermes workflow`)
|
|
580
|
-
- ✅ Team-shareable configuration
|
|
581
|
-
- ✅ Time-saved tracking
|
|
582
|
-
|
|
583
|
-
### Next (v0.3)
|
|
584
|
-
- [ ] `hermes undo` - Revert last operation safely
|
|
585
|
-
- [ ] Auto-backup system before risky operations
|
|
586
|
-
- [ ] Ticket integration (Linear, Jira)
|
|
587
|
-
- [ ] `--dry-run` flag for all commands
|
|
588
|
-
|
|
589
|
-
See [PRODUCT_VISION.md](docs/PRODUCT_VISION.md) for full roadmap.
|
|
590
|
-
|
|
591
|
-
### Future
|
|
592
|
-
- [ ] `hermes review` - PR review assistance
|
|
593
|
-
- [ ] `hermes explain "<git-command>"` - Explain any Git command
|
|
594
|
-
- [ ] Configuration file support (`~/.hermesrc`)
|
|
595
|
-
- [ ] Plugin system for custom commands
|
|
596
|
-
- [ ] Interactive mode with `hermes shell`
|
|
343
|
+
Issues and PRs welcome at [github.com/simandebvu/hermes-cli](https://github.com/simandebvu/hermes-cli).
|
|
597
344
|
|
|
598
345
|
---
|
|
599
346
|
|
|
600
347
|
## Why "Hermes"?
|
|
601
348
|
|
|
602
|
-
In Greek mythology,
|
|
603
|
-
|
|
604
|
-
- **Branches are worlds.**
|
|
605
|
-
- **Merges are crossings.**
|
|
606
|
-
- **Hermes ensures you cross safely.**
|
|
349
|
+
In Greek mythology, Hermes guides travelers and carries messages between worlds. Branches are worlds. Merges are crossings. Hermes makes sure you get there safely.
|
|
607
350
|
|
|
608
351
|
---
|
|
609
352
|
|
|
610
353
|
## License
|
|
611
354
|
|
|
612
|
-
[MIT
|
|
613
|
-
|
|
614
|
-
---
|
|
615
|
-
|
|
616
|
-
## Acknowledgments
|
|
617
|
-
|
|
618
|
-
- Powered by [GitHub Copilot CLI](https://github.com/github/copilot-cli)
|
|
619
|
-
- Built with [Commander.js](https://github.com/tj/commander.js), [Chalk](https://github.com/chalk/chalk), and [Inquirer](https://github.com/SBoudrias/Inquirer.js)
|
|
620
|
-
- Inspired by the need to make Git safer and more accessible
|
|
355
|
+
[MIT](LICENSE)
|
|
621
356
|
|
|
622
357
|
---
|
|
623
358
|
|
|
624
359
|
<div align="center">
|
|
625
360
|
|
|
626
|
-
**
|
|
361
|
+
**Built with [Commander.js](https://github.com/tj/commander.js), [Chalk](https://github.com/chalk/chalk), [Inquirer](https://github.com/SBoudrias/Inquirer.js)**
|
|
627
362
|
|
|
628
|
-
[Report
|
|
363
|
+
[Report a bug](https://github.com/simandebvu/hermes-cli/issues) • [Request a feature](https://github.com/simandebvu/hermes-cli/issues)
|
|
629
364
|
|
|
630
365
|
</div>
|