kaos-ui

Part of Kelvin Agentic OS (KAOS) — open agentic infrastructure for legal work, built by 273 Ventures. See the full KAOS package map for the rest of the stack.

kaos-ui is the project scaffolder for KAOS user-facing applications. It ships six production-ready templates — web:api (FastAPI), web:spa (Vite + React + Tailwind v4 + shadcn/ui, kaos-agents-wired), dashboard:streamlit, tui:textual, module (KAOS module package), and workflow (single-file script) — and exposes the same scaffold/info/doctor lifecycle to MCP agents through four read-only tools.

It is the dependency-light entry point every KAOS user-facing app builds from. kaos-ui does not run servers, talk to LLMs, or render UI itself — it produces working projects that do those things, with the conventions and toolchain that the rest of the KAOS ecosystem assumes.

To expose kaos-ui over the Model Context Protocol, register its tools on a KaosRuntime and serve it through the companion package kaos-mcp (ships separately).

Install

uv add kaos-ui
# or
pip install kaos-ui

kaos-ui requires Python 3.13 or newer and has three runtime dependencies (kaos-core, pydantic, pydantic-settings). Templates that depend on pnpm, cargo, or docker declare those expectations in their kaos-ui-doctor check; kaos-ui itself does not require them.

Quick start

Scaffold a project from the CLI:

# Discover what's available
kaos-ui list

# See full detail (deps, env, post-install, next steps)
kaos-ui info web:spa

# Materialize a project
kaos-ui new web:spa myapp
cd myapp
make install     # runs the manifest's post_install chain
make dev         # boots the dev servers

Or drive the same lifecycle from Python:

import asyncio
from pathlib import Path

from kaos_core import KaosRuntime
from kaos_ui import register_ui_tools, scaffold


async def main() -> None:
    # Use scaffold() directly:
    result = scaffold(template="workflow", name="demo", target_dir=Path("./demo"))
    print(f"created {len(result.files)} files in {result.target}")

    # Or register the MCP tools onto a runtime:
    runtime = KaosRuntime()
    n = register_ui_tools(runtime)
    print(f"registered {n} kaos-ui MCP tools")
    tool = runtime.tools.get_tool("kaos-ui-list-templates")
    res = await tool.execute({})
    print("templates:", res.structuredContent["count"])


asyncio.run(main())

Concepts

The package is built around four small primitives.

CLI

kaos-ui ships a kaos-ui CLI. Every structured command supports --json for machine-readable output:

kaos-ui list                       # registered template kinds
kaos-ui list --json                # structured envelope: {"command": "list", ...}
kaos-ui info web:spa               # full manifest detail
kaos-ui info workflow --json
kaos-ui new web:spa myapp          # materialize a project
kaos-ui new web:spa myapp --dry-run  # plan without writing
kaos-ui doctor ./myapp             # health-check a scaffolded project
kaos-ui doctor . --json            # structured findings

Compatibility & status

Companion packages

kaos-ui is one of the packages in the Kelvin Agentic OS. The broader stack:

Packages depend on kaos-core; everything else is opt-in. Mix and match the ones you need.

Pre-built example

The repository ships a complete reference application under examples/single-user-chat/ that exercises the web:spa template end-to-end: bearer-token auth, SSE streaming proxy with a read-only KAOS tool allowlist, persistent VFS, markdown rendering with link sanitization, and a stop/cancel control. It's the canonical proof that the scaffold output runs in anger.

Development

git clone https://github.com/273v/kaos-ui
cd kaos-ui
uv sync --group dev

Install pre-commit hooks (recommended — they run the same checks as CI on every commit, scoped to staged files):

uvx pre-commit install
uvx pre-commit run --all-files     # one-time full sweep

Manual QA commands (the same set CI runs):

uv run ruff format --check kaos_ui tests
uv run ruff check kaos_ui tests
uv run ty check kaos_ui tests
uv run pytest -m "not slow"

Build from source

uv build
uv pip install dist/*.whl

Contributing

Issues and pull requests are welcome. See CONTRIBUTING.md for setup, quality gates, pull request expectations, and engineering standards. By contributing you certify the Developer Certificate of Origin v1.1 — sign every commit with git commit -s. Please open an issue before starting on a non-trivial change so we can align on scope.

Security

For security issues, please do not file a public issue. Report privately via GitHub Private Vulnerability Reporting or email security@273ventures.com. See SECURITY.md for the full disclosure policy.

License

Apache License 2.0 — see LICENSE and NOTICE.

Copyright 2026 273 Ventures LLC. Built for kelvin.legal.