Skip to content
Kozou

Get started

Kozou is a PostgreSQL-native compiler and runtime. It reads your database’s DDL and COMMENT text once and emits an Admin UI, a REST API, and MCP context for AI agents — no duplicate definitions, no drift.

This page is the 5-minute fast lane: the happy path that gets a project scaffolded, the stack online, and an AI agent pointed at the MCP server. When you want the rationale, output samples, and the full walkthrough, jump to the Quickstart.

Prerequisites

Section titled “Prerequisites”
  • PostgreSQL 16 or later — the canonical source of truth.
  • Docker 24 or later (recommended) — for the docker compose up stack: PostgreSQL plus a kozou service that serves the Admin UI, the MCP HTTP server, and the in-house REST layer in-process.
  • Node.js 20 or later — for running the published npm packages directly with npx, including the scaffolder and the host CLI.

See Installation for the full matrix and alternatives.

1. Scaffold a project

Section titled “1. Scaffold a project”

create-kozou writes a starter directory with a docker-compose.yml, a kozou.config.yaml, a ui-hints.yaml, a .env.example, and a starter migration. It ships as a secondary bin of the kozou package, so npx needs -p kozou to find it on a clean machine.

Terminal window
npx -p kozou create-kozou my-project
cd my-project

2. Start the stack

Section titled “2. Start the stack”

Copy the example environment file, then bring everything up. The scaffold’s docker-compose.yml includes a kozou service that runs kozou dev, so a single command brings the full stack online: PostgreSQL and a kozou service serving the bundled Admin UI, the MCP HTTP server, and the in-house REST layer, all in-process.

Terminal window
cp .env.example .env
docker compose up

3. Open the Admin UI

Section titled “3. Open the Admin UI”

The Admin UI listens on port 3333 by default. Open it in your browser:

http://localhost:3333

You should see the tables from your schema, rendered from your DDL and COMMENT text. To shape how columns and tables appear, Kozou reads COMMENT tags such as @ai, @widget, @policy, and @example — see COMMENT conventions.

4. Point an AI agent at the MCP server

Section titled “4. Point an AI agent at the MCP server”

Kozou serves the same Schema Context to AI agents over MCP, so a tool like Claude Code or Claude Desktop can call its introspect and describe-table tools.

For stdio transport (the default), run the host CLI:

Terminal window
kozou mcp --stdio

The kozou dev process started by docker compose up in Step 2 also serves MCP over HTTP on port 3334, so an HTTP-capable agent can connect there without a separate command.

Where to next

Section titled “Where to next”
  • Quickstart — the same flow with output samples, configuration details, and the full walkthrough.
  • Installation — the requirements matrix, the Docker runtime image, and library packages such as @kozou/core, @kozou/introspect, @kozou/mcp, and @kozou/svelte-ui.
  • COMMENT conventions — how the @ai, @widget, @policy, and @example tags drive the emitted surfaces.