Skip to content
Kozou

Kozou

Your PostgreSQL DDL and COMMENT, compiled into an Admin UI, REST API, and MCP context.
Get started View on GitHub View on npm

What is Kozou?

Section titled “What is Kozou?”

Kozou reads your PostgreSQL schema once — tables, views, foreign keys, and the COMMENT ON text that describes them — and compiles it into the surfaces a modern team and its AI agents need. One source, no drift.

  • PostgreSQL is the single source of truth. Structure, relations, and business meaning live physically in the database as DDL and COMMENT. If you can express it in PostgreSQL, you don’t repeat it in YAML.
  • An Admin UI, generated at runtime. A reference SvelteKit app renders CRUD forms, relation pickers, and read-only views directly from the schema — no hand-written screens.
  • MCP context for AI agents. @kozou/mcp exposes your tables, views, and business concepts to Claude Code, Claude Desktop, and other MCP clients, so agents query with the schema’s own vocabulary.
  • A REST API over your data. v0.1 wires up PostgREST; v0.2 adds an experimental in-house REST layer (@kozou/api) that emits OpenAPI straight from your COMMENT.

The lever is COMMENT: annotate a column with @ai, @widget, or @example and that intent flows into the UI, the API docs, and the MCP context at once. See COMMENT conventions.

Install

Section titled “Install”
Terminal window
# Scaffold a project (docker-compose + kozou.config.yaml + ui-hints.yaml)
npx -p kozou create-kozou my-project
cd my-project
cp .env.example .env
docker compose up

docker compose up brings PostgreSQL, the REST layer, and the Admin UI online together. Prefer to run the CLI on your host instead? See Installation.

Status

Section titled “Status”

Kozou is at v0.1.1. Schema introspection, the MCP server (stdio + HTTP), and the reference Admin UI are published on npm, and a multi-arch runtime image is on GHCR. The v0.2 line adds an experimental in-house REST layer (@kozou/api) behind kozou dev --adapter api.

Source lives at github.com/kozou-dev/kozou. Published packages include kozou (CLI), @kozou/core, @kozou/introspect, @kozou/mcp, and @kozou/svelte-ui.

The name

Section titled “The name”

Kozou carries three meanings in three syllables: kozō (calf — the young elephant beside PostgreSQL’s mascot Slonik), kōzō (structure — the transformation a compiler performs), and kozō (apprentice — the quiet figure that serves something larger than itself).