Kairo: A Local-First Terminal Task Manager with Lua Plugins, Git Sync, and an MCP Server

Soumalya Das — Wed, 29 Apr 2026 02:08:10 +0000

Most CLI Task Managers Fail in the Same Two Ways. Kairo Tries a Third Path.

You know that feeling when your task manager gets in the way of your actual work?

You're deep in the terminal. Everything is keyboard-driven, fast, focused. Then you need to jot down a task — and suddenly you're reaching for the mouse, switching to a browser tab, logging into yet another cloud service that owns your data and charges you monthly for the privilege.

Kairo was built because of that feeling.

What Is Kairo?

Kairo is a terminal-native task manager for developers — built around a simple premise: your tasks should live where your brain already does.

No browser tabs. No subscriptions. No mouse. Just a fast, beautiful TUI that lives in your terminal and stores everything locally in SQLite.

brew install programmersd21/kairo/kairo
kairo

Press n to create your first task. That's the entire onboarding.

The Problem With Every Other Option

Every developer eventually runs into the same three-way trap:

The problem	Why it hurts
GUI apps (Notion, Linear, Todoist)	Pull you out of your flow to manage a task about your flow
Cloud tools	Your data lives on someone else's server, behind an account, behind a paywall
Plain-text tools (`todo.txt`, Taskwarrior)	Powerful but spartan — no structure, no search, no visual feedback

Kairo sits in none of those buckets. It's the tool you'd build for yourself if you had the time.

What It Actually Does

Fast — genuinely fast

Sub-millisecond fuzzy search. Full Vim keybindings (j/k/gg/G). Natural language deadlines — type tomorrow 10am or next friday and it just works. You never have to leave the keyboard, and you never wait for it.

Your data is yours

Everything lives in a local SQLite database with WAL mode. Fully offline by default. If you want sync, it's Git-backed — no backend, no account, no lock-in. Export to JSON, CSV, Markdown, or plain text whenever you want.

It grows with you

A Lua plugin system lets you hook into task lifecycle events:

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

A headless CLI API means you can automate anything from scripts and pipelines:

# Create a task from anywhere in your workflow
kairo api create --title "Finish report" --priority 1

# Query and filter
kairo api list --tag work

# Export everything
kairo export --format markdown

# Git sync — no backend required
kairo sync

An MCP server opens Kairo up to AI agents that can read and manage your tasks directly:

kairo mcp        # stdio mode
kairo mcp 8080   # SSE mode

AI — on your terms

Optional Gemini integration (2.0 / 2.5 / 2.5 Flash). Toggle it with ctrl+a. It never runs unless you invoke it. Your workflow, your call.

Beautiful by default

32 built-in themes. Live switching with t. Bento-style layout with real-time Markdown preview. Cinematic animations for create, complete, and delete. It's a terminal app you'll actually enjoy looking at.

The Shortcuts That Matter

Key	Action
`n`	New task
`e`	Edit
`z`	Complete
`d`	Delete
`t`	Switch theme
`f`	Filter by tag
`ctrl+p`	Command palette
`ctrl+a`	AI panel
`?`	Help

How It's Built

Kairo is written in Go, built on a stack that prioritizes rendering performance and correctness:

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

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

Go was chosen for the same reason you'd choose it for any CLI tool: fast startup, single static binary, no runtime dependency to manage.

Installation

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

Works best on Alacritty, Kitty, and WezTerm. Some terminals may have rendering quirks — see issue #16.

Everything Included, Nothing Gated

Feature	Status
Local-first SQLite storage	✅
Full TUI with 32 themes	✅
Keyboard-only workflow + Vim bindings	✅
Natural language date parsing	✅
Git sync (no backend)	✅
Lua plugin system	✅
CLI automation API	✅
AI assistant (optional, opt-in)	✅
MCP server for AI agents	✅
Free & open source (MIT)	✅

No tiers. No "Pro" features. Everything ships in the binary.

What's Coming

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

Contributing

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

A special thank you to @Tornado300 for key contributions and bug fixes that made Kairo better for everyone.

Final Thought

Kairo isn't trying to replace your entire productivity stack. It's trying to be the one task manager that never makes you context-switch, never holds your data hostage, and never feels like it was designed for someone else.

If that's what you've been missing, it's worth five minutes of your terminal.

🔗 github.com/programmersd21/kairo

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

DEV Community: Soumalya Das