Kairo

The terminal task manager for developers who live in their editor.

A premium, minimalist task manager designed for focus. Kairo strips away the noise, relying on structured whitespace and refined typography to keep you in your flow.

Why Kairo?

Kairo is built on the philosophy of "Calm Tech." We focus on your data, not our UI.

Premium Minimalist Feature	Benefit
Momentum Dashboard	Empty states are now data-rich, bordered modules.
White-Space-First UI	No borders, no clutter — just content.
Monochrome Design	Neutral core, semantic-only color highlights.
Typography Hierarchy	Clear visual focus through font weight and scale.
Fluid Motion	Sub-300ms transitions that feel "alive."

Quick Start

macOS (Homebrew)

brew install programmersd21/kairo/kairo

Linux / macOS

curl -fsSL https://raw.githubusercontent.com/programmersd21/kairo/main/scripts/install.sh | bash

Windows (PowerShell)

iwr -useb https://raw.githubusercontent.com/programmersd21/kairo/main/scripts/install.ps1 | iex

go install github.com/programmersd21/kairo/cmd/kairo@latest

Then just run:

kairo

Press n to create your first task. ctrl+s to save. That's it.

Works best on Alacritty. Some terminals may have rendering quirks — see #16.

Features

⚡ Genuinely Fast

Sub-millisecond fuzzy search. Vim bindings (j/k/gg/G). Natural language deadlines like tomorrow 10am or next friday. Full keyboard control — you never touch the mouse.

🗂 Nested Tasks & Hierarchy

Organize work into deep hierarchies and separate projects. Nest tasks via the Parent field in the editor, switch projects with ctrl+e to focus your workspace, and export/import with full structure preserved — across JSON, CSV, Markdown, and plain text.

🔁 Recurring Tasks

Tasks reappear automatically on a schedule. Weekly (mon,wed,fri) or monthly (15). When completed, Kairo generates the next instance immediately with a smart due-date preview.

🔒 Your Data, Locally

SQLite with WAL mode. Fully offline. Optional Git-backed sync — no backend, no account, no lock-in. Export to JSON, CSV, Markdown, or plain text on demand. Project organization is preserved in your database.

🧭 Interactive Stats Dashboard

Press s to open a next-gen "Command Center". Visualize your Productivity DNA, track real-time momentum, and get behavioral insights like "You complete 73% more tasks at night". Fully animated, keyboard-driven, and deeply insightful.

🤖 AI — Optional, Never Intrusive

Gemini integration (gemini-3.1-flash-lite-preview / gemini-2.5-flash-lite / gemini-2.0-flash-lite). Toggle with ctrl+a. Create and manage complex recurring tasks with natural language, including assigning to specific projects. Invisible until you need it.

🎨 Beautiful by Default

32 built-in themes with edge-to-edge background coverage. Live switching with t. Bento-style layout. Real-time Markdown preview (ctrl+p). Cinematic create/complete/delete animations — or disable them entirely in config.toml.

🧩 Extensible to the Core

A Lua plugin system hooks into task events. A headless CLI API enables full scripting. An MCP server opens Kairo to AI agents — with complete support for recurring schedules and nested hierarchies.

🎨 Tag Highlighting

Color-code your tags directly in config.toml. Supports hex codes or theme-aware ui-* aliases (e.g., ui-accent).

[tags.highlight]
work    = { fg = "#CCCCCC" }
private = "fg=#EEEEEE,bg=#0000FF,bold"
diy     = "bg=ui-accent"

Keyboard Shortcuts

Key	Action
`n`	New task
`D`	Duplicate task
`e`	Edit task
`z`	Complete task
`ctrl+d`	Duplicate task
`Space`	Select task / Collapse subtasks
`s`	Stats dashboard
`f`	Filter by tag
`ctrl+e`	Switch project
`p`	Manage plugins
`t`	Switch theme
`ctrl+p`	Command palette / Markdown preview
`ctrl+a`	AI panel
`ctrl+s`	Settings
`x`	Import / Export
`?`	Help
`ctrl+w`	Welcome tour

CLI Automation

Kairo exposes a full CLI API for scripting and CI pipelines, with complete support for parent_id and collapsed state:

# Create a task
kairo api create --title "Finish report" --priority 1

# List by tag
kairo api list --tag work

# Mark complete
kairo api update --id <id> --status done

# Export everything
kairo export --format markdown

Lua Plugin System

local plugin = {
    id = "my-plugin",
    name = "My Plugin",
    version = "1.0.0"
}

kairo.on("task_create", function(event)
    kairo.notify("New task: " .. event.task.title)
end)

return plugin

Browse sample plugins →

Architecture

Input  (CLI · TUI · Lua · AI)
       ↓
Task Service  (single source of truth)
       ↓
SQLite (WAL)  +  optional Git sync
       ↓
Bubble Tea TUI  (instant rendering)

Stack: Bubble Tea · Lip Gloss · SQLite (WAL) · GopherLua · Gemini API · Git

Everything Included

Feature	Status
Local-first SQLite storage	✅
Nested tasks & folders	✅
32 themes, live switching	✅
Keyboard-only workflow	✅
Recurring tasks	✅
Git sync (no backend)	✅
Lua plugin system	✅
CLI automation API	✅
AI assistant (optional)	✅
MCP server	✅
Free & open source	✅

Configuration

Kairo can be configured via config.toml in your application data directory.

Task List

You can customize the fields shown on the right side of the task list:

[list.order]
right = ["tags", "due", "priority"]

Valid values for right are: tags, due, priority.

Task Fields

Minimal Due Mode: Abbreviate "overdue" to "OD" and use a fixed-width column for consistent task list alignment. Enabled by default.
```
[list.fields.due]
minimal = true
```
wait_until: Hide a task from the task list until the specified datetime. If the task is recurring, new instances are not generated/shown until wait_until has passed. Format: yyyy-MM-dd HH:mm.
until: Stop generating new recurring instances after the specified datetime. Existing instances may remain visible. Format: yyyy-MM-dd HH:mm.

Auto-generated on first run at:

Linux: ~/.config/kairo/config.toml
macOS: ~/Library/Application Support/kairo/config.toml
Windows: %APPDATA%\kairo\config.toml

Option	Description	Default
`theme`	UI theme name	`catppuccin`
`vim_mode`	Vim keybindings	`false`
`show_help`	Help footer	`true`
`show_id`	Task IDs in detail view	`true`
`animations`	UI animations	`true`
`rainbow`	Animated rainbow logo	`false`

Prefer not to edit files? ctrl+s opens the in-app settings menu.

Roadmap

Encrypted multi-workspace support
Event-sourced sync engine
Sandboxed plugin environment
Smart task suggestions
Plugin marketplace
Streaming performance optimizations

Star History

Contributing

PRs are welcome — especially for themes, plugins, performance, and docs. If something bugs you, fix it.

Huge thanks to @Tornado300 and @riodelphino for key bug fixes and improvements that made Kairo better for everyone.

If Kairo saves you time, a ⭐ helps other developers find it.

Built for the terminal. Built for focus. Built for you.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Kairo

Why Kairo?

Quick Start

Features

⚡ Genuinely Fast

🗂 Nested Tasks & Hierarchy

🔁 Recurring Tasks

🔒 Your Data, Locally

🧭 Interactive Stats Dashboard

🤖 AI — Optional, Never Intrusive

🎨 Beautiful by Default

🧩 Extensible to the Core

🎨 Tag Highlighting

Keyboard Shortcuts

CLI Automation

Lua Plugin System

Architecture

Everything Included

Configuration

Task List

Task Fields

Roadmap

Star History

Contributing

FilesExpand file tree

README.md

Latest commit

History

README.md

File metadata and controls

Kairo

Why Kairo?

Quick Start

Features

⚡ Genuinely Fast

🗂 Nested Tasks & Hierarchy

🔁 Recurring Tasks

🔒 Your Data, Locally

🧭 Interactive Stats Dashboard

🤖 AI — Optional, Never Intrusive

🎨 Beautiful by Default

🧩 Extensible to the Core

🎨 Tag Highlighting

Keyboard Shortcuts

CLI Automation

Lua Plugin System

Architecture

Everything Included

Configuration

Task List

Task Fields

Roadmap

Star History

Contributing