kairos

module
v0.4.6 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jul 16, 2026 License: Apache-2.0

README

Kairos

Kairos is a Git Context Engine that understands a project's history to generate high-quality commit messages, tag messages, release notes, and changelog entries using LLMs.

The best commit message is written by understanding the project's history.

Philosophy

Kairos is not just an AI commit message generator. It builds rich context from your Git repository — history, branches, tags, changed files, project type — before asking any LLM for output.

Features (Phase 1)

  • 🔍 Git Context Engine — collects staged diff, branch, recent commits, last tag, changed files, project type, README/CHANGELOG excerpts
  • 🤖 LLM Providers — Ollama (default), OpenAI-compatible (OpenAI, LM Studio, GoModel gateway), with pluggable interface for Anthropic, Gemini, OpenRouter
  • 📝 Conventional Commits — structured JSON output parsed into type, scope, subject, body, and breaking changes
  • ⚙️ Configurable — platform-native config dir (via go-appdir), KAIROS_* environment variables, CLI flags
  • 🌍 Localized CLI messages — Kairos's own errors (e.g. the not-a-git-repo message) follow language/--language/KAIROS_LANGUAGE if set, else the system locale (LC_ALL/LC_MESSAGES/LANG), else English (currently en/de)
  • 🧪 Fully Tested — unit tests with mocked Git and provider dependencies, no network required

Quick Start

Prerequisites
  • Go 1.26+
  • Git
  • Ollama (default provider) with a model like qwen3:30b
Install
go install github.com/afeldman/kairos/cmd/kairos@latest
Usage

Generate a commit message:

git add .
git commit -am "$(kairos)"

Or using kairos commit:

git add .
kairos commit

With a different model:

kairos -m llama3.2:3b
Configuration

Create config.yaml in Kairos's platform config dir (macOS: ~/Library/Application Support/kairos, Linux: ~/.config/kairos, Windows: %APPDATA%\kairos):

provider: ollama
model: qwen3:30b
temperature: 0.2
history: 20
style: conventional
language: english
update_changelog: true
LM Studio (macOS)

LM Studio only exposes an OpenAI-compatible API, no native Ollama API. Start the local server in LM Studio (default http://localhost:1234/v1), then:

kairos --provider lmstudio --model <loaded-model-name>

Or in config.yaml:

provider: lmstudio
model: qwen2.5-coder-14b-instruct
# base_url: http://localhost:1234/v1   # only needed if not the default
GoModel gateway (optional)

To route through a GoModel gateway (multi-provider routing, cost tracking, observability) instead of talking to LM Studio directly, point Kairos at the gateway's endpoint (default http://localhost:8080/v1):

kairos --provider gomodel --model gpt-5-chat-latest --api-key "$GOMODEL_KEY"

GoModel is a separate service (Docker/binary), not a Go dependency of Kairos — run it alongside and configure its own OPENAI_LMSTUDIO_BASE_URL etc. to reach LM Studio. --base-url overrides the endpoint for any of openai, lmstudio, or gomodel if not running on the default port.

Commands

Command Description
kairos Generate commit message (default)
kairos commit Generate commit message
kairos tag Generate annotated tag message
kairos release Generate release notes
kairos changelog Update or generate CHANGELOG.md
kairos explain Explain staged or committed changes
kairos doctor Diagnose configuration and environment
kairos config Display or edit configuration
kairos providers List available LLM providers

Architecture

cmd/kairos/main.go        Entry point
internal/
  cmd/                    Cobra command definitions
  config/                 Viper-backed configuration
  context/                Project context builder (core engine)
  detect/                 Project type detection
  formatter/              Commit message parser and renderer
  git/                    Git repository abstraction
  prompt/                 LLM prompt builder
  provider/               Provider interface + registry
  provider/ollama/        Ollama HTTP client
  provider/openai/        OpenAI-compatible HTTP client (openai, lmstudio, gomodel)
pkg/                      Reserved for future public API

Roadmap

  • Phase 1 — Core CLI, Git context, Ollama provider, Conventional Commits
  • Phase 2a — OpenAI-compatible provider (OpenAI, LM Studio, GoModel gateway)
  • Phase 2b — Anthropic, Gemini, OpenRouter
  • Phase 3 — kairos tag, kairos release, kairos changelog
  • Phase 4 — kairos explain, kairos doctor
  • Phase 5 — GitHub/GitLab integration, Jira, Linear, MCP support

License

Apache 2.0

Directories

Path Synopsis
cmd
kairos command
Command kairos is a Git Context Engine that generates commit messages, tags, releases, and changelog entries using local or remote LLMs.
 Command kairos is a Git Context Engine that generates commit messages, tags, releases, and changelog entries using local or remote LLMs.
internal
build
Package build holds build-time version information injected by GoReleaser via -ldflags.
 Package build holds build-time version information injected by GoReleaser via -ldflags.
cmd
Package cmd contains all Cobra command definitions.
 Package cmd contains all Cobra command definitions.
config
Package config loads Kairos configuration from flags, environment variables, and the user's config file, in that order of precedence.
 Package config loads Kairos configuration from flags, environment variables, and the user's config file, in that order of precedence.
context
Package context builds a rich ProjectContext from a git repository.
 Package context builds a rich ProjectContext from a git repository.
detect
Package detect identifies a project's primary language/toolchain from well-known manifest files in its root directory.
 Package detect identifies a project's primary language/toolchain from well-known manifest files in its root directory.
formatter
Package formatter parses LLM responses into structured commit messages and renders them according to a style template (e.g.
 Package formatter parses LLM responses into structured commit messages and renders them according to a style template (e.g.
git
Package git provides a Repository interface and an exec-based implementation for collecting Git context.
 Package git provides a Repository interface and an exec-based implementation for collecting Git context.
i18n
Package i18n resolves the CLI's UI locale and translates the small set of user-facing error and easter-egg messages Kairos prints itself.
 Package i18n resolves the CLI's UI locale and translates the small set of user-facing error and easter-egg messages Kairos prints itself.
prompt
Package prompt builds structured prompts for LLM interactions.
 Package prompt builds structured prompts for LLM interactions.
provider
Package provider defines the Provider interface that all LLM providers must satisfy, along with a simple registry for looking up providers by name.
 Package provider defines the Provider interface that all LLM providers must satisfy, along with a simple registry for looking up providers by name.
provider/ollama
Package ollama provides a Provider that talks to a local Ollama instance via its REST API.
 Package ollama provides a Provider that talks to a local Ollama instance via its REST API.
provider/openai
Package openai provides a Provider that talks to any OpenAI-compatible chat completions API.
 Package openai provides a Provider that talks to any OpenAI-compatible chat completions API.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.