AICommit Documentation
A drop-in replacement for git that tracks your AI-assisted development and builds a verified portfolio.
Table of Contents
# 1. Installation
AICommit works on macOS, Linux, and Windows. See the Download page for all options.
macOS / Linux (one-liner)
Auto-detects OS and architecture, downloads the standalone binary (no Node.js needed), and optionally aliases git → aicommit.
macOS (Homebrew)
Windows (PowerShell)
Uses winget, Chocolatey, or Scoop to install git and Node.js if missing.
Windows (Scoop)
npm (any OS with Node.js 18+)
Local Source (Development)
Builds the CLI from source and links it globally via npm link. Useful for local development.
Uninstall
# 2. Getting Started
AICommit replaces git entirely. Use aicommit for every git command — it does everything git does, plus tracks your AI prompts automatically.
aicommit commit runs git commit, then auto-matches prompts to the commit and syncs to the platform.
aicommit push runs git push, then syncs encrypted prompts to your portfolio.
Local Storage Structure
# 3. Git Wrapper
AICommit is a complete git wrapper. Every git command works — you never need to type git again.
Passthrough Commands
These commands pass directly through to git with no extra behavior:
Enhanced Commands
These commands do git operations plus AICommit tracking:
| Command | Description |
|---|---|
| aicommit init | git init + aicommit tracking setup + git hooks |
| aicommit commit -m "msg" | git commit + match prompts + auto-sync to platform |
| aicommit commit -a -m "msg" | Stage all + commit + match + sync (all git flags work) |
| aicommit push | git push + sync prompts to platform |
| aicommit push --no-git | Only sync prompts (skip git push) |
| aicommit push --no-platform | Only git push (skip prompt sync) |
| aicommit commit --no-sync | Only git commit (skip AICommit tracking) |
Dual-Purpose Commands
Some commands have both a git and AICommit meaning. Use the git- prefix for the git version:
| Command | Description |
|---|---|
| aicommit log | AICommit prompt history |
| aicommit git-log | git log (commit history) |
| aicommit tag <id> <tag> | Tag an AICommit prompt |
| aicommit git-tag | git tag (create/list git tags) |
| aicommit status | AICommit tracking status |
| aicommit git-status | git status (working tree status) |
Git Alias (Optional)
The installer offers to alias git → aicommit so even git commit goes through AICommit:
# 4. CLI Commands Reference
Setup & Auth
| Command | Description |
|---|---|
| aicommit login | Authenticate with a CLI token (generated from dashboard) |
| aicommit login --token <token> | Headless / CI authentication |
| aicommit init | git init + tracking setup + git hooks |
| aicommit init --private | Initialize with all prompts set to private |
| aicommit init --bare | Create a bare git repository |
| aicommit status | Show tracking status, branch stats, last sync |
| aicommit status --json | Output status as JSON (for scripts/hooks) |
Tracking & History
| Command | Description |
|---|---|
| aicommit prompt "text" --model=copilot | Log a prompt manually |
| aicommit log | View all prompts (paginated, color-coded) |
| aicommit log --last 20 | Show last 20 prompts |
| aicommit log --model claude | Filter by AI model name |
| aicommit log --branch feature-x | Filter prompts by git branch |
| aicommit log --since 2d | Prompts from the last 2 days |
| aicommit show <commit-sha> | Show prompts matched to a specific commit |
| aicommit show HEAD | Prompts matched to the latest commit |
| aicommit branches | List all branches with prompt/commit counts |
| aicommit tag <id> <tag> | Add a tag to a prompt |
| aicommit note <id> "text" | Add a note to a prompt |
Commit, Push & Sync
| Command | Description |
|---|---|
| aicommit commit -m "msg" | git commit + match prompts + auto-sync |
| aicommit push | git push + sync prompts to platform |
| aicommit push --dry-run | Preview what will be synced |
| aicommit push --review | Interactively approve each prompt |
| aicommit push --branch main | Push only prompts from a specific branch |
| aicommit sync | Re-match unmatched prompts to commits |
| aicommit sync --force | Full re-run of matching on all prompts |
Privacy & Visibility
| Command | Description |
|---|---|
| aicommit privacy | Interactive privacy manager — scan for secrets |
| aicommit redact <id> | Redact sensitive content from a prompt |
| aicommit set-public <id> | Make a prompt publicly visible |
| aicommit set-private <id> | Make a prompt private |
Security & Certificates
| Command | Description |
|---|---|
| aicommit setup-certs | Generate local CA certificates for HTTPS proxy interception |
| aicommit push --skip-scan | Skip secret scanning before sync |
# 5. Proxy Interceptor
The local proxy runs on localhost:7331 and transparently captures AI API calls from any tool that makes HTTP requests. It works with direct API calls and IDE integrations alike.
Supported Integrations
API / Direct
- OpenAI API
- Anthropic API
- Google Gemini API
- Groq / Together / Fireworks
- Ollama (local)
- LM Studio (local)
IDE / Tool
- GitHub Copilot (LSP hook)
- Cursor IDE (proxy setting)
- Windsurf / Codeium
- Aider (chat history file)
- Continue.dev (config hook)
- VS Code Extension
Each intercepted request is parsed by a provider-specific handler that extracts the prompt text, response, model name, temperature, and token usage. Data is stored locally in .aicommit/history.db.
# 6. Prompt-to-Commit Matching
AICommit uses a weighted scoring algorithm to link prompts to git commits. Matching runs automatically on aicommit commit, or manually with aicommit sync.
Signal Weights
Files open at prompt time match files changed in commit
Prompt and commit are on the same git branch
Prompt within 90 minutes before commit
Prompt words appear in commit message or diff
AI response code appears (fuzzy) in git diff
Same session as a previously matched prompt
Confidence Levels
# 7. Branch-Aware Tracking
AICommit tracks which git branch each prompt and commit belongs to. When you switch branches, the post-checkout hook records the change. All filtering supports branch context.
CLI Branch Features
How It Works
- →Post-commit hook records the current branch with each commit
- →Post-checkout hook writes the active branch to .aicommit/.current-branch
- →Proxy interceptor tags each captured prompt with the current branch
- →Matching algorithm uses branch match as a 20% weighted signal
# 8. Privacy & Redaction
AICommit has three layers of privacy protection. Your data stays on your machine until you decide to share it.
All data stored in .aicommit/history.db on your machine. Nothing transmitted until aicommit push.
AES-256 encryption at rest. TLS 1.3 for all data in transit to the platform.
Each prompt can be Public, Private, or Redacted. You control what the world sees.
Auto-Redaction Engine
The redaction engine scans prompts for sensitive content before push:
- ⚠API keys and tokens (AWS, OpenAI, Stripe, etc.)
- ⚠Passwords and secrets
- ⚠PII — emails, phone numbers, addresses
- ⚠IP addresses and internal URLs
- ⚠SQL literals and connection strings
Redaction is advisory — it warns and asks for confirmation, never silently alters your data.
# 9. Authentication
AICommit uses token-based authentication. No passwords are stored on your machine.
Setup
Token Management
From the dashboard, you can:
- →Generate tokens with custom names and expiry (30/60/90/180/365 days)
- →View active tokens with last-used timestamps
- →Revoke tokens instantly
Tokens are SHA-256 hashed before storage — the platform never stores your raw token.
# 10. Web Dashboard
Your profile page at aicommit.vercel.app/username is your dashboard. When logged in, you see the full dashboard experience — when others visit, they see your public profile.
Dashboard Features (Owner View)
Navigation
When logged in, the nav bar shows: Overview, CLI Tokens, Settings, Import Repo. The old /dashboard URL redirects to /username automatically.
# 11. Public Profiles
Every developer gets a profile at aicommit.vercel.app/username. It works like GitHub — your profile is both your public page and your dashboard.
Owner vs Visitor View
| Command | Description |
|---|---|
| Owner (logged in) | Sees nav tabs (Tokens, Settings, Import), CLI setup guide, private prompts, quick links |
| Visitor | Sees public projects, public prompts, stats, activity graph, model chart |
Profile Includes
Project Detail Pages
Click any project to open aicommit.vercel.app/username/project showing:
- →Model attribution bar with percentage breakdowns
- →AI Score (computed from prompt + commit activity)
- →Full prompt timeline with branch filtering
- →Visibility badge (🌐 Public / 🔒 Private)
- →Clickable repo link (GitHub / GitLab / Bitbucket)
- →Project info sidebar with stats
# 12. Repo Import
Import public repositories from GitHub, GitLab, or Bitbucket directly from the dashboard.
# 13. AI Workflow Builder
Document your AI-assisted development processes as step-by-step workflows. Share them with the community or keep them private.
Workflow Steps
Each workflow is a sequence of steps with:
- →Title and description
- →AI tool/model used
- →Prompt template or example
- →Expected output or outcome
- →Tips and notes
# 14. Secret Scanning
Before syncing prompts to the platform, AICommit scans for secrets using Shannon entropy analysis and known secret patterns.
What It Detects
- ⚠High-entropy strings (Shannon entropy > 4.5 for strings > 20 chars)
- ⚠AWS access keys and secret keys
- ⚠GitHub / GitLab / Bitbucket tokens
- ⚠Private key headers (RSA, EC, etc.)
- ⚠JWT tokens and database connection strings
- ⚠OpenAI, Anthropic, Stripe API keys
Behavior on Push
When secrets are found, you get three options:
| Command | Description |
|---|---|
| Redact all | Auto-redact flagged secrets and continue push |
| Skip flagged | Skip prompts with secrets, sync the rest |
| Abort | Cancel the push entirely |
In CI/headless mode (no TTY), secrets are auto-redacted by default.
# 15. .aicommitignore
Exclude files from proxy tracking with a .aicommitignore file in your repo root. Uses gitignore-compatible glob syntax.
Default Patterns
How It Works
When the proxy intercepts an AI API call, it checks the active_files context. If any file matches an ignore pattern, the entire prompt is discarded and not stored in the local database.
Supports *, **, ! negation, and # comments.
# 16. Certificate Management
For HTTPS-only AI APIs, AICommit can generate local CA certificates for proxy interception.
What It Does
- →Generates a CA root certificate and private key in ~/.aicommit/certs/
- →Checks for existing certs before overwriting
- →Shows platform-specific trust instructions (macOS Keychain, Linux ca-certificates, Windows Certificate Store)
If certs are missing when the proxy starts, it falls back to HTTP-only mode with a warning.
# 17. CI / Headless Mode
AICommit works in CI pipelines and automated scripts. When no TTY is detected, interactive prompts are skipped and safe defaults are applied.
Setup
Headless Behavior
| Command | Description |
|---|---|
| Secret scanning | Auto-redacts flagged secrets (no interactive prompt) |
| Push --review | Skipped in headless mode (all prompts synced) |
| Token auth | CLI tokens (act_...) work without browser OAuth |
# 18. MCP Server (IDE Integration)
AICommit includes a built-in MCP (Model Context Protocol) server that integrates with IDEs like Cursor, Windsurf, and VS Code. It exposes tools that allow AI agents to log prompts directly into your local history.
Setup
Exposed Tools
| Command | Description |
|---|---|
| log_prompt | Log a prompt with model name, text, response, temperature, active files, and branch |
| get_session_info | Get current session ID, project directory, branch, and prompt count |
IDE Configuration
The MCP config is written to .cursor/mcp.json (for Cursor) during aicommit init. For other IDEs, add the server config manually:
The MCP server uses the absolute path to your Node.js binary to avoid PATH issues in IDE environments.
# 19. Settings & GDPR
Manage your data usage preferences and exercise your right to data erasure from the dashboard.
Data Usage Toggle
Under Dashboard → Settings, toggle "Allow anonymized prompts for platform-wide trend analysis". Default is OFF. When off, your prompts are excluded from all aggregation and analytics.
Delete Project Data (GDPR)
On any project settings page, use "Delete Forever" to permanently remove all prompts, commits, links, and project metadata. Requires typing the project name to confirm. Deletion is logged in the audit trail.
Contribution Heatmap
Public profiles show a contribution heatmap with daily activity counts. For private repos, only the date and count are shown — no prompt text, repo names, or file names are revealed.
# 20. API Reference
The platform exposes REST API routes. Authenticated routes accept either a session cookie or a CLI token via Authorization: Bearer <token> header.
Endpoints
| Command | Description |
|---|---|
| POST /api/auth | Login with username/password, returns session cookie |
| POST /api/auth/register | Create a new account |
| GET /api/auth/session | Check current session status |
| GET /api/auth/me | Get authenticated user (supports JWT + CLI token) |
| POST /api/sync | Push prompts, commits, links from CLI (supports JWT + CLI token) |
| GET /api/branches | List branches with stats for authenticated user |
| GET /api/profiles | List all developer profiles |
| GET /api/profiles/:username | Get a specific developer profile |
| GET /api/projects | List projects for authenticated user |
| POST /api/import | Import a public repo from GitHub/GitLab/Bitbucket |
| GET /api/search?q=... | Search developers by name, model, or keyword |
| GET /api/tokens | List CLI tokens for authenticated user |
| POST /api/tokens | Generate a new CLI token |
| DELETE /api/tokens | Revoke a CLI token |
| GET /api/settings | Get user settings (analytics toggle) |
| PATCH /api/settings | Update user settings |
| DELETE /api/projects/:id | GDPR delete — permanently remove project and all data |
| GET /api/heatmap/:username | Contribution heatmap data (daily activity counts) |
| POST /api/hooks/github | GitHub webhook receiver |
| POST /api/hooks/gitlab | GitLab webhook receiver |
| POST /api/hooks/bitbucket | Bitbucket webhook receiver |
Sync Payload (CLI Push)
# 21. Plans & Pricing
- ✓ 5 projects
- ✓ 10 prompts
- ✓ 1 workflow
- ✓ Basic repo import
- ✓ Public profile
- ✓ Unlimited projects
- ✓ Unlimited prompts
- ✓ Unlimited workflows
- ✓ Analytics dashboard
- ✓ Verified badge
- ✓ Priority search
- ✓ Everything in Pro
- ✓ Team dashboard
- ✓ Org analytics
- ✓ Shared workflows
- ✓ API access
# 22. Troubleshooting
aicommit status shows 0 prompts
The proxy interceptor must be running to capture AI API calls. Check:
- →Run aicommit proxy to start the proxy on localhost:7331
- →Ensure your AI tool is configured to use the proxy (HTTP_PROXY=http://localhost:7331)
- →For Cursor/VS Code, check that the MCP server is enabled in IDE settings
- →Verify .aicommit/ directory exists in your project (run aicommit init if not)
MCP server shows as disabled in Cursor
- →Open Cursor Settings → MCP and manually enable the aicommit server
- →Check .cursor/mcp.json exists and has the correct node path
- →Re-run aicommit init to regenerate the MCP config with the correct absolute node path
- →Restart Cursor after enabling the MCP server
MCP server works but 0 prompts tracked
MCP tool usage is soft enforcement — the IDE agent may not automatically call log_prompt on every interaction. This is a known limitation.
- →Add a .cursorrules file instructing the agent to call log_prompt after every response
- →Use the proxy interceptor as the primary capture method instead of MCP
- →Log prompts manually with aicommit prompt "text" --model=cursor
aicommit push fails with 'Not logged in'
- →Run aicommit login and enter your CLI token
- →Generate a token from your profile → CLI Tokens tab
- →Check ~/.aicommit/config.json has a valid token
aicommit push --no-git for branches without upstream
If your branch has no upstream remote, aicommit push will fail on the git push step. Use:
Private repo prompts not visible on profile
Private repo prompts are synced with private visibility by default. They are only visible when you are logged in and viewing your own profile. Visitors cannot see them.
- →Log in to see your private prompts at aicommit.vercel.app/username
- →Use aicommit set-public <id> to make individual prompts public
Project page shows 404
Project names that contain slashes (e.g., org/repo) are URL-encoded. If you get a 404:
- →Click the project from your profile page — the link is auto-encoded correctly
- →If typing manually, use %2F instead of / in the project name
Proxy not capturing HTTPS API calls
- →Run aicommit setup-certs to generate local CA certificates
- →Trust the CA cert in your OS keychain (instructions shown after setup)
- →Set NODE_EXTRA_CA_CERTS=~/.aicommit/certs/ca.pem for Node.js tools
- →Without certs, the proxy falls back to HTTP-only mode
Secret scanner false positives
- →Use aicommit push --skip-scan to bypass scanning for trusted workflows
- →Choose "Skip flagged" during interactive push to skip only flagged prompts
- →The scanner uses Shannon entropy (>4.5) — long random strings may trigger it
Database locked or corrupted
- →Close all aicommit processes and IDE instances
- →Delete .aicommit/history.db-wal and .aicommit/history.db-shm (WAL files)
- →If still broken, back up and delete .aicommit/history.db, then re-run aicommit init