kmailai

v0.2.1 · stable · agents

the Kmail AI coding agent, in your terminal

about

A branded, self-contained coding agent that runs against the Kmail AI

OpenWebUI instance at ai.kmail.at. Vendored Pi engine, red/white theme,

modern splash header, guided first-run API-key setup. Interactive TUI

and one-shot (-p) mode, with 44 OpenWebUI models available.

what it does

Self-contained vendored engine: The package ships the Pi coding agent (0.84.2) plus its node_modules and an `fd` binary under vendor/pi-coding-agent, and package.json declares no dependencies at all, so `npm install -g kmailai` needs no separate engine or global install.
Provider setup wizard: `kmailai setup` asks you to pick OpenWebUI, Ollama, LM Studio or any OpenAI-compatible endpoint, takes its base URL and API key, checks the endpoint answers HTTP 200, and only then writes ~/.kmailai/provider.json with mode 0600.
TUI plus one-shot mode: `kmailai` with no arguments opens the fullscreen TUI (transcript plus docked footer); `kmailai -p "question"` prints one answer and exits; `--mode` also accepts json and rpc for scripting.
Live model sync: `kmailai sync-models` fetches GET <baseUrl>/models from the active provider into ~/.kmailai/agent/models.json, keeps per-model edits such as a renamed model, and sorts the result by model id.
Sessions kept per directory: Sessions are JSONL files under ~/.kmailai/agent/sessions/<escaped-cwd>/, resumed with -c (most recent) or -r (picker), forked with --fork <id>, and skipped entirely with --no-session.
Config survives reinstalls: bin/seed-agent.sh copies the packaged templates into ~/.kmailai/agent only for files that do not already exist, so edits to SYSTEM.md, settings.json, themes/ and your saved provider key are untouched by updates.

install

npm (recommended)

npm install -g kmailai

Puts the `kmailai` command on your PATH; the postinstall script runs bin/seed-agent.sh once so ~/.kmailai/agent already exists at first launch. Needs Node.js >= 18 and python3 (stdlib only, no pip packages).

Then run the guided setup

kmailai setup

First run launches this wizard anyway: choose a provider, enter its base URL and API key (a sensible default URL is pre-filled and the endpoint is verified before saving), and it also regenerates ~/.kmailai/agent/models.json and settings.json for that provider.

Skip the saved key for one run

KMAILAI_API_KEY=<key> kmailai -p "explain this repo"

An explicit key (or the legacy OPENWEBUI_API_KEY) overrides the key saved in ~/.kmailai/provider.json for that invocation only, for CI or a shell that should not persist credentials.

From a source checkout

git clone https://github.com/mokmail/kmailai && cd kmailai && npm install -g .

Installs the bin from a local clone; the launcher resolves symlinks so an in-place checkout works, and all runtime state still goes to ~/.kmailai/ rather than into the checkout.

synopsis

kmailai [options] [@files...] [messages...]

changelog

v0.2.1multi-provider setup wizard (OpenWebUI/Ollama/LM Studio/OpenAI-compatible), live model sync, opencode-style TUI theme, session history, tuned compaction & retry
v0.1.6guided first-run setup (kmailai setup) + engine re-vendor to 0.84.2
v0.1.4rebrand from ibev to KmailAI; config moves to ~/.kmailai
v0.1.0initial release: branded Pi coding agent on Kmail AI