📝 Kairo

⌛ Time, executed well.

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

🎯 Instant Responsiveness — Sub-millisecond task searching and navigation
🎨 Premium UI Design — Modern color palette with accessibility at its core
⌨️ Keyboard-First — Complete control without ever touching a mouse
🔐 Offline-First — Your data lives locally in SQLite, always under your control
🔗 Git-Backed Sync — Optional distributed sync leveraging Git's architecture
🧩 Extensible — Lua-based plugins for custom workflows
📱 Responsive Layout — Gracefully adapts to any terminal size

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

✨ Core Features

Feature	Description
Task Engine	Title, description (Markdown), tags, priority levels, deadlines, status tracking
Smart Filtering	Multiple views: Inbox, Today, Upcoming, Completed, by Tag, by Priority
Fuzzy Search	Lightning-fast command palette with ranked results
Strike Animation	Visual feedback when completing tasks with 'z'
Offline Storage	SQLite with WAL for reliability and concurrent access
Git Sync	Optional repository-backed sync with per-task JSON files
Lua Plugins	Extend the app with custom commands and views
Import/Export	JSON and Markdown support for data portability
Modern Themes	4 built-in themes (Midnight, Dracula, Nord, Paper) with user customization
Minimalist UI	Breathable, clean design system with standard Unicode compatibility

🎨 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
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

Shortcut	Action
`ctrl+p`	🔍 Open Command Palette
`z`	⚡ Strike (toggle completion with animation)
`tab` / `shift+tab`	→ / ← Switch views
`n`	➕ Create new task
`e`	✏️ Edit selected task
`enter`	👁️ View task details
`d`	🗑️ Delete task
`t`	🎨 Cycle themes
`?`	❓ Show help menu
`q`	❌ Quit

View Filters

Shortcut	View
`1`	Inbox — Active tasks
`2`	Today — Due today
`3`	Upcoming — Future deadlines
`4`	Completed — Done tasks
`5`	Tags — Filter by tag
`6`	Priority — Filter by priority

Pro Tips

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

OS	Path
Windows	`%APPDATA%\kairo\config.toml`
macOS	`~/Library/Application Support/kairo/config.toml`
Linux	`~/.config/kairo/config.toml`

Quick Setup

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

Then edit to customize:

Theme selection — Choose from 12 built-in themes:
- Dark: Catppuccin (Default), Midnight, Aurora, Cyberpunk, Dracula, Nord
- Light: Vanilla, Solarized, Rose, Matcha, Cloud, Sepia
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

🏗 Architecture

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

Core Components

Component	Role
UI Layer (Bubble Tea)	Elm-inspired TUI framework with state-machine pattern for mode management
Storage (SQLite)	Pure Go database with WAL for reliability and concurrent access
Sync Engine (Git)	Distributed "no-backend" sync with per-task JSON files
Search (Fuzzy Index)	In-memory ranked matching with sub-millisecond results
Plugins (Gopher-Lua)	Lightweight Lua VM for user extensions

Data Flow

User Input → Bubble Tea Loop → Active Component
    ↓
Immediate DB Persistence → Optional Git Sync
    ↓
UI Re-render → Instant User Feedback

🔌 Plugins (Lua)

Extend Kairo with custom commands and views using Lua. Place .lua files in your plugins directory.

Plugin Metadata

return {
    id = "my-plugin",
    name = "My Custom Plugin",
    description = "Does something awesome",
    author = "You",
    version = "1.0.0",
    -- commands and views defined below
}

API: Tasks

-- Create, read, update, delete tasks
kairo.create_task({title, description, status, priority, tags})
kairo.get_task(id)
kairo.update_task(id, {title, status, ...})
kairo.delete_task(id)
kairo.list_tasks({statuses, tag, priority, sort})

API: UI

-- Send notifications to the user
kairo.notify(message, is_error)

Example: Cleanup Command

-- plugins/cleanup.lua
return {
    id = "cleanup",
    name = "Cleanup Done Tasks",
    description = "Removes all completed tasks",
    commands = {
        {
            id = "run-cleanup",
            title = "Cleanup: Remove Done",
            run = function()
                local tasks = kairo.list_tasks({statuses = {"done"}})
                for _, t in ipairs(tasks) do
                    kairo.delete_task(t.id)
                end
                kairo.notify("Cleanup complete!", false)
            end
        }
    }
}

🌴 Project Structure

kairo/
├── cmd/kairo/              # Main entry point
├── internal/
│   ├── app/                # Application state & messages
│   ├── core/               # Task model & core logic
│   ├── config/             # Configuration parsing
│   ├── storage/            # SQLite repository
│   ├── sync/               # Git sync engine
│   ├── search/             # Fuzzy search index
│   ├── plugins/            # Lua plugin host
│   └── ui/                 # Terminal UI components
│       ├── styles/         # Premium design system
│       ├── theme/          # Color themes
│       ├── tasklist/       # Main task list view
│       ├── detail/         # Task detail view
│       ├── editor/         # Task editor
│       ├── palette/        # Command palette
│       ├── keymap/         # Keyboard bindings
│       ├── help/           # Help overlay
│       ├── theme_menu/     # Theme switcher
│       └── plugin_menu/    # Plugin manager
├── configs/                # Example configuration
├── plugins/                # Sample plugins
├── DESIGN_SYSTEM.md        # Complete design documentation
├── CONTRIBUTING.md         # Contributing guidelines
└── README.md               # This file

🤝 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

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

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

📝 Kairo

✨ A Premium Terminal Task Manager Designed for Focused Execution

✨ Core Features

🎨 Design System

Design Philosophy

⌨️ Keyboard Navigation

Essential Commands

View Filters

Pro Tips

⚙️ Configuration

Config Location

Quick Setup

🔄 Git Sync

🏗 Architecture

Core Components

Data Flow

🔌 Plugins (Lua)

Plugin Metadata

API: Tasks

API: UI

Example: Cleanup Command

🌴 Project Structure

🤝 Contributing

Areas for Contribution

📜 License

🗺 Roadmap

💡 Philosophy

📞 Support

FilesExpand file tree

README.md

Latest commit

History

README.md

File metadata and controls

📝 Kairo

✨ A Premium Terminal Task Manager Designed for Focused Execution

✨ Core Features

🎨 Design System

Design Philosophy

⌨️ Keyboard Navigation

Essential Commands

View Filters

Pro Tips

⚙️ Configuration

Config Location

Quick Setup

🔄 Git Sync

🏗 Architecture

Core Components

Data Flow

🔌 Plugins (Lua)

Plugin Metadata

API: Tasks

API: UI

Example: Cleanup Command

🌴 Project Structure

🤝 Contributing

Areas for Contribution

📜 License

🗺 Roadmap

💡 Philosophy

📞 Support