README

Devlog

AI-Powered Development Log Generator — Privacy-First, Local-First

Transform Git history into intelligent, human-readable changelogs. Analyze actual code changes with AI while keeping your data secure through local-first processing.

Quick Start

# Install
cargo install --git https://gitlab.com/aice-lab/devlog.git

# Generate changelog (plain mode, outputs to stdout)
devlog

# Generate with AI analysis
devlog --llm ollama:llama3 -o CHANGELOG.md

# View all options
devlog --help

Commands

Running devlog with no subcommand still does exactly what it always did, so every existing invocation and flag below keeps working unchanged.

Global flags, accepted before or after any subcommand:

Log-only flags (devlog and devlog log): --group-by-type, --group-features, --authors, --include-merges, --no-diff, --release-notes, --dry-run, --estimate-cost.

Data goes to stdout, progress and prompts go to stderr, so --format json is safe to pipe. Exit codes: 0 success, 1 a verify mismatch or a failed run, 2 usage error, 3 provider or configuration unusable.

Providers

devlog providers list reports every provider, on-device first. Cloud providers are read from key presence only — no API call is ever made.

apple is Apple Foundation Models: the on-device model on macOS 26 or later, reached through a small devlog-afm helper that ships inside the desktop app (point DEVLOG_AFM_HELPER at one to use it from the CLI). No key, no cost, no network. It serves one model, system, in a fixed 4096-token context window shared by prompt and answer — a prompt that does not fit is refused with the limit named, never truncated, which is what --group-features over many commits will run into.

The server-backed local providers (ollama, lmstudio, mlx) are reported in three states, so a local model is never a dead end:

• not installed — no runtime binary on PATH
• installed, not running — the binary is there, nothing answers the endpoint
• running — the endpoint answered; ollama and LM Studio also report their models

Endpoints default to http://localhost:11434 (ollama), http://localhost:1234 (LM Studio) and http://localhost:8080 (mlx), overridable with DEVLOG_OLLAMA_URL, DEVLOG_LMSTUDIO_URL and DEVLOG_MLX_URL. Probes use a one-second timeout.

llamacpp is deprecated: Ollama’s MLX backend covers what it was for, so it is no longer listed or offered. It still works — --llm llamacpp:MODEL and DEVLOG_LLAMACPP_URL are unchanged.

--format json adds installed, running and models to every local row, plus a hint naming the commands that would make the provider usable.

devlog providers check --llm ollama:MODEL exits 3 when the runtime is missing or stopped, or when MODEL was never pulled, and prints the exact commands to fix it (ollama treats a bare name as :latest, so llama3.2 matches llama3.2:latest).

devlog providers start ollama runs ollama serve in the background and re-probes for up to ten seconds; devlog providers start lmstudio does the same with lms server start. mlx and llama.cpp are never started for you — they need a model chosen first, so run mlx_lm.server --model <model> or llama-server -m <model.gguf> yourself.

devlog never installs anything and never pulls a model. It only tells you the command:

The desktop app shows the same three states under Settings → AI Models, with a Start button for a stopped ollama and a copyable command for everything else.

Agent Skill

skill/ packages devlog for AI coding agents (Claude Code, opencode, Cursor) — commands, --format json shapes, exit codes, and a CI-gate recipe for devlog verify. See skill/README.md for where to install it. The desktop app can also save it from Settings → General → Integrations.

Key Features

✅ Privacy-First — Works entirely offline with local LLMs (Ollama, llama.cpp)
✅ Zero Network Access — Code diffs never leave your machine
✅ Smart Analysis — Groups commits into logical units, analyzes actual code changes
✅ Multiple Providers — Apple Foundation Models (on-device), Ollama, LM Studio, MLX, Claude, OpenAI, OpenRouter, or plain mode
✅ Flexible Output — Markdown, JSON, with filtering and grouping

Documentation

Full documentation available at: ananno.gitlab.io/devlog

• Getting Started — Installation & setup
• Configuration Guide — API keys, providers, options
• Features & Examples — Full feature reference
• Troubleshooting — Common issues & solutions

Installation

From Source (Recommended)

cargo install --git https://gitlab.com/aice-lab/devlog.git

Specific Version

cargo install --git https://gitlab.com/aice-lab/devlog.git --tag v1.1.0

Build Locally

git clone https://gitlab.com/aice-lab/devlog.git
cd devlog && cargo build --release
./target/release/devlog --help

Requirements

• Rust 1.70+
• Git repository (to analyze)
• Optional: API key for cloud LLMs (Claude, OpenAI, OpenRouter)
• Optional: Apple Foundation Models (macOS 26+), or a local LLM server (Ollama, LM Studio, MLX)

Examples

Generate Changelog (Plain Mode)

devlog -o CHANGELOG.md

AI-Powered Analysis with Local LLM

devlog --llm ollama:llama3 -o CHANGELOG.md

AI-Powered Analysis with Cloud LLM

devlog --llm anthropic:claude-sonnet-4-5 -y -o CHANGELOG.md

Version Range

devlog -f v1.0 -t v2.0 -o CHANGELOG.md

Group by Type

devlog --group-by-type -o CHANGELOG.md

Group by Logical Features (Requires LLM)

devlog --llm ollama:llama3 --group-features -o CHANGELOG.md

Export as JSON

devlog --format json -o changelog.json

Include Author Attribution

devlog --authors -o CHANGELOG.md

Disable Diff Analysis with LLM

devlog --llm ollama:llama3 --no-diff -o CHANGELOG.md

Check Commit Messages Against the Code (CI Gate)

devlog verify --llm ollama:llama3 --from v2.0.0

Plain-Language Update for a Client

devlog report --template client --llm ollama:llama3 -f v1.0 -t v2.0

Machine-Readable Output for an Agent

devlog verify --llm ollama:llama3 --format json

Pin a Reference and Reuse It

devlog checkpoint save release --ref v2.0.0
devlog log --from @release

Configuration

Set default LLM via environment variable:

export DEVLOG_LLM=ollama:llama3
devlog  # Uses Ollama with llama3 by default

Or create devlog.toml:

[defaults]
llm = "ollama:llama3"
format = "markdown"

See Configuration Guide for details.

Architecture

• Git Analysis — Parses history, identifies commit types (PR, merge, direct)
• Code Diff Processing — Analyzes actual changes, not just messages
• Smart Filtering — Removes noise (whitespace, formatting changes)
• LLM Integration — Optional AI summarization or plain mode
• Output Generation — Markdown or JSON changelog

Privacy: Works offline by default. Cloud providers optional & explicit opt-in.

License

MIT License — See LICENSE file

Contributing

Contributions welcome! See CONTRIBUTING.md for guidelines.

Questions? Check the troubleshooting guide or open an issue on GitLab.

This is a snapshot generated from GitLab. For the live README, see the project page.