https://github.com/programmersd21/kairo

🤩 Kairo is a fast, keyboard-first terminal task manager in Go 🐹 with offline-first SQLite, Git sync 🔁, fuzzy search 🔍 & Lua plugins 🧩
https://github.com/programmersd21/kairo

bubbletea command-palette cross-platform developer-tools fuzzy-search git go golang lipgloss lua minimal-ui offline open-source plugin-system productivity sqlite task-manager terminal tui

Last synced: about 1 month ago
JSON representation

🤩 Kairo is a fast, keyboard-first terminal task manager in Go 🐹 with offline-first SQLite, Git sync 🔁, fuzzy search 🔍 & Lua plugins 🧩

Host: GitHub
URL: https://github.com/programmersd21/kairo
Owner: programmersd21
License: mit
Created: 2026-04-15T09:46:34.000Z (about 2 months ago)
Default Branch: main
Last Pushed: 2026-04-20T14:06:23.000Z (about 2 months ago)
Last Synced: 2026-04-20T19:03:34.770Z (about 2 months ago)
Topics: bubbletea, command-palette, cross-platform, developer-tools, fuzzy-search, git, go, golang, lipgloss, lua, minimal-ui, offline, open-source, plugin-system, productivity, sqlite, task-manager, terminal, tui
Language: Go
Homepage:
Size: 328 KB
Stars: 26
Watchers: 6
Forks: 1
Open Issues: 2
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
- Security: SECURITY.md

Awesome Lists containing this project

README

          




# 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.




[![Release](https://img.shields.io/github/v/release/programmersd21/kairo?style=for-the-badge&logo=github&color=7c3aed)](https://github.com/programmersd21/kairo/releases)

[![CI](https://img.shields.io/github/actions/workflow/status/programmersd21/kairo/ci.yml?branch=main&style=for-the-badge&logo=github&color=2563eb)](https://github.com/programmersd21/kairo/actions)

[![License: MIT](https://img.shields.io/badge/License-MIT-f59e0b?style=for-the-badge)](https://opensource.org/licenses/MIT)




![Kairo Demo](screenshots/demo.gif)



---

## 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)**

```bash

brew install programmersd21/kairo/kairo

```

**Linux / macOS**

```bash

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

```

**Windows (PowerShell)**

```powershell

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

```

**Go**

```bash

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

```

Then just run:

```bash

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](https://github.com/programmersd21/kairo/issues/16).

---

## Features

![Kairo Home Screen](screenshots/home_screen.png)

### ⚡ 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. Nest tasks via the **Parent** field in the editor, collapse/expand with `Space`, 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.

### 🧭 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. 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.

---

## Keyboard Shortcuts

| Key | Action |

|---|---|

| `n` | New task |

| `e` | Edit task |

| `z` | Complete task |

| `d` | Delete task |

| `Space` | Collapse / expand subtasks |

| `s` | Stats dashboard |

| `f` | Filter by tag |

| `t` | Switch theme |

| `ctrl+p` | Command palette / Markdown preview |

| `ctrl+a` | AI panel |

| `ctrl+s` | Settings |

| `x` | Import / Export |

| `?` | Help |

| `ctrl+d` | Welcome tour |



  

  

  

  

  

  



---

## CLI Automation

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

```bash

# 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  --status done

# Export everything

kairo export --format markdown

```

---

## Lua Plugin System

```lua

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 →](https://github.com/programmersd21/kairo/tree/main/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:

```toml

[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.

    ```toml

    [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](https://github.com/Tornado300) for key bug fixes 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.*

ecosyste.ms

Data

Tools

Indexes

Applications

Experiments

Awesome

https://github.com/programmersd21/kairo

Awesome Lists containing this project

README