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
brew tap aice-lab/tap https://gitlab.com/aice-lab/homebrew-tap.git
brew install devlog

# 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.

Command	What it does	Example
log	Development log; the default when no subcommand is given	devlog log -f v1.0 -t v2.0
report --template <T>	release-notes, devlog or client output	devlog report --template client --llm ollama:llama3
verify	Checks each commit message against the code it changed; exits 1 on a mismatch	devlog verify --llm ollama:llama3
sync	Fills the analysis cache, renders nothing	devlog sync --llm ollama:llama3
cache <stats|clear>	Inspect or empty the analysis cache	devlog cache stats
providers <list|check|start>	Which providers are usable, and starting a local one	devlog providers check --llm ollama:llama3
checkpoint <save|list|rm>	Named references, usable as @NAME in --from/--to	devlog checkpoint save release --ref v2.0.0
usage	Cached analysis rollups per repository and per month	devlog usage

Global flags, accepted before or after any subcommand:

Flag	What it does
-f, --from / -t, --to	Reference range; @NAME resolves a checkpoint
-o, --output <FILE>	Write to a file instead of stdout
--format <markdown|json>	Output format; JSON works on every subcommand
--llm <PROVIDER:MODEL>	Enables diff analysis (ollama:llama3, anthropic:claude-sonnet-5-5, …)
-n, --limit <N>	Maximum number of commits
-y, --yes	Answer every prompt in advance (CI)
--quiet	Silence progress on stderr
--repo <PATH>	Repository to read
--privacy <strict|moderate|relaxed>	Sanitization level for cloud providers
--no-cache	Ignore the analysis cache for this run

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 and devlog providers start mlx do the same with lms server start and mlx_lm.server. A bare mlx_lm.server loads whatever model each request names, which is what devlog sends. llama.cpp is never started for you — it needs a model file chosen first, so run llama-server -m <model.gguf> yourself.

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

	macOS	Linux
ollama	brew install ollama	curl -fsSL https://ollama.com/install.sh | sh
LM Studio	brew install --cask lm-studio	download
mlx	brew install mlx-lm	pip install mlx-lm

The desktop app shows the same three states under Settings → AI Models, with a Start button for a stopped ollama, LM Studio or mlx, 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

Homebrew (Recommended)

brew tap aice-lab/tap https://gitlab.com/aice-lab/homebrew-tap.git
brew install devlog

One tap serves every aice-lab tool, so the same brew tap also gives you envkit. Upgrades come with brew upgrade devlog.

From Source

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-5-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.