kairo

✨ A Premium Terminal Task Manager Designed for Focused Execution

🏃🏻 Kairo is a lightning-fast, keyboard-first task management application
built for developers and power users.

It combines the simplicity of a command-line tool
with the sophistication of a modern, premium design system.

🎯 BubbleTea Motion System — Liquid glass interactions with elastic physics
🎨 Premium UI Design — Modern Bento-style layout with soft, rounded aesthetics
⌨️ Keyboard-First — Complete control without ever touching a mouse
🖥️ Seamless Rendering — Pixel-perfect background fills the entire viewport, no terminal bleed-through
🔐 Offline-First — Your data lives locally in SQLite, always under your control
🔗 Git-Backed Sync — Optional distributed sync leveraging Git's architecture
🧩 Extensible — Unified Lua plugin system and CLI automation API
📱 Responsive Layout — Gracefully adapts to any terminal size
🤖 Automation-Friendly — Headless API for external scripts and CI/CD
🌊 Boba Liquid Feel — UI elements behave with soft inertia and fluid clustering

Built with Bubble Tea (TUI framework), Lip Gloss (terminal styling), and SQLite (local storage).

✨ Core Features

🤩 Star History

📦 Installation

macOS (Homebrew)

brew tap programmersd21/kairo https://github.com/programmersd21/kairo
brew install --cask programmersd21/kairo/kairo

Linux / macOS (curl)

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

Installs to $HOME/.local/bin/kairo (fallback: /usr/local/bin/kairo) and attempts to persist the PATH update in your shell profile when needed.

Windows (PowerShell)

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

Installs to %USERPROFILE%\AppData\Local\Programs\kairo\kairo.exe and adds the install directory to your user PATH.

Any other OS

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

OR download a prebuilt binary from the Releases page.

Updates

kairo update

Downloads the latest GitHub Release for your OS/arch, verifies it against checksums.txt, and safely replaces the installed binary. On Windows, Kairo will automatically close to apply the update; simply re-run kairo once the terminal returns.

Startup Notifications: Kairo automatically checks for updates on startup. If a newer version is available, a notification will appear in the footer (e.g., Update: v1.2.1 → v1.2.2) directing you to run the update command.

🤖 Automation & CLI API

Kairo provides a stable CLI API for external automation. Every operation available in the TUI can be performed via the api subcommand.

Usage

# List tasks with a specific tag
kairo api list --tag work

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

# Update a task
kairo api update --id <task-id> --status done

# Delete all tasks (soft-delete)
kairo api delete all

# Advanced JSON interface
kairo api --json '{"action": "create", "payload": {"title": "API Task", "tags": ["bot"]}}'

Other CLI Commands

# Check installed version
kairo version

# Update to the latest version
kairo update

# Export tasks
kairo export --format json --out tasks.json
kairo export --format markdown --out tasks.md

# Import tasks
kairo import --format json --in tasks.json

# Shell completion (bash, zsh, fish, powershell)
# Automatic install:
kairo completion zsh install

# Manual install (add to your shell profile):
# source <(kairo completion zsh)
kairo completion zsh

# Get help for any command
kairo help
kairo help api
kairo help export

# Sync with Git (if configured)
kairo sync

🔌 Plugins (Lua)

Extend Kairo with custom logic, event hooks, commands, and views using Lua.

Plugin Structure

-- plugins/my-plugin.lua
local plugin = {
    id = "my-plugin",
    name = "My Plugin",
    description = "Reacts to tasks",
    version = "1.0.0",
}

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

-- Register custom commands
plugin.commands = {
    { id = "hello", title = "Say Hello", run = function() kairo.notify("Hello!") end }
}

return plugin

Supported Events

• task_create
• task_update
• task_delete
• app_start
• app_stop

Lua API Reference

🎨 Design System

Kairo features a minimalist design system optimized for clarity and focus.

Design Philosophy

• Breathable Layout — Reduced padding and thin borders for a clean, modern look
• Seamless Backdrop — Custom rendering engine ensures the theme background covers the entire terminal window
• Instant Feedback — Smooth strikethrough animations when completing tasks
• Keyboard-First — All interactions optimized for speed
• High Compatibility — Uses standard Unicode symbols for consistent rendering across all terminals

⌨️ Keyboard Navigation

Essential Commands

Plugin Menu Shortcuts

View Shortcuts

Pro Tips

• Press f to open the tag filter input modal for direct tag entry
• Type tag name and press enter to apply filter, or esc to cancel
• Type #tag in the command palette to jump to a specific tag
• Type pri:0 to filter tasks by priority level
• Use ctrl+s to save while editing
• Press esc to cancel and return to the list

⚙️ Configuration

Config Location

Quick Setup

cp configs/kairo.example.toml ~/.config/kairo/config.toml

Then edit to customize:

• Theme selection — Choose from 32 built-in themes:
  • Premium Dark: catppuccin (Default), midnight, aurora, cyberpunk, dracula, nord, obsidian_bloom, neon_reef, carbon_sunset, vanta_aurora, plasma_grape, midnight_jade, synthwave_minimal, graphite_matcha
  • Premium Light: vanilla, solarized, rose, matcha, cloud, sepia, cloud_dancer, sakura_sand, olive_mist, terracotta_air, vanilla_sky, peach_fuzz_neo, coastal_drift, matcha_latte
  • Hybrid/Specialized: digital_lavender, neo_mint_system, sunset_gradient_pro, forest_sanctuary
• Keybindings — Rebind any keyboard shortcut
• View ordering — Customize your task view tabs
• Sync settings — Configure Git repository sync

🔄 Git Sync

Enable optional distributed sync by setting sync.repo_path in your config.

Kairo uses a unique no-backend approach:

• Each task is stored as an individual JSON file
• Changes are committed locally with automatic messages
• Perform sync manually or on-demand
• Git's branching and merging handle conflicts transparently

# Manual sync
kairo sync

📅 Natural Language Deadlines

Kairo's smart parser understands natural language, making it effortless to set deadlines without worrying about specific date formats.

When creating or editing a task, you can input deadlines like:

• Relative days: today, tomorrow, day after tomorrow
• Specific days: monday, next friday, this sunday
• Time-based: in 2 hours, at 5pm, tomorrow at 10am
• Dates: august 24, 24th of april

Powered by the when library, Kairo ensures your deadlines are always parsed intuitively.

🏗 Architecture

Kairo is built with a modular architecture designed for performance, extensibility, and data sovereignty.

Core Components

Data Flow

User Input/API/Lua → Task Service → Hooks System
    ↓
Immediate DB Persistence → Optional Git Sync
    ↓
UI Re-render → Instant User Feedback

🌴 Project Structure

kairo/
├── .github/
│   ├── ISSUE_TEMPLATE/
│   │   ├── bug_report.md
│   │   └── feature_request.md
│   ├── workflows/
│   │   ├── ci.yml
│   │   └── release.yml
│   └── PULL_REQUEST_TEMPLATE.md
├── cmd/
│   └── kairo/
│       └── main.go
├── internal/
│   ├── api/
│   │   └── api.go
│   ├── app/
│   │   ├── model.go
│   │   └── msg.go
│   ├── buildinfo/
│   │   └── buildinfo.go
│   ├── completion/
│   │   └── completion.go
│   ├── config/
│   │   ├── config.go
│   │   └── config_test.go
│   ├── core/
│   │   ├── codec/
│   │   │   ├── json.go
│   │   │   └── markdown.go
│   │   ├── nlp/
│   │   │   └── deadline.go
│   │   ├── core_test.go
│   │   ├── ids.go
│   │   ├── task.go
│   │   └── view.go
│   ├── hooks/
│   │   └── hooks.go
│   ├── lua/
│   │   └── engine.go
│   ├── plugins/
│   │   └── host.go
│   ├── search/
│   │   ├── fuzzy.go
│   │   ├── fuzzy_test.go
│   │   └── index.go
│   ├── service/
│   │   └── service.go
│   ├── storage/
│   │   ├── migrations.go
│   │   ├── repo.go
│   │   └── repo_test.go
│   ├── sync/
│   │   └── engine.go
│   ├── ui/
│   │   ├── detail/
│   │   │   └── model.go
│   │   ├── editor/
│   │   │   └── model.go
│   │   ├── help/
│   │   │   └── model.go
│   │   ├── keymap/
│   │   │   ├── keymap.go
│   │   │   ├── keymap_test.go
│   │   │   ├── normalize.go
│   │   │   └── normalize_test.go
│   │   ├── palette/
│   │   │   └── model.go
│   │   ├── plugin_menu/
│   │   │   └── model.go
│   │   ├── render/
│   │   │   ├── easing.go
│   │   │   └── render.go
│   │   ├── styles/
│   │   │   └── styles.go
│   │   ├── tasklist/
│   │   │   └── model.go
│   │   ├── theme/
│   │   │   └── theme.go
│   │   └── theme_menu/
│   │       └── model.go
│   ├── updater/
│   │   ├── checksums.go
│   │   ├── download.go
│   │   ├── extract.go
│   │   ├── github.go
│   │   ├── updater.go
│   │   └── windows_helper.go
│   └── util/
│       ├── paths.go
│       └── util_test.go
├── plugins/
│   ├── auto-cleanup.lua
│   ├── auto-tagger.lua
│   ├── sample.lua
│   └── task-logger.lua
├── screenshots/
│   └── demo.gif
├── scripts/
│   ├── install.ps1
│   └── install.sh
├── local/
│   └── demo_preset.json
├── .gitignore
├── .goreleaser.yaml
├── CHANGELOG.md
├── go.mod
├── go.sum
├── LICENSE
├── Makefile
├── README.md
└── VERSION.txt

🤝 Contributing

We welcome contributions! Please see CONTRIBUTING.md for guidelines and CODE_OF_CONDUCT.md for our code of conduct.

Areas for Contribution

• ✨ New themes and design improvements
• 🐛 Bug fixes and performance enhancements
• 📚 Documentation and tutorials
• 🧩 Plugins and extensions
• 🌍 Translations and localization

💙 Community Legend(s)

• @Tornado300 — Contributed significantly by reporting issues that led to multiple critical bug fixes.

📜 License

Kairo is released under the MIT License.

🗺 Roadmap

• Multi-workspace support with encryption at rest
• Incremental DB-to-UI streaming for large datasets
• Conflict-free sync via append-only event log
• Sandboxed Plugin SDK
• Smart suggestions and spaced repetition
• Enhanced mobile/SSH terminal support
• Community plugin marketplace

💡 Philosophy

Kairo is built on the belief that task management should be fast, simple, and under your control. We prioritize:

✅ Your Privacy — Data stays on your machine
✅ Your Freedom — Open source, MIT licensed
✅ Your Time — Lightning-fast interactions
✅ Your Experience — Premium, thoughtful design

Every feature is carefully considered to maintain focus and avoid complexity creep.

📞 Support

• 🐛 Report bugs on GitHub Issues
• 💬 Discuss ideas on GitHub Discussions
• ⭐ Show your support with a star!

Made with ❤️ for focused execution. Start organizing your time today.