📚 Kairo

✨ A fast, keyboard-driven task manager that lives in your terminal — and never phones home.

---

⚡ Install & run in seconds

Pick your platform:

🍺 macOS (Homebrew)

brew tap programmersd21/kairo_tap && brew install --cask kairo

🐧 Linux / macOS (curl)

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

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

▶️ Run

kairo

Press n → create your first task.

Done writing? → ctrl+s to save your task!

---

🧠 One-line definition

Kairo is a terminal task manager built in Go for developers who want speed, structure, and full local control.

---

🔥 Why this exists

Most task managers are built wrong for developers:

• GUI apps → slow, mouse-driven, context switching
• Plain-text tools → flexible but no structure or querying
• Cloud apps → lock-in, subscriptions, data ownership loss
• Legacy TUIs → powerful but outdated UX

Kairo is the missing middle:

A modern, scriptable, AI-aware, local-first task system inside your terminal

---

✨ Core capabilities

🔒 Data sovereignty

• SQLite storage (WAL-enabled)
• Fully offline operation
• Optional Git-backed sync (no backend)
• Export: JSON / CSV / Markdown / plain text

⚡ Speed at every layer

• Sub-millisecond fuzzy search with ranked results
• Full keyboard control (no mouse)
• Vim mode (j/k/gg/G)
• Natural language deadlines (tomorrow 10am, next friday, in 2 hours)

🧩 Extensibility

• Lua plugin system (event hooks: task_create, task_update, app_start, etc.)
• Headless CLI API for automation
• MCP server exposing full task schema to AI agents
• Custom themes via Lua or config

🤖 AI (optional)

• Gemini integration (2.0 / 2.5 / 3.1 flash)
• Full task CRUD from chat panel
• Toggle anytime (ctrl+a)
• Fully disabled unless invoked

🎨 Terminal UI

• Bento-style layout with Lip Gloss styling
• 32 built-in themes (dark/light/hybrid)
• Live theme switching (t)
• Full-viewport rendering (no terminal bleed-through)
• Cinematic animations for create/complete/delete

---

🧭 Feature snapshot

Capability	Status
Local-first storage	✅
Full TUI with themes	✅
Keyboard-only workflow	✅
Git sync (no backend)	✅
Lua plugin system	✅
CLI automation API	✅
AI assistant	✅
MCP server	✅
Free & open source	✅

---

🚀 Quick commands

kairo api create --title "Finish report"
kairo api list --tag work
kairo api update --id <id> --status done
kairo export --format markdown
kairo sync
kairo mcp

---

🧱 Architecture

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

---

🧠 Plugin system (Lua)

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

Lua API: create_task, update_task, delete_task, list_tasks, on, notify

Events: task_create · task_update · task_delete · app_start · app_stop

---

⌨️ Keyboard shortcuts

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

---

📦 Full capability set

• Views: Inbox, Today, Upcoming, Completed, by Tag, Priority
• Fuzzy command palette (ctrl+p)
• Shell completions (bash/zsh/fish/powershell)
• Import/export: JSON, CSV, Markdown
• Git-backed sync (per-task JSON)
• MCP server for AI agents
• Plugin hooks for automation

---

🚀 Automation API

kairo api create --title "task" --priority 1
kairo api list --tag work
kairo api update --id <id> --status done
kairo api delete all

JSON mode:

kairo api --json '{"action":"create","payload":{"title":"API task"}}'

Extras:

kairo api set_theme --theme nord
kairo api plugin_list
kairo export --format csv
kairo sync
kairo mcp

---

🧩 Plugin system (full example)

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

---

🧱 Architecture stack

• TUI: Bubble Tea (state machine)
• Styling: Lip Gloss
• Storage: SQLite (WAL)
• Search: in-memory fuzzy index
• Plugins: GopherLua VM
• Sync: Git-based per-task files
• AI: Gemini tool-calling API

---

🗺 Roadmap

• encrypted multi-workspace support
• event-sourced sync engine
• sandboxed plugins
• smart task suggestions
• plugin marketplace
• streaming performance optimizations

---

⚙️ Configuration

Auto-generated on first run:

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

In-app config: ctrl+s (settings menu)

---

🤝 Contributing

PRs welcome:

• themes
• plugins
• performance
• docs

Special thanks to @Tornado300 for key bug fixes and contributions.

---

⭐ Star this repo

If Kairo improves your workflow, star it so more developers can discover it.

---

Fast. Local. Scriptable. Terminal-native.