task-assistant

Task

The AI-first task manager. Semantic search, agent-friendly APIs, and a TUI that stays out of your way.

Documentation: See the comprehensive Code Wiki for detailed architecture and API documentation.

The Problem

Task managers weren't built for AI. You can't pipe tasks to Claude, search by meaning, or batch-create from parsed text. When you need your AI assistant to manage tasks, you're stuck copying and pasting.

The Solution

Task bridges humans and AI agents. A clean CLI for scripts, an interactive TUI for focus, and an HTTP API that speaks JSON. Search tasks by meaning, not keywords. Create dozens of tasks in one call. Every feature works for both you and your AI tools.

Key Features

• Semantic Search — find tasks by meaning, not just keywords
• Agent Integration — JSON output, batch operations, context metadata
• Recurring Tasks — natural language patterns ("every Monday", "1st of month")
• Google Calendar — one-way sync keeps your calendar current
• Multiple Interfaces — CLI for scripts, TUI for focus, API for agents
• Local-first — SQLite database, your data stays yours

Claude Code Integration

Task CLI includes a Claude Code skill for natural language task management. Once installed, just ask:

"Add a task to review PR #42, due tomorrow"

"What tasks are overdue?"

"Show me all tasks related to authentication"

Install in Claude Code:

/plugin marketplace add lauriliivamagi/task
/plugin install task-assistant@task

See How to Use the Claude Code Skill for details.

Quick Start

Install

From GitHub Releases (recommended):

# Download the latest binary for your platform
curl -L https://github.com/lauriliivamagi/task/releases/latest/download/task-linux-x86_64 -o task
chmod +x task
sudo mv task /usr/local/bin/

With Deno:

deno install --global -A --name task --config deno.json src/main.ts

From source:

git clone https://github.com/lauriliivamagi/task.git
cd task
deno task compile  # Creates ./task binary

Your First Tasks

# Create a task
task add "Review PR #42" --due tomorrow --tag review

# List active tasks
task list

# Search by meaning (requires embedding provider)
task list --semantic "authentication bugs"

# Launch the TUI
task tui

Interfaces

CLI

Run task --help for all commands. Common operations:

task add "Title" --project Work --due "next friday"
task list --status in-progress
task update 42 --status done
task view 42

See CLI Reference for complete documentation.

TUI

Launch with task tui. Navigate with vim-style keys or arrows.

Key	Action
j/k	Move up/down
n	New task
x	Toggle done
e	Edit title
Tab	Switch panels
Shift+P	Command palette
?	Show all shortcuts
q	Quit

Shortcuts are customizable via ~/.task-cli/config.json.

HTTP API

Start the server:

task serve --port 3000

The API supports all task operations. See CLAUDE.md for endpoint documentation.

Configuration

Configuration lives in ~/.task-cli/config.json:

{
  "logLevel": "info",
  "work": {
    "repos_dir": "~/git",
    "ide_command": "claude"
  }
}

Environment variables override config:

TASK_CLI_LOG_LEVEL=debug
EMBEDDING_PROVIDER=ollama    # or openai, gemini
OPENAI_API_KEY=sk-...        # for OpenAI embeddings

Data storage:

~/.task-cli/
├── config.json       # Configuration
├── databases/        # SQLite databases (multi-db support)
├── logs/             # Daily rotated logs
└── templates/        # Task sharing templates

Semantic Search Setup

To search by meaning, configure an embedding provider:

# Ollama (local, free)
export EMBEDDING_PROVIDER=ollama

# OpenAI
export EMBEDDING_PROVIDER=openai
export OPENAI_API_KEY=sk-...

# Google Gemini
export EMBEDDING_PROVIDER=gemini
export GEMINI_API_KEY=...

Then backfill embeddings and search:

task embeddings backfill
task list --semantic "urgent customer issues"

Documentation

Tutorials

Step-by-step lessons to get you started:

• Quick Start — your first tasks in 5 minutes
• AI Integration — use with Claude Code and AI assistants

How-to Guides

Solve specific problems: