loco turns Git diffs into 3 high-signal commit drafts using a local model through Ollama. It is designed for teams that want clearer history, faster reviews, safer incident debugging, and zero source-code exposure to hosted AI tools.

The Problem

Bad commit messages look harmless until a team needs the history for something important.

That pain shows up everywhere in software:

• code reviews slow down because intent is missing
• release prep gets messy when change history is vague
• debugging old regressions turns into archaeology
• developers lose focus at the last 30 seconds of a task
• privacy-conscious teams cannot send internal diffs to cloud APIs

loco is built for that exact gap. It handles the small but repeated documentation step between “code is done” and “commit is written”, then keeps the whole workflow local.

What improves with loco?

| Without discipline | With loco | |---|---| | Commit messages decay under deadline pressure | The CLI drafts useful commit options from the diff | | Git history becomes noisy and hard to search | History stays readable and operationally useful | | Local-first teams avoid AI entirely | AI assistance stays inside the machine | | Hooks can become brittle and disruptive | Hook mode fails open and stays out of the way |

Features

Protect Developer Focus Finishing a task should not end with staring at a blank commit prompt. loco drafts the wording so engineers can close work without losing momentum.

Private By Default Runs through your local Ollama runtime. No external API calls, no vendor lock-in, no diff data leaving the machine.

History That Helps Later Outputs conventional commit style messages that remain useful during reviews, release notes, blame sessions, and future maintenance.

Human Review Built In You get three drafts, then decide what happens next: choose one, edit one, regenerate, or cancel.

Fits Existing Team Habits Use it as an interactive CLI, as a copy-to-clipboard helper for IDE workflows, or as a Git hook for standard terminal commits.

Practical Hook Mode Installs a prepare-commit-msg hook that pre-fills commit text without hijacking merge, squash, or manually supplied messages.

Low-Friction Setup Checks Ollama, starts the local service when possible, and pulls a default model so the first-run experience stays short.

Model Flexibility Start with a lightweight default and switch to larger Ollama models whenever your machine or quality bar allows it.

Quick Start

1. Install

npm install -g loco-ai

Requires: Node.js >= 18 and Ollama

2. Set up Ollama

# macOS
brew install ollama

# or download the desktop app
# https://ollama.com/download

Then run:

loco setup

loco setup checks that Ollama is installed, starts the service if necessary, and pulls the default model: qwen2.5-coder:1.5b.

3. Generate your commit

git add .
loco commit

If you skip loco setup, the commit and message flows can guide you through setup on first use.

Commands

| Command | Description | |---------|-------------| | loco commit | Generate 3 suggestions, pick one, and commit | | loco message | Generate suggestions without committing | | loco msg | Alias for loco message | | loco setup | Verify Ollama and pull the default model | | loco init | Install the git hook | | loco models | List installed models and manage them interactively | | loco pull <model> | Pull a model from the Ollama library | | loco config | Show current config and choose the default model | | loco config --model <name> | Set the default model directly | | loco doctor | Run environment health checks |

Usage

Basic workflow

# Stage your changes
git add src/cli.js src/commands/commit.js

# Generate 3 suggestions and pick one
loco commit

Output:

? Pick a commit message:
> 1. feat(cli): add interactive commit message selection flow
  2. refactor(commit): simplify local diff analysis before generation
  3. chore(ollama): improve setup flow for local model startup
  ↻ Regenerate
  ✎ Edit manually
  ✖ Abort

Instead of forcing engineers to invent phrasing from scratch, loco turns the diff into decision-ready options.

Generate a message without committing

git add .
loco msg

Pick one of the generated messages and loco copies it to your clipboard so you can paste it into your IDE or Git client.

This mode is especially useful when a team commits through GUI tools but still wants consistent, high-quality commit language.

Install the git hook

loco init
git add .
git commit

The hook pre-fills the commit message file for regular commits. If you already pass -m, or Git is creating a merge, squash, or similar special commit message, loco stays out of the way instead of fighting the workflow.

Check your environment

loco doctor

This verifies:

• Ollama is installed
• Ollama is running
• Your default model is available
• The current directory is a Git repository

Models

loco works with any model available through the Ollama library. The default is qwen2.5-coder:1.5b because commit drafting is a short, focused task where startup speed matters more than heavyweight general reasoning.

| Model | Approx. Size | Speed | Notes | |-------|--------------|-------|-------| | qwen2.5-coder:1.5b | Small | Fastest | Default, lightweight | | llama3.2:1b | Small | Fast | Good alternative | | codellama | Medium | Medium | More code-oriented | | mistral:latest | Medium | Medium | Stronger language quality | | llama3.1 | Large | Slower | Best if you want richer phrasing |

Pull and switch models

# Pull a new model
loco pull codellama

# Pick the active model interactively
loco config

# Or set it directly
loco config --model codellama

Browse installed models

loco models

This opens an interactive menu where you can:

• view installed models
• set the active model
• pull another model

Configuration

Config is stored at ~/.loco/config.json.

The configuration surface is intentionally small. loco is meant to disappear into the workflow, not become another tool that needs constant tuning.

Example config

{
  "defaultModel": "qwen2.5-coder:1.5b",
  "setupComplete": true
}

Update config

# Show current config and choose interactively
loco config

# Set directly
loco config --model llama3.2:1b

How It Works

git add .  ->  loco commit  ->  Ollama (local)  ->  choose/edit  ->  git commit

1. Reads your staged diff first.
2. If nothing is staged, the interactive flow can fall back to the current Git diff.
3. Large diffs are truncated to roughly 4000 characters before sending them to the model.
4. The prompt asks the local model for exactly 3 conventional commit suggestions.
5. You select one, edit it, regenerate, or cancel.
6. On approval, loco runs git commit -m ....

With loco init, the hook flow is slightly different: Git hands loco the commit message file, and loco writes the first generated suggestion into it without blocking commits on failure.

The core idea is simple: if commit quality drops because writing them is tedious, the fix is to reduce the friction without removing human judgment.

Git Hook

Install loco as a prepare-commit-msg hook:

loco init

After that:

git add .
git commit

Your editor opens with a generated commit message already filled in.

Note: The hook intentionally skips commits that already have a message, such as git commit -m "...", merge commits, squash commits, and similar non-standard commit flows.

FAQ

Because commit messages are not cosmetic. They affect review speed, release traceability, bug forensics, and team communication. Most teams know this, but under pressure they still ship weak messages. loco makes the better default faster than the rushed one.

No. loco talks only to your local Ollama instance at http://localhost:11434.

No. If Ollama is installed and a model is available, that's enough.

loco tries to start ollama serve automatically. If that fails, it tells you how to start Ollama manually.

Choose another draft, regenerate, or edit manually. The product is designed to shorten the wording step, not to force an opaque one-shot answer.

Yes. loco message and loco msg generate suggestions without creating a commit and copy the selected message to your clipboard.

No. The hook is designed to fail silently so normal Git usage keeps working even if generation fails.

Requirements

• Node.js >= 18
• Git
• Ollama
• An Ollama model such as qwen2.5-coder:1.5b

License

MIT