Installation
Phantomit is a global CLI tool. Install it once and use it in any git project on your machine.
Requires Node.js 18+. You'll also need a free Groq API key from console.groq.com — no credit card required.
Quick Start
Up and running in under a minute.
That's it. Edit files, save them, and phantomit handles the rest silently in the background.
Commands
| Command | Description |
|---|---|
| phantomit init | Create .phantomit.json config in current project |
| phantomit watch --every 30 | Auto commit every 30 minutes if changes exist |
| phantomit watch --lines 20 | Auto commit when 20+ lines have changed |
| phantomit watch --on-save | Commit 8s after your last file save |
| phantomit watch --on-save --daemon | Same but runs silently in background |
| phantomit push | Manually trigger an AI commit right now |
| phantomit push --mock | Test the flow without a Groq API key |
| phantomit stop | Stop the background daemon |
| phantomit status | Check if daemon is running + recent activity |
Watch Modes
--on-save
Triggers a commit 8 seconds after your last file save. All saves within that window are batched into one commit — so editing 5 files quickly results in one clean commit, not five.
--every <minutes>
Commits on a fixed time interval if there are uncommitted changes. Fully hands-off.
--lines <count>
Commits when the accumulated diff exceeds a line count. Best for dense coding bursts.
phantomit push
No automation — trigger AI commit generation manually whenever you're ready.
.phantomit.log. Use phantomit status to check activity, phantomit stop to kill it.The Prompt
In foreground mode, every commit trigger shows you the AI-generated message before doing anything. You are always in control.
- YCommit and push with the generated message
- EEdit the message before committing
- NSkip this commit entirely
In daemon mode (--daemon), the prompt is skipped and commits happen automatically. All activity is logged to .phantomit.log.
Configuration
Running phantomit init creates a .phantomit.json in your project root. CLI flags always override config values.
| Field | Default | Description |
|---|---|---|
| mode | "interval" | Watch mode: interval, lines, on-save, manual |
| interval | 30 | Minutes between commits in interval mode |
| lines | 20 | Line threshold for lines mode |
| debounce | 8 | Seconds to wait after last save before triggering |
| autoPush | true | Auto push to remote after committing |
| watch | ["."] | Directories to watch. Defaults to entire project. |
| ignore | [...] | Extra ignore patterns. Merged with .gitignore automatically. |
| branch | "main" | Branch to push to |
API Keys
Phantomit reads your Groq key from .env. It supports unlimited keys for automatic rotation — useful for spreading rate limits across free accounts.
Any env variable matching GROQ_API_KEY_* is picked up automatically. Get free keys at console.groq.com.
.env is in your .gitignore. Phantomit reads your gitignore automatically and won't watch or commit your .env..gitignore Integration
Phantomit automatically reads your .gitignore and uses it as the watcher's ignore list. You never have to duplicate your ignore patterns.
The ignore field in .phantomit.json is additive — it merges on top of your gitignore. So node_modules, dist, .env and anything else in gitignore is automatically excluded.
!important.js), globs (**/*.log), trailing slashes (dist/). Powered by the ignore npm library.How It Works
Four simple steps run on every trigger:
File changes are detected by chokidar and batched within the debounce window into a single event. All event types are tracked — creates, edits, deletes, and folder changes.
git add . stages everything, then git diff --staged captures the full diff. Git is the source of truth — no manual file snapshotting needed.
The diff is sent to Groq's llama-3.1-8b-instant with a strict conventional commits prompt. Max 60 tokens, 10-20 words, specific and professional.
The message is shown for approval (or auto-committed in daemon mode). If approved, git commit then git push sends it to your remote.
If a commit is in progress when a new trigger fires, it's queued and runs immediately after — nothing is ever silently dropped.