phantomit

AI-powered git commits. Watches your code, diffs your changes, generates professional commit messages via Groq — so your GitHub graph stays green while you stay focused.

Built by var-raphael.

---

Why

You write code every day but forget to push. Your GitHub graph looks empty. Your commits when you do push are lazy — "fix stuff", "update", "changes". Phantomit solves all three.

It watches your project silently in the background, batches your file changes, sends the diff to Groq AI, and generates a clean conventional commit message. You approve it, it pushes. Done.

---

Install

npm install -g phantomit-cli

---

Quick Start

# 1. Go into any git project
cd your-project

# 2. Setup phantomit
phantomit init

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

# 4. Start watching
phantomit watch --on-save --daemon

Get a free Groq API key at console.groq.com — no credit card required.

---

Commands

Command	Description
phantomit init	Create .phantomit.json config in current project
phantomit watch --every 30	Auto commit every 30 minutes if there are changes
phantomit watch --lines 20	Auto commit when 20+ lines have changed
phantomit watch --on-save	Commit 8 seconds after your last file save
phantomit watch --on-save --daemon	Same but runs silently in the background
phantomit push	Manually trigger a commit right now
phantomit stop	Stop the background daemon
phantomit status	Check if daemon is running + recent activity

---

Watch Modes

--every <minutes>

Triggers a commit on a fixed interval if there are uncommitted changes. Best for devs who want fully automatic, hands-off commits.

phantomit watch --every 30        # every 30 minutes
phantomit watch --every 10        # every 10 minutes

--lines <count>

Triggers a commit when the accumulated diff crosses a line threshold. Best for devs who write in focused bursts.

phantomit watch --lines 20        # commit every 20 lines changed
phantomit watch --lines 50        # commit every 50 lines changed

--on-save

Triggers a commit 8 seconds after your last file save. All saves within that window are batched into one commit. Best for active coding sessions.

phantomit watch --on-save         # foreground — shows prompts in terminal
phantomit watch --on-save --daemon # background — silent, logs to .phantomit.log

--manual

Watcher runs but never auto-commits. You trigger commits yourself with phantomit push.

phantomit watch --manual
# then whenever you're ready:
phantomit push

---

The Commit Prompt

When a commit is triggered in foreground mode, you'll see:

  ✦ Commit message:
  "feat(auth): add JWT token validation to middleware layer"

  [Y] commit & push   [E] edit message   [N] skip

  →

• Y — commit and push as-is
• E — edit the message before committing
• N — skip this commit entirely

In daemon mode (--daemon), commits happen automatically without prompts and are logged to .phantomit.log.

---

Configuration

Running phantomit init creates a .phantomit.json in your project root:

{
  "mode": "interval",
  "interval": 30,
  "lines": 20,
  "debounce": 8,
  "autoPush": true,
  "watch": ["."],
  "ignore": ["node_modules", ".git"],
  "branch": "main"
}

Field	Type	Default	Description
mode	string	interval	Default watch mode (interval, lines, on-save, manual)
interval	number	30	Minutes between commits in interval mode
lines	number	20	Line threshold for lines mode
debounce	number	8	Seconds to wait after last save before triggering (on-save mode)
autoPush	boolean	true	Push to remote after committing
watch	array	["."]	Folders/files to watch
ignore	array	[...]	Extra patterns to ignore (merged with .gitignore)
branch	string	"main"	Branch to push to

CLI flags always override config file values.

---

API Key Setup

Phantomit reads your Groq API key from .env. It supports multiple keys for automatic rotation — useful for spreading rate limits across accounts.

# Single key — works fine
GROQ_API_KEY=your_key

# Multiple keys — phantomit picks one at random per commit
GROQ_API_KEY_1=first_key
GROQ_API_KEY_2=second_key
GROQ_API_KEY_3=third_key
# ...add as many as you want, no limit

Get free keys at console.groq.com.

---

Testing Without a Groq Key

Use --mock to test the full flow with a fake AI response:

phantomit push --mock

This simulates the AI response with a realistic commit message so you can verify the setup works before adding a real key.

---

How It Works

1. Phantomit watches your specified directories using chokidar
2. On trigger (save/interval/lines), it runs git add . then git diff --staged
3. The diff is sent to Groq's llama-3.1-8b-instant model with a strict prompt
4. The AI returns a conventional commit message (10-20 words)
5. You approve, edit, or skip — then it commits and pushes

Your .gitignore is automatically respected — phantomit reads it and excludes those paths from watching.

---

License

MIT — free forever.