npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

kmailai

v0.2.1

Published

KmailAI — a branded, self-contained coding agent for Kmail AI, powered by Pi on Kmail AI (OpenWebUI).

Readme

KmailAI — Coding Agent (self-contained)

KmailAI is a branded coding agent built on the Pi coding-agent engine. It is provider-flexible: point it at your own OpenWebUI, Ollama, LM Studio, or any OpenAI-compatible endpoint. A setup wizard (kmailai setup) lets you pick a provider, enter its base URL and API key, and the choice is saved locally and reused on every launch.

It is fully self-contained: the Pi engine is vendored into this package (vendor/pi-coding-agent), so it does not depend on a global @earendil-works/pi-coding-agent npm install. Everything needed to run is inside this directory.

npm package node license version engine


Table of contents


What is KmailAI?

KmailAI is a thin, branded harness around the Pi coding-agent engine. It ships pre-configured for the Kmail AI (OpenWebUI) endpoint at ai.kmail.at, but you can switch it to your own OpenWebUI, Ollama, LM Studio, or any OpenAI-compatible endpoint with kmailai setup.

The agent has a single mission: give Kmail AI users a precise, rigorous, trustworthy coding assistant that works in the directory it is invoked from, remembers its identity across sessions, and never quietly relies on a global toolchain it does not own.

Key features

  • Self-contained. Pi engine, its node_modules, and an fd binary are all vendored. npm install -g kmailai is enough — no global engine dependency.
  • Branded. red (#e2001a) + white throughout: theme, splash header, system prompt, README. No reference to the underlying engine surfaces.
  • Isolated config. User config, sessions, skills, themes and the API key live in ~/.kmailai/. Reinstalls and updates never clobber user data.
  • OpenCode-style TUI — fullscreen layout (clean transcript + docked footer) with an opencode-inspired dark theme and an opencode-style top-bar header, plus one-shot (-p "question") mode.
  • Provider setup wizard (kmailai setup): pick OpenWebUI, Ollama, LM Studio or any OpenAI-compatible endpoint, enter its base URL + API key, saved locally (mode 0600) and reused on every launch.
  • Live model sync from the active provider (kmailai sync-models), preserving user-renamed models.
  • Custom startup header (red→white gradient KMAILAI wordmark + bordered info panel) registered as an extension; one command (/builtin-header) restores the engine's default header.
  • Session history organised by working directory, resumable with -c / -r / --session, forkable with --fork.
  • Compaction & retry tuned for long sessions (16k reserve, 20k recent tokens; 3 retries with 2 s base delay, capped at 60 s).
  • Five pre-enabled models (minimax-m3:cloud, deepseek-coder:latest, glm-5.2:cloud, kimi-k2.7-code:cloud, claude-opus-5) with all 44 OpenWebUI models available.

Quick start

# 1. Install (publishes the `kmailai` command on your PATH)
npm install -g /path/to/kmailai      # from this checkout
# or, once published:
# npm install -g kmailai

# 2. Run the setup wizard — pick a provider, enter its base URL + API key
kmailai setup

# 3. Run it — every launch re-reads the saved provider
kmailai

# 4. One-shot query
kmailai -p "explain this repo"

# 5. Sync the live model list from the active provider
kmailai sync-models

That's it. No global Pi install, no extra config files.

Requirements

| Requirement | Version / detail | | --------------- | ------------------------------------------------------------------------- | | Node.js | >=18 (the launcher runs node directly; no transpilation) | | python3 | Required for provider config + kmailai sync-models (stdlib only; no pip deps) | | Network access | HTTPS to your provider's /models + chat-completions endpoint (local Ollama/LM Studio need none) | | Terminal | Any modern TTY; ANSI true-color is used by the splash header & theme | | Disk | ~50 MB (Pi dist + node_modules + the vendored fd binary) |

Installation

From this checkout (recommended while iterating)

cd /path/to/kmailai
npm install -g .          # installs the `kmailai` bin onto your PATH

The postinstall script in package.json runs bin/seed-agent.sh once, which pre-creates ~/.kmailai/agent so the first launch is instant.

From npm (once published)

npm install -g kmailai

Uninstall

npm uninstall -g kmailai
# ~/.kmailai/ is intentionally NOT removed — it holds your settings, themes,
# skills, session history and API key. Remove it manually if desired:
rm -rf ~/.kmailai

Update the vendored Pi engine

The Pi engine lives under vendor/pi-coding-agent/. To upgrade to a newer Pi release, replace that directory with the contents of the upstream package:

# From a machine where the global package is installed:
rm -rf vendor/pi-coding-agent
cp -r ~/.npm-global/lib/node_modules/@earendil-works/pi-coding-agent \
      vendor/pi-coding-agent

The launcher uses vendor/pi-coding-agent/dist/cli.js — no rebuild is required.

Usage

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

Run with no arguments for the interactive TUI; pass -p for a single non-interactive query. All arguments are passed through to the vendored Pi engine, with the launcher only handling API-key resolution and the help / sync-models subcommands.

Commands & flags

| Flag / command | Description | | --------------------------------------- | ------------------------------------------------------------------------------ | | kmailai | Interactive TUI (red & white, branded splash header) | | kmailai -p "question" | One-shot query, prints response, exits | | kmailai setup | Setup wizard: pick a provider, enter base URL + API key, saved locally | | kmailai sync-models | Regenerate ~/.kmailai/agent/models.json from the active provider | | kmailai configure-provider | Re-apply the active provider config (models.json / settings.json) | | /theme (in TUI) | Switch the TUI theme directly (selector or /theme <name>) | | kmailai -h, --help, help | Print KmailAI-branded help (handled by the launcher, not the engine) | | --provider <name> | Provider name (default: from ~/.kmailai/provider.json) | | --model <pattern> | Model pattern or full ID (e.g. openwebui/minimax-m3:cloud) | | --api-key <key> | API key (overrides the saved provider key) | | --system-prompt <text> | Override system prompt (default: KmailAI identity) | | --append-system-prompt <t> | Append text or file contents to the system prompt | | --mode <mode> | Output mode: text (default), json, rpc | | --print, -p | Non-interactive: process prompt and exit | | --continue, -c | Continue the previous session in this directory | | --resume, -r | Pick a session interactively | | --session <path\|id> | Use a specific session file or partial UUID | | --fork <path\|id> | Fork a session into a new one | | --session-dir <dir> | Directory for session storage / lookup | | --no-session | Ephemeral: don't save the session | | --models <patterns> | Comma-separated model patterns for Ctrl+P cycling | | --no-tools, -nt | Disable all tools by default | | --no-builtin-tools, -nbt | Disable built-in tools but keep extension tools | | --tools, -t <tools> | Comma-separated allowlist of tool names | | --thinking <level> | off, minimal, low, medium, high, xhigh (default medium) | | --extension, -e <path> | Load an extension file (repeatable) | | --no-extensions, -ne | Disable extension discovery | | --skill <path> | Load a skill file or directory (repeatable) | | --no-skills, -ns | Disable skills discovery | | --prompt-template <path> | Load a prompt template file or directory | | --config <file> | Load a config from a specific file | | --settings <file> | Load settings from a specific file | | --list-models | List available models and exit | | --version, -v | Print the engine version and exit |

Environment variables

| Variable | Purpose | Default | | ----------------------- | ------------------------------------------------------------ | ------------------------ | | KMAILAI_API_KEY | API key for the active provider. Overrides the saved key. | saved in provider.json | | OPENWEBUI_API_KEY | Legacy alias for the OpenWebUI key (overrides the saved key). | — | | KMAILAI_CONFIG_DIR | Where KmailAI stores user config, sessions, provider + API key. | ~/.kmailai | | PI_CODING_AGENT_DIR | Engine-side config dir (set by the launcher). | ${KMAILAI_CONFIG_DIR}/agent |

First launch & provider setup

On the very first run, KmailAI launches the setup wizard so you can pick a provider and save its credentials locally:

  KmailAI — setup
  ──────────────

  Choose the AI provider kmailai should talk to.
  You can switch providers anytime by re-running this wizard.

  1) OpenWebUI   — hosted (e.g. https://ai.kmail.at/api/v1)
  2) Ollama      — local (default http://localhost:11434/v1)
  3) LM Studio   — local (default http://localhost:1234/v1)
  4) OpenAI-compatible — any custom endpoint

  Select [1-4]: █

After you pick a provider you are asked for its base URL (a sensible default is pre-filled), an API key (required for hosted providers, optional for local Ollama/LM Studio), and an optional default model ID. The wizard verifies the endpoint (for key-required providers it must return HTTP 200) and only then saves everything to ~/.kmailai/provider.json (mode 0600).

Recommended: kmailai setup

Run kmailai setup explicitly anytime to switch providers or update your credentials. It regenerates ~/.kmailai/agent/models.json and ~/.kmailai/agent/settings.json for the selected provider, so the CLI is ready to use immediately.

Resolution order

  1. Explicit override: KMAILAI_API_KEY=... kmailai ... (or the legacy OPENWEBUI_API_KEY)
  2. Persisted file: ~/.kmailai/provider.json (created by the setup wizard)
  3. Re-prompted: delete ~/.kmailai/provider.json to be asked again.

A legacy .api-key (from older KmailAI versions) is migrated into ~/.kmailai/provider.json on first launch (one-shot, not deleted).

How it works

┌──────────────────────────┐
│   bin/kmailai (bash)     │  ← resolves symlinks, locates KMAILAI_HOME
│                          │  ← seeds ~/.kmailai/agent from agent/ templates
│                          │  ← reads ~/.kmailai/provider.json (active provider)
│                          │  ← runs configure-provider.py (models.json/settings.json)
│                          │  ← exec node vendor/pi-coding-agent/dist/cli.js
└──────────────┬───────────┘
               │ env: PI_CODING_AGENT_DIR, KMAILAI_API_KEY
               ▼
┌──────────────────────────┐
│ Pi engine (vendored)     │  ← reads SYSTEM.md, settings.json, models.json
│   dist/cli.js            │  ← loads theme kmailai-red + extensions/
│                          │  ← talks to the active provider's base URL
└──────────────┬───────────┘
               │ HTTPS (Bearer auth, or none for local servers)
               ▼
┌──────────────────────────┐
│ Your provider            │  ← OpenWebUI / Ollama / LM Studio / OpenAI-compatible
│   (base URL)             │  ← model routing, completions
└──────────────────────────┘

The launcher is intentionally thin: it does not interpret model output, it does not modify the prompt, and it does not interfere with the engine's session management. It only prepares the runtime, seeds config, reads the active provider, and resolves the API key.

Configuration

Config directory layout

kmailai/                          # this npm package (source of truth / templates)
├── bin/
│   ├── kmailai                   # launcher: runs vendored engine, injects API key
│   ├── seed-agent.sh             # seeds ~/.kmailai/agent from packaged templates
│   ├── configure-provider.py     # applies the active provider (models.json/settings.json)
│   └── sync-models.py            # regenerates ~/.kmailai/agent/models.json
├── vendor/
│   └── pi-coding-agent/          # vendored Pi engine (dist + node_modules)
│       ├── dist/cli.js           # the actual CLI entrypoint
│       ├── node_modules/
│       └── package.json          # @earendil-works/pi-coding-agent 0.84.2
├── agent/                        # packaged template config (shipped as the seed source)
│   ├── SYSTEM.md                 # base system prompt (KmailAI identity)
│   ├── APPEND_SYSTEM.md          # appended context
│   ├── auth.json                 # engine auth store (empty `{}` by default)
│   ├── models.json               # provider + models (regenerated per active provider)
│   ├── settings.json             # default provider/model, theme, compaction, retry
│   ├── themes/kmailai-opencode.json  # opencode-inspired dark theme (default)
│   ├── themes/kmailai-red.json   # red + white TUI theme (51 tokens)
│   ├── extensions/kmailai-splash-header.ts   # branded startup header
│   ├── bin/fd                    # vendored `fd` binary (file finder)
│   ├── skills/                   # on-demand capability packages (empty by default)
│   └── prompts/                  # reusable prompt templates (empty by default)
├── package.json                  # npm package metadata
├── package-lock.json
└── README.md

~/.kmailai/                       # user config dir (created on npm install / first launch)
├── agent/                        # live Pi agent directory (PI_CODING_AGENT_DIR)
│   ├── SYSTEM.md                 # copy of template (editable — survives updates)
│   ├── APPEND_SYSTEM.md
│   ├── auth.json
│   ├── settings.json, models.json
│   ├── themes/, extensions/, skills/, prompts/, bin/
│   └── sessions/                 # session history (user-owned, survives reinstalls)
└── provider.json                 # active provider: type, base URL, API key, model (mode 0600)

The shipped agent/ directory is the template source. bin/seed-agent.sh copies anything missing into ~/.kmailai/agent, but never overwrites existing files — your local edits to SYSTEM.md, settings.json, themes/, etc. survive every reinstall.

System prompt

agent/SYSTEM.md defines KmailAI's identity and operating principles (precision, rigor, brand palette, output style). agent/APPEND_SYSTEM.md appends a short reinforcement block. Both are seeded into ~/.kmailai/agent/ on first run and can be edited freely; the next npm install will not touch them.

Settings

agent/settings.json controls the engine's defaults:

| Key | Value | | ----------------------- | ---------------------------------------------------------------------- | | defaultProvider | Active provider (set by kmailai setup / configure-provider) | | defaultModel | Active default model (set by kmailai setup / configure-provider) | | defaultThinkingLevel | medium | | theme | kmailai-opencode (opencode-inspired dark; kmailai-red also ships) | | tuiMode | fullscreen (clean transcript + docked footer; regular also available) | | quietStartup | false | | collapseChangelog | true | | compaction.enabled | true — long sessions auto-compact | | compaction.reserveTokens | 16384 — tokens reserved for the system prompt during compaction | | compaction.keepRecentTokens | 20000 — recent tokens kept verbatim | | retry.enabled | true | | retry.maxRetries | 3 | | retry.baseDelayMs | 2000 | | retry.provider.maxRetryDelayMs | 60000 — cap on exponential backoff | | enabledModels | 5 models shown in the Ctrl+P quick-pick (see below) | | enableSkillCommands | true | | lastChangelogVersion | 0.84.2 |

Models

agent/models.json declares the active provider (OpenWebUI, Ollama, LM Studio, or an OpenAI-compatible endpoint) with the models it exposes. It is regenerated by kmailai setup / kmailai configure-provider / kmailai sync-models from the provider's /models endpoint. Each model entry has the shape:

{
  "id": "minimax-m3:cloud",
  "name": "minimax-m3:cloud",
  "reasoning": true,
  "input": ["text", "image"],
  "contextWindow": 262144,
  "maxTokens": 16384,
  "cost": { "input": 0, "output": 0, "cacheRead": 0, "cacheWrite": 0 }
}

The five models pre-enabled in the quick-pick (Ctrl+P) are:

  • minimax-m3:cloud
  • deepseek-coder:latest
  • glm-5.2:cloud
  • kimi-k2.7-code:cloud
  • claude-opus-5

Reasoning capability is inferred heuristically (deepseek, kimi, qwen, glm, minimax, claude, gpt-5, gemini, grok, mistral, nemotron, ruler, eco, cio, qm, karli, clone, role, mimo) by bin/sync-models.py. Adjust it manually if needed — sync-models preserves your customisations on subsequent runs.

Theme (kmailai-red)

agent/themes/kmailai-red.json is a 51-token TUI theme built around the red palette. Twelve CSS-style variables drive every color:

| Variable | Hex | Role | | --------------- | --------- | --------------------------------- | | bevRed | #e2001a | borders, brand primary | | bevRedBright | #ff1f38 | accent, headings, list bullets | | bevRedDark | #a30012 | borders, code-block outlines | | white | #ffffff | primary text, accent borders | | nearWhite | #f5f5f7 | code blocks, soft text | | gray | #c9c9cf | muted text | | dimGray | #8a8a92 | dim text, URLs | | darkGray | #5c5c64 | muted borders | | darkRedBg | #1f0a0e | deep page background | | cardRedBg | #2b1014 | card / user-message background | | deepBg | #12060a | page background | | selectedRedBg | #4a1420 | selected row background |

It also defines the thinkingXhigh → off ramp on bevRedBright → darkGray and exports three page backgrounds (pageBg, cardBg, infoBg) for the HTML export pipeline.

Theme (kmailai-opencode)

The default theme, agent/themes/kmailai-opencode.json, is an opencode-inspired dark theme: a near-black background (#0a0a0a) with layered panel/element surfaces (#141414 / #1e1e1e), subtle gray borders, and the KmailAI red as the primary accent. It maps opencode's palette (background, backgroundPanel, backgroundElement, border, text, textMuted, primary, secondary, accent, success, error, warning, info, diff, markdown and syntax colors) onto the Pi theme tokens, so the TUI reads like opencode while keeping the KmailAI brand. The classic kmailai-red theme still ships and can be selected via /settings or by editing settings.json.

Extensions & splash header

agent/extensions/kmailai-splash-header.ts is a TypeScript extension that replaces the engine's built-in startup header with a redesigned KmailAI splash. On every session_start it renders:

  • A bold, letter-spaced KMAILAI wordmark in the colours of the Palestinian flag (red → white → green gradient)
  • A Palestinian flag graphic — a red bar on the left with black, white and green horizontal stripes (rendered with truecolor backgrounds)
  • A tagline — coding agent for Kmail AI — with the kmailai version right-aligned (or on its own line on narrow terminals)
  • The mission line rigorous · precise · trustworthy
  • A developer block: author (Mohammed Kmail / mokmail), platform (ai.kmail.at), web (kmail.at), GitHub and LinkedIn
  • A ● ready — type a message to begin status line

No reference to the underlying engine is shown — only KmailAI / Kmail brand details, sourced from kmail.at.

It registers one command:

| Command | Description | | ----------------- | -------------------------------------------- | | /builtin-header | Restore the engine's default header with keybinding hints | | /theme | Switch the TUI theme directly (selector, or /theme <name>) |

Extensions are loaded by the engine automatically — no extra flags needed. If you want the engine's vanilla header again, run /builtin-header once and it persists for the session. To change the TUI theme without digging into /settings, run /theme (interactive selector) or /theme <name> (e.g. /theme kmailai-red).

Skills & prompts

agent/skills/ and agent/prompts/ ship empty. They are seeded (created if missing) so users can drop in on-demand capability packages and reusable prompt templates without touching the package. The enableSkillCommands: true flag in settings.json enables slash-command discovery for installed skills.

Sessions

~/.kmailai/agent/sessions/ holds JSONL session files, organised by working directory (each - in the path becomes a -- subfolder). For example, sessions created in /home/kmail/ibev live under:

~/.kmailai/agent/sessions/--home-kmail-ibev--/
├── 2026-08-14T11-28-56-518Z_ddfe50f9-...jsonl
├── 2026-08-14T11-29-02-822Z_6bc264f0-...jsonl
└── ...

Sessions are gitignored (agent/sessions/) and are user-owned data — they are not seeded, never overwritten, and survive every reinstall. Resume with -c (most recent), -r (picker), --session <id>, or fork with --fork <id>.

Subcommands

kmailai sync-models

Regenerates ~/.kmailai/agent/models.json from the active provider (selected in ~/.kmailai/provider.json).

  • Fetches GET <baseUrl>/models (Bearer auth for hosted providers, none for local Ollama/LM Studio).
  • Merges into the existing file, preserving per-model customisation (name, reasoning, contextWindow, maxTokens, etc.) so any models you renamed or annotated keep their labels.
  • New models are added with sensible defaults: reasoning inferred by substring match, input: ["text", "image"], contextWindow: 262144, maxTokens: 16384, all cost fields 0.
  • Output is sorted alphabetically by model id.
kmailai sync-models                  # refresh models.json
KMAILAI_CONFIG_DIR=/tmp/kmailai-test kmailai sync-models   # test against an isolated config

Self-contained / vendoring

The Pi engine is vendored under vendor/pi-coding-agent/ (dist + node_modules). Three reasons:

  1. No global dependency. Users run npm install -g kmailai and it just works — no @earendil-works/pi-coding-agent install step.
  2. Hermetic engine version. The package ships a known-good engine build. Upstream Pi releases do not silently break KmailAI.
  3. Offline-friendly distribution. vendor/pi-coding-agent/node_modules/ is included in package.json's files whitelist, so the package is installable from a tarball without network access.

To upgrade the engine, see Update the vendored Pi engine.

Provider

KmailAI is provider-flexible. The active provider is stored in ~/.kmailai/provider.json and applied on every launch. Supported providers:

| Provider | Default base URL | API key | Auth header | | ------------- | ----------------------------------- | ------- | ----------- | | openwebui | https://ai.kmail.at/api/v1 | required | Bearer | | ollama | http://localhost:11434/v1 | optional | none | | lmstudio | http://localhost:1234/v1 | optional | none | | openai | (custom, you provide it) | required | Bearer |

  • API: openai-completions (all presets speak the OpenAI Chat Completions API)
  • Models: fetched from the provider's /models endpoint into ~/.kmailai/agent/models.json by kmailai setup / kmailai configure-provider / kmailai sync-models. Pi does not auto-discover models, so run kmailai sync-models after adding models on the server.
  • Switching: re-run kmailai setup to pick a different provider. The previous provider's models are kept in models.json (so you can switch back), and settings.json is repointed at the new provider.

Brand

  • Name: KmailAI (bold, white, all-caps wordmark)
  • Palette: red #e2001a + white
  • Identity: coding agent for Kmail AI
  • Tone: rigorous, precise, trustworthy
  • Startup header: KMAILAI wordmark with red→white gradient + bordered info panel (engine / provider / model), implemented by agent/extensions/kmailai-splash-header.ts

Security & privacy

  • Provider + API key storage: ~/.kmailai/provider.json, mode 0600, owned by the invoking user. Never logged, never written to the package directory (the launcher migrates legacy in-package keys once and then forgets them).
  • Config isolation: all user state lives under ~/.kmailai/. The package itself contains only templates and the vendored engine.
  • No telemetry: KmailAI only calls the provider endpoint you configured (its /models and chat-completions routes). The splash header, settings and theme are purely local.
  • Gitignored: .api-key, provider.json and agent/sessions/ are gitignored from this repo. User-owned secrets and history never leak.
  • Sandbox: the Pi engine inherits the user's shell permissions; there is no extra sandbox layer. Treat prompts like any other code that runs on your machine.

Troubleshooting

| Symptom | Likely cause / fix | | ------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------- | | KmailAI: no provider configured. then nothing happens | No ~/.kmailai/provider.json yet. Run kmailai setup to pick a provider. | | KmailAI: invalid choice. Setup aborted. | You entered a number outside 1–4 in the setup wizard. Re-run kmailai setup. | | 401 / 403 from the model | The saved key is stale or revoked. Re-run kmailai setup and enter a fresh key, or export KMAILAI_API_KEY=.... | | --list-models shows 0 models | The provider returned no data, or the key has no model-list scope. Run kmailai sync-models to inspect. | | New model not visible | Pi does not auto-discover models. Run kmailai sync-models to regenerate ~/.kmailai/agent/models.json. | | Local Ollama/LM Studio not reachable | The server isn't running. Start it, then re-run kmailai sync-models. The config is saved regardless. | | Splash header is missing / falls back to default | The extension failed to load. Check ~/.kmailai/agent/extensions/kmailai-splash-header.ts exists; run /builtin-header and re-seed via npm install -g .. | | Sessions gone after npm install -g kmailai | Sessions live in ~/.kmailai/agent/sessions/, never in the package. If they're missing there, the user config dir was removed. | | Engine complains about an unknown CLI flag | That flag is not supported by the vendored Pi version (0.84.2). See the Pi changelog and bump the engine if needed. | | kmailai sync-models fails with a Python traceback | python3 is missing or too old (needs 3.7+). Install Python 3 and retry. |

Limitations

  • No auto-discovery of models. New models added in OpenWebUI require a manual kmailai sync-models.
  • Engine pinning. Vendoring means you do not get automatic Pi updates. Upgrades are explicit (see Update the vendored Pi engine).
  • Single provider. The shipped models.json declares only openwebui. Adding more providers is straightforward (append a providers.<name> block) but is not currently templated.
  • No global npm dependency required, but Node ≥ 18 is required.
  • sync-models heuristic for reasoning is substring-based; double check per-model entries after regeneration.

Kanban / project tracking

Work is tracked on the kmailai kanban board:

hermes kanban boards switch kmailai

Roadmap & contributing

  • [ ] More OpenWebUI providers (per-tenant endpoints)
  • [ ] Per-model name / reasoning overrides stored in a separate models.local.json so sync-models can never overwrite them
  • [ ] Automated engine version check + one-command bump
  • [ ] Optional sandbox layer for tool execution
  • [ ] A second theme (kmailai-light) for daylight terminals

Contributions: open a PR on github.com/mokmail/kmailai. Keep changes focused on the KmailAI identity — rigorous, precise, trustworthy.

License

MIT — © Mohammed Kmail (mokmail).

Credits

  • Pi coding-agent engine — © Mario Zechner / earendil-works. Vendored under vendor/pi-coding-agent/. See its LICENSE for upstream terms.
  • Kmail AI / OpenWebUIhttps://ai.kmail.at, the inference endpoint KmailAI targets.
  • fd — the fd file finder binary, vendored at agent/bin/fd for the engine's fast file-search tool.

KmailAI — rigorous, precise, trustworthy.