Kairos Documentation

Kairos is an AI-native scheduling app you can self-host, extend with plugins, and theme to your taste. These docs cover building plugins, authoring themes, and calling the API.

Building plugins

Create a scratchpad plugin that extracts tasks from any source — URLs, files, voice memos.

Authoring themes

Design a full visual identity by declaring 20 semantic tokens in a JSON manifest.

API reference

Integrate Kairos from agents, n8n, or any HTTP client via the REST API.

Quick start: self-host in 5 minutes

# 1. Clone the repo
git clone https://github.com/kairos-app/kairos && cd kairos

# 2. Copy env template and fill in your credentials
cp .env.local.example .env.local

# 3. Start with Docker
docker compose up -d

# 4. Open http://localhost:3000

See the CONTRIBUTING.md for the full setup guide including Google OAuth.

Architecture in one paragraph

Kairos is a single Next.js 16 app (App Router). Tasks, tags, and schedule windows live in a Postgres database via Drizzle. Google Calendar is the only time store — tasks store a gcalEventId and a denormalised scheduledAt cache. The scratchpad is a plugin host: it receives input (text, URLs, voice), dispatches to whichever plugin claims it, and returns candidate tasks for the user to review before committing. Background scheduling runs through a Postgres jobs table drained by Vercel Cron.