CommitLoom

         ✦   ˚   ✦
        ╭─────────╮
        │  ◕   ◕ │
        ╰────┬────╯
  ◉━━━━━━━━━━┻━━━━━━━━━━◉
  ┃   ╭─────────────╮    ┃
  ┃   │ ●  ───────  │    ┃
  ┃   │    ───────  │    ┃
  ┃   │    ─────    │    ┃
  ┃   │ ●  ───────  │    ┃
  ┃   ╰─────────────╯    ┃
  ◉━━━━━━━━━━━━━━━━━━━━━◉

    commitloom · git loom · weave your commits

Stop burning tokens on commit messages.
Because fix stuff is not a commit message. Reads your staged diff, follows your rules, outputs a clean commit — then politely asks before pulling the trigger.

Install

npm install -g commitloom
cloom install            # register git loom as a native git subcommand

Quick start

cloom init      # creates .commitloom.yml and .commitloom.md in your repo
git add .
git loom        # generate and confirm commit

Usage

git loom works like any built-in git command — no aliases, no shell config:

git loom                          # generate and confirm commit
git loom -- --ticket PROJ-42      # inject context variables
git loom -- --scope auth --breaking-change

cloom install creates a git-loom executable in ~/.local/bin (or /usr/local/bin). Git finds commands named git-<name> in the PATH automatically.

To remove it:

cloom uninstall

Commands

| Command | Description | |---------------------------------|-------------------------------------------------------------| | cloom install | Register git loom as a native git subcommand | | cloom uninstall | Remove the git loom subcommand | | cloom init | Initialize config and instruction files in the current repo | | cloom c | Same as git loom (direct alias) | | cloom c --config <path> | Override config file for this run | | cloom c --instructions <path> | Override instruction file for this run | | cloom c --verbose | Show prompt and raw LLM response |

Configuration (.commitloom.yml)

Gitignored by default — safe to store API keys here.

provider: ollama
model: qwen2.5-coder:7b
baseUrl: http://localhost:11434
apiKey: null
timeoutMs: 30000
temperature: 0.2
maxTokens: 512

Providers

| Provider | provider value | Notes | |----------------------------------------|------------------|----------------------------------------| | Ollama | ollama | Local, free, no key needed | | LM Studio | lmstudio | Local, free, no key needed | | OpenAI | openai | Needs apiKey or OPENAI_API_KEY | | OpenRouter | openrouter | Needs apiKey or OPENROUTER_API_KEY | | Anthropic | anthropic | Needs apiKey or ANTHROPIC_API_KEY |

Provider examples:

# Ollama (local)
provider: ollama
model: qwen2.5-coder:7b

# LM Studio (local — start the server in LM Studio → Developer tab)
provider: lmstudio
model: gemma-4-e2b-it
baseUrl: http://localhost:1234/v1

# OpenAI
provider: openai
model: gpt-4o-mini
apiKey: sk-...

# Anthropic
provider: anthropic
model: claude-haiku-4-5-20251001
apiKey: sk-ant-...

Customizing rules (.commitloom.md)

Committed to your repo and shared with the team. Contains the instructions sent to the LLM on every run. Requires a YAML frontmatter block:

---
system: "You are a git commit message generator."
language: en
final: "Generate the commit message now. Only the message, no explanation."
---

Follow Conventional Commits. Keep the subject under 72 characters.

| Field | Required | Description | |------------|----------|-----------------------------------------------------------| | system | No | Overrides the LLM system role | | language | No | Forces output language (en, pt-BR, es, fr…) | | final | No | Overrides the closing instruction appended after the diff |

Context variables

Inject runtime values into the LLM prompt by passing them after --:

git loom -- --task-id 1001
git loom -- --ticket PROJ-42 --scope payments

Use {{key}} placeholders in .commitloom.md to interpolate them:

This commit is related to task #{{task-id}}.

Ollama setup (local, free)

1. Install Ollama — https://ollama.com/download
2. Pull a model — downloads it to your machine (~GB, one-time):

ollama pull qwen2.5-coder:7b

3. Use it — set the model name in .commitloom.yml:

provider: ollama
model: qwen2.5-coder:7b

To switch models later, just pull the new one and update the config:

ollama pull qwen2.5-coder:7b
# then update .commitloom.yml: model: codellama:13b

Available models:

| Model | RAM | GPU VRAM | CPU? | Quality | |-------------------------|-------|----------|-------------------|-----------| | qwen2.5-coder:32b | 24 GB | 20 GB | ⚠️ impractical | Excellent | | qwen3:32b | 24 GB | 20 GB | ⚠️ impractical | Excellent | | deepseek-coder-v2:16b | 16 GB | 12 GB | ⚠️ very slow | Very good | | phi4-mini | 4 GB | 3 GB | ✅ fast | Good | | codellama:13b ⭐ | 12 GB | 10 GB | ✅ slow | Good | | qwen2.5-coder:7b ⭐ | 8 GB | 6 GB | ✅ slow | Good | | qwen3:8b | 8 GB | 6 GB | ✅ slow | Better | | phi4:14b | 10 GB | 8 GB | ✅ slow | Very good | | qwen2.5-coder:14b | 12 GB | 10 GB | ✅ very slow | Better | | qwen3:14b | 12 GB | 10 GB | ✅ very slow | Very good | | devstral | 16 GB | 14 GB | ❌ not recommended | Excellent | | hf.co/unsloth/gemma-4-E2B-it-GGUF:UD-Q8_K_XL | ~3 GB | ~3 GB | ✅ fast | Very good |

Recommendations:

• CPU only (fast) — phi4-mini: 4 GB RAM, runs without a GPU, though results are not as precise
• CPU only (precise) — qwen2.5-coder:7b ⭐: a bit slower on CPU but noticeably more accurate commit messages
• Hugging Face via Ollama — hf.co/unsloth/gemma-4-E2B-it-GGUF:UD-Q8_K_XL: Gemma 4 quantized by Unsloth; showed consistently good results in testing — worth trying if you want a lightweight model beyond the standard Ollama library

Models ≤ 8B are usable on CPU (3–10 tokens/s). Apple Silicon handles larger models better due to unified memory.

Requirements

• Node.js 18+
• Git
• A running LLM (Ollama locally, or an API key for cloud providers)

License

MIT © Lucian Caetano