feat: implement focus mode with integrated timer and task tracking engine

Author: programmersd21

CHANGELOG.md

@@ -5,6 +5,19 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## v1.6.0 (2026-05-09)
+
+### Added
+* **Integrated Focus Engine (Pomodoro)**: A native deep-work timer to bridge the gap between planning and execution.
+  * `f` → Open Focus Engine. If a task is selected in the list, it's automatically tracked.
+  * **Minimalist "Liquid Glass" UI**: A dedicated focus mode with countdown timer and state management (Focus/Break).
+  * **"DEEP WORK" Pulse**: Live visual feedback in the footer when a session is active.
+  * **Automatic Persistence**: Completed focus sessions are logged to the database and linked to specific tasks for future analytics.
+* **Onboarding Update**: Added Focus Engine training to the Welcome Tour.
+
+### Changed
+* **Keybinding Refinement**: To accommodate the Focus Engine, the "Filter by Tag" shortcut has been moved from `f` to `ctrl+f`.
+
 ## v1.5.6 (2026-05-08)
 
 ### Added

README.md

@@ -85,8 +85,10 @@ Tasks reappear automatically on a schedule. Weekly (`mon,wed,fri`) or monthly (`
 ### 🔒 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. Project organization is preserved in your database.
 
-### 🧭 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.
+### 🧭 Interactive Stats Dashboard & Focus Engine
+Press `s` to open a next-gen "Command Center". Visualize your **Productivity DNA**, track real-time momentum, and get behavioral insights. 
+
+**Focus Engine**: Press `f` to launch the native Pomodoro timer. Track deep work sessions directly against your active tasks. When a session is active, Kairo displays a "DEEP WORK" pulse in the footer.
 
 ### 🤖 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, including assigning to specific projects. Invisible until you need it.
@@ -123,7 +125,8 @@ diy     = "bg=accent"
 | `ctrl+d` | Duplicate task |
 | `Space` | Select task / Collapse subtasks |
 | `s` | Stats dashboard |
-| `f` | Filter by tag |
+| `f` | Focus engine |
+| `ctrl+f` | Filter by tag |
 | `ctrl+e` | Switch project |
 | `p` | Manage plugins |
 | `t` | Switch theme |
@@ -144,6 +147,7 @@ diy     = "bg=accent"
   <img src="screenshots/theme_menu.png" width="30%" />
   <img src="screenshots/dashboard.png" width="30%" />
   <img src="screenshots/welcome_tour.png" width="30%" />
+  <img src="screenshots/focus_mode.png" width="30%" />
 </div>
 
 ---

VERSION.txt

@@ -1 +1 @@
-1.5.7
+1.6.0

internal/app/model.go

@@ -31,6 +31,7 @@ import (
 	"github.com/programmersd21/kairo/internal/ui/ai_panel"
 	"github.com/programmersd21/kairo/internal/ui/detail"
 	"github.com/programmersd21/kairo/internal/ui/editor"
+	"github.com/programmersd21/kairo/internal/ui/focus"
 	"github.com/programmersd21/kairo/internal/ui/help"
 	"github.com/programmersd21/kairo/internal/ui/import_export_menu"
 	"github.com/programmersd21/kairo/internal/ui/keymap"
@@ -101,6 +102,7 @@ const (
 	ModeOnboarding
 	ModeStats
 	ModeProjectSwitcher
+	ModeFocus
 )
 
 type Model struct {
@@ -137,6 +139,7 @@ type Model struct {
 	set        settings.Model
 	iem        import_export_menu.Model
 	stats      stats.Model
+	foc        focus.Model
 	aiPanel    ai_panel.Model
 	aiClient   *ai.Client
 	aiKey      string
@@ -260,6 +263,7 @@ func New(ctx context.Context, cfg config.Config, svc service.TaskService) (tea.M
 	m.set = settings.New(m.s, cfg)
 	m.iem = import_export_menu.New(m.s)
 	m.stats = stats.New(m.s)
+	m.foc = focus.New(m.s)
 	m.aiPanel = ai_panel.New(m.s)
 	m.aiChan = make(chan ai_panel.AIChunkMsg, 100)
 	m.aiKey = cfg.App.GeminiAPIKey
@@ -813,6 +817,19 @@ func (m *Model) Update(msg tea.Msg) (tea.Model, tea.Cmd) {
 			}(),
 		)
 
+	case focus.SessionDoneMsg:
+		return m, m.createFocusSessionCmd(x.Session)
+
+	case focus.TickMsg:
+		var cmd tea.Cmd
+		m.foc, cmd = m.foc.Update(msg)
+		// If rainbow is off, we still want the pulse to animate,
+		// so we can increment the offset here too.
+		if !m.cfg.App.Rainbow {
+			m.RainbowAnimationOffset = (m.RainbowAnimationOffset + 1) % 7
+		}
+		return m, cmd
+
 	case taskUpdatedMsg:
 		m.rebuildComponentSizes()
 		return m, m.refreshCmd()
@@ -1343,11 +1360,19 @@ func (m *Model) Update(msg tea.Msg) (tea.Model, tea.Cmd) {
 				}
 
 				switch {
-				case km.String() == "f":
+				case keymapMatch(m.km.ViewTag, km):
 					m.tagFilterInput.SetValue(m.tagFilter.Value())
 					m.tagFilterInput.Focus()
 					m.mode = ModeTagFilter
 					return m, nil
+				case keymapMatch(m.km.Focus, km):
+					if item, ok := m.list.Selected(); ok {
+						m.foc.Task = &item.Task
+					} else {
+						m.foc.Task = nil
+					}
+					m.mode = ModeFocus
+					return m, nil
 				case km.String() == " ":
 					// Handle space key for toggle collapse
 					if item, ok := m.list.Selected(); ok && item.HasChildren {
@@ -1546,6 +1571,16 @@ func (m *Model) Update(msg tea.Msg) (tea.Model, tea.Cmd) {
 		var cmd tea.Cmd
 		m.pm, cmd = m.pm.Update(msg)
 		return m, cmd
+	case ModeFocus:
+		if km, ok := msg.(tea.KeyMsg); ok {
+			if keymapMatch(m.km.Back, km) {
+				m.mode = ModeList
+				return m, nil
+			}
+		}
+		var cmd tea.Cmd
+		m.foc, cmd = m.foc.Update(msg)
+		return m, cmd
 	case ModeSettings:
 		var cmd tea.Cmd
 		m.set, cmd = m.set.Update(msg)
@@ -1647,6 +1682,7 @@ func (m *Model) renderMainUI() string {
 	m.tm.SetSize(mainW, availableHeight)
 	m.iem.SetSize(mainW, availableHeight)
 	m.stats.SetSize(mainW, availableHeight)
+	m.foc.SetSize(mainW, availableHeight)
 	if m.edit != nil {
 		m.edit.SetSize(mainW, availableHeight)
 	}
@@ -1688,6 +1724,8 @@ func (m *Model) renderMainUI() string {
 		}
 	case ModeImportExport:
 		body = m.iem.View()
+	case ModeFocus:
+		body = m.foc.View()
 	case ModeStats:
 		body = m.stats.View()
 	case ModeOnboarding:
@@ -2143,11 +2181,36 @@ func (m *Model) renderFooter() string {
 			}
 			versionText = fmt.Sprintf("Update: %s → %s", cur, lat)
 		}
+
+		focusPill := ""
+		if m.foc.Active && (m.mode == ModeList || m.mode == ModeFocus) {
+			pulseStyle := m.s.BadgeDoing
+			if m.foc.State == focus.StateShortBreak || m.foc.State == focus.StateLongBreak {
+				pulseStyle = m.s.BadgeGood
+			}
+
+			text := "DEEP WORK"
+			if m.foc.State != focus.StateFocus {
+				text = "BREAK"
+			}
+
+			// Pulse effect using RainbowAnimationOffset
+			if m.RainbowAnimationOffset%2 == 0 {
+				text = "• " + text + " •"
+			} else {
+				text = "  " + text + "  "
+			}
+
+			focusPill = m.s.TagLeft.Foreground(pulseStyle.GetBackground()).Render() +
+				pulseStyle.Render(text) +
+				m.s.TagRight.Foreground(pulseStyle.GetBackground()).Render() + " "
+		}
+
 		mcpStatus := ""
 		if m.mcpRunning {
 			mcpStatus = makePill("MCP "+styles.IconSuccess) + " "
 		}
-		right = mcpStatus + makePill(syncLogo+versionText) + " "
+		right = focusPill + mcpStatus + makePill(syncLogo+versionText) + " "
 	}
 
 	return render.BarLine(left, right, m.width, m.s.Theme.Bg)
@@ -2357,6 +2420,15 @@ func (m *Model) updateTaskCmd(id string, p core.TaskPatch) tea.Cmd {
 	}
 }
 
+func (m *Model) createFocusSessionCmd(s core.FocusSession) tea.Cmd {
+	return func() tea.Msg {
+		if err := m.svc.Repo().CreateFocusSession(m.ctx, s); err != nil {
+			return errMsg{Err: err}
+		}
+		return nil
+	}
+}
+
 func (m *Model) deleteTaskCmd(id string) tea.Cmd {
 	return func() tea.Msg {
 		before, err := m.svc.GetByID(m.ctx, id)

internal/core/stats.go

@@ -17,6 +17,14 @@ type Event struct {
 	Metadata  string
 }
 
+type FocusSession struct {
+	ID        string
+	TaskID    string
+	StartTime time.Time
+	EndTime   *time.Time
+	Duration  time.Duration
+}
+
 const (
 	EventTypeTaskCreated   = "task_created"
 	EventTypeTaskCompleted = "task_completed"

internal/lua/engine.go

@@ -61,7 +61,7 @@ func (e *Engine) SetupKairoAPI(L *lua.LState) {
 	L.SetField(kairo, "notify", L.NewFunction(e.luaNotify))
 
 	// Meta
-	L.SetField(kairo, "version", lua.LString("1.5.7"))
+	L.SetField(kairo, "version", lua.LString("1.6.0"))
 
 	// Set as global
 	L.SetGlobal("kairo", kairo)

internal/storage/migrations.go

@@ -86,6 +86,18 @@ func migrate(ctx context.Context, db *sql.DB) error {
 			ALTER TABLE tasks ADD COLUMN project TEXT;
 			CREATE INDEX IF NOT EXISTS idx_tasks_project ON tasks(project);
 		`},
+		{6, `
+			CREATE TABLE IF NOT EXISTS focus_sessions (
+				id TEXT PRIMARY KEY,
+				task_id TEXT NULL,
+				start_time_ms INTEGER NOT NULL,
+				end_time_ms INTEGER NULL,
+				duration_ms INTEGER NOT NULL DEFAULT 0,
+				FOREIGN KEY(task_id) REFERENCES tasks(id) ON DELETE SET NULL
+			);
+			CREATE INDEX IF NOT EXISTS idx_focus_sessions_start ON focus_sessions(start_time_ms);
+			CREATE INDEX IF NOT EXISTS idx_focus_sessions_task ON focus_sessions(task_id);
+		`},
 	}
 
 	for _, s := range steps {

internal/storage/repo.go

@@ -890,3 +890,58 @@ func (r *Repository) ListEvents(ctx context.Context) ([]core.Event, error) {
 	}
 	return out, rows.Err()
 }
+
+func (r *Repository) CreateFocusSession(ctx context.Context, s core.FocusSession) error {
+	var taskID any
+	if s.TaskID != "" {
+		taskID = s.TaskID
+	}
+	var endTime any
+	if s.EndTime != nil {
+		endTime = s.EndTime.UTC().UnixMilli()
+	}
+	_, err := r.db.ExecContext(ctx, `
+		INSERT INTO focus_sessions (id, task_id, start_time_ms, end_time_ms, duration_ms)
+		VALUES (?, ?, ?, ?, ?)
+	`, s.ID, taskID, s.StartTime.UTC().UnixMilli(), endTime, int64(s.Duration/time.Millisecond))
+	return err
+}
+
+func (r *Repository) ListFocusSessions(ctx context.Context) ([]core.FocusSession, error) {
+	rows, err := r.db.QueryContext(ctx, `
+		SELECT id, task_id, start_time_ms, end_time_ms, duration_ms
+		FROM focus_sessions
+		ORDER BY start_time_ms DESC
+	`)
+	if err != nil {
+		return nil, err
+	}
+	defer func() {
+		if err := rows.Close(); err != nil {
+			_ = err
+		}
+	}()
+	var out []core.FocusSession
+	for rows.Next() {
+		var id string
+		var taskID sql.NullString
+		var startMs int64
+		var endMs sql.NullInt64
+		var durMs int64
+		if err := rows.Scan(&id, &taskID, &startMs, &endMs, &durMs); err != nil {
+			return nil, err
+		}
+		s := core.FocusSession{
+			ID:        id,
+			TaskID:    taskID.String,
+			StartTime: time.UnixMilli(startMs).UTC(),
+			Duration:  time.Duration(durMs) * time.Millisecond,
+		}
+		if endMs.Valid {
+			t := time.UnixMilli(endMs.Int64).UTC()
+			s.EndTime = &t
+		}
+		out = append(out, s)
+	}
+	return out, rows.Err()
+}