tasq

A local-first task manager, exposed as a CLI, an interactive TUI, and a local MCP server, backed by a single SQLite file. Built with Python, uv, Typer, Textual, and the MCP SDK.

See spec.md for the original design and rationale.

What it does

tasq keeps your work in one SQLite file on your machine — no account, no server, no sync — and lets you drive it three ways over the same engine: type commands (tasq …), scroll an interactive board (tasq ui), or let an AI assistant manage tasks through the built-in MCP server. Anything you do one way is immediately visible in the others.

The mental model. A task has a title, a status, a priority (P1–P5), an optional t-shirt size (XS–XL, used for effort estimates), optional scheduled (start) and due dates, a markdown description, and any number of labels. Tasks can be grouped under a project and broken into one level of sub-tasks. Every status change is recorded as an auditable history — you can always see when and why a task moved, not just where it is now.

What you can do with it:

• Capture & organise — add tasks with priority, size, dates, labels, and rich descriptions; group them by project; break them into sub-tasks.
• Track a lifecycle — move tasks through waiting → in-progress → blocked → done/cancelled, each transition logged with an optional comment.
• See what's next — an agenda (overdue + today + upcoming) with effort estimates, and a proposed day-by-day plan that packs open work into your daily focus budget over working days (weekends skipped) — a suggestion, never written back to a task. Export the plan as an HTML report.
• Find things — fuzzy search across titles/descriptions (typos are fine), and a references view that pulls URLs (PRs, JIRAs, docs) out of descriptions so you can jump straight to them.
• Work interactively — a full-screen board (tasq ui) to scroll, quick-edit priority/size/status, create/schedule/delete tasks, open references, and view the plan — all with the keyboard.
• Hand off to (and resume) AI agents — link a task to the AI coding session you worked on it in (agent, directory, session id, launcher/profile), then resume or start that session in a new iTerm2 tab — a fresh session is primed with a task briefing so the agent self-manages via tasq. Configurable launchers and project directories make this a one-key action.
• Be legible to an AI — the MCP server exposes every capability as a tool, and labels carry human-written descriptions so an assistant acts on intent, not guesswork.

Nothing leaves your machine: it's a single local SQLite file (WAL + FTS5), and the CLI, TUI, and MCP server are thin adapters over one shared core.

Install / run

uv sync                       # install dependencies
uv run tasq --help               # the `tasq` (and short `tq`) command

The database lives at $XDG_DATA_HOME/tasq/tasks.db by default. Override with --db PATH or the TASQ_DB environment variable.

CLI tour

# Capture
tasq add "Write the spec" -p acme --priority 2 --size M --due 2026-07-25 \
    -l writing --desc "See [design](https://figma.com/f/abc) and https://github.com/acme/repo"

# Missing dates are guessed: start = next working day, due = a few business days later
tasq add "Follow up with infra"   # e.g. start 2026-07-31 · due 2026-08-07
tasq add "Someday idea" --no-guess-dates   # leave both dates unset

# See what's next
tasq agenda --days 5              # overdue + today + upcoming, with effort estimates
tasq today
tasq overdue

# Get a proposed day-by-day schedule — a suggestion, never written back to tasks
tasq plan                        # packs open tasks into 5h/day over 5 working days
tasq plan --days 10 --hours 6    # 10 working days at 6 focus-hours/day
tasq plan --weekends             # include Sat/Sun (excluded by default)
tasq plan -o html --browser      # write an HTML report and open it in the browser
tasq plan -o html --out plan.html  # …or just write it to a specific file
tasq plan -p Work -p IGM         # limit planning to certain projects
tasq plan -L personal            # keep private (labelled) tasks out of the plan

# Interactive board: scroll the task list and quick-edit with the keyboard
tasq ui                          # 1-5 = priority · shift+←/→ = size · s/b/d = start/block/done
                                 # n = new task · t = set start date · o = open refs in browser
                                 # / = fuzzy find · p = cycle project filter · v = read-only plan view
                                 # a = start in an AI agent · x = delete · r = reload · R = resume in iTerm
                                 # enter = edit (shows clickable refs + AI session, has Delete)
                                 # ⟳ before a title = a linked AI session (resumable)

# Open a task's reference URLs (PRs, JIRAs, …) in the browser
tasq open 2                      # opens every URL extracted from task #2's description
tasq refs open 5                 # …or open a single extracted reference by its ref-id

# Link a task to the AI session you're working in, so it can be resumed later
tasq link 2 -a claude-code -d . -s <session-id> -c claude-work
                                 # -c is the command/alias you launched with (selects a profile)
tasq unlink 2                    # drop the session link

# Start a task in an AI agent — new iTerm2 tab, primed with a task briefing (macOS)
tasq work 2                      # prompts for a project dir + launcher, opens a briefed session
tasq work 2 -D igm               # start in the 'igm' project dir (its default launcher)
tasq work 2 -D igm -l claude-work    # …and pick one of that dir's allowed launchers
tasq work 2 --resume             # resume a session instead of a new briefed one
tasq work 2 -D igm --print       # print the launch command instead of opening iTerm

# Resume a linked session — opens a new iTerm2 tab, cds in, and runs the agent (macOS)
tasq resume 2                    # e.g. `cd <dir> && claude-work --resume <session-id>`
tasq resume 2 --print            # just print the command (no iTerm), for other terminals

# Break a task into sub-tasks (one level deep; they show in list/agenda too)
tasq add "Write migration" --parent 1 --priority 1
tasq subtasks 1                  # list a task's sub-tasks
tasq edit 3 --no-parent          # promote a sub-task back to top-level
tasq list --top-level            # hide sub-tasks from the flat list

# Move it through its lifecycle (comment optional, recorded either way)
tasq start 1 -m "picking this up"
tasq block 1 -m "waiting on backend"
tasq done  1
tasq history 1

# Find things (fuzzy — typos are fine)
tasq search "lgin bug"
tasq refs github                 # search URLs pulled out of descriptions
tasq refs open 2                 # open a matched URL

# Projects & labels (labels carry AI-facing descriptions)
tasq project add acme -l globex-corp
tasq label describe deep-work --desc "Requires 2h+ focus; schedule in the morning"
tasq label list

# Machine-readable output for any query command
tasq list --status waiting,blocked --json

Configuration

Planning and effort estimates are tunable via an optional TOML file at $XDG_CONFIG_HOME/tasq/config.toml (override with TASQ_CONFIG). Everything has a default, so the file is optional. TASQ_DAILY_HOURS overrides the daily budget for a single run, and tasq plan --hours N overrides it per-invocation.

[planning]
daily_hours = 5          # focus hours/day for `plan`; the rest is meetings/overhead
include_weekends = false # plan Mon–Fri only (override per-run with --weekends)
projects = []            # only plan these projects (empty = all); overridable with -p
labels = []              # only plan tasks carrying one of these labels
exclude_labels = ["personal"]  # keep private work out of the plan (override with -L)

[effort]
unsized_hours = 2        # assumed effort for a task with no size

[effort.size_hours]      # hours per t-shirt size (drives estimates and `plan`)
XS = 0.5
S = 1
M = 2
L = 4
XL = 8

[add]
guess_dates = true       # fill missing start/due when adding (override with --no-guess-dates)
due_business_days = 5    # due lands this many working days after the start date

[agents.launchers]       # commands/aliases for `tasq work` (each alias can be a profile)
claude = "claude-code"
claude-work = "claude-code"
copilot = "github-copilot-cli"

# Big-project directories agents can be started in (one table per project).
# `launchers` (defaults to all) restricts what's allowed there; `default` (defaults
# to the first) is preselected. `name` defaults to the path's basename.
[[agents.project_dirs]]
name = "igm"
path = "/Users/me/IGT/Azure/repos/igm"
launchers = ["copilot", "claude-work"]
default = "copilot"

# Customise the briefing that primes a fresh `tasq work` session. Placeholders
# $id, $title, $description are filled in (use ${id} next to letters). Optional —
# omit to use the built-in briefing.
[agents]
prompt_template = """
Work on tasq task #$id: $title.
$description

Link this session to task #$id in tasq, mark it in_progress, ask me for context,
and record any relevant PR / JIRA / repo URLs as you go.
"""

MCP server

Run the server over stdio:

tasq serve

Register it with an MCP client (e.g. Claude Desktop):

{
  "mcpServers": {
    "tasq": { "command": "uvx", "args": ["tasq", "serve"] }
  }
}

The examples below use uvx tasq serve, which works once the package is published. To run from a local checkout instead, use uv with --directory, e.g. "command": "uv", "args": ["run", "--directory", "/path/to/tasq", "tasq", "serve"]. Point at a specific database with the TASQ_DB env var if you don't want the default.

Claude Code

Add it from the terminal (project-scoped):

claude mcp add tasq -- uvx tasq serve

…or commit a .mcp.json at the repository root so the whole team gets it:

{
  "mcpServers": {
    "tasq": {
      "command": "uvx",
      "args": ["tasq", "serve"],
      "env": { "TASQ_DB": "${HOME}/.local/share/tasq/tasks.db" }
    }
  }
}

GitHub Copilot (VS Code)

Copilot's agent mode reads MCP servers from .vscode/mcp.json (note the top-level servers key and the type field):

{
  "servers": {
    "tasq": {
      "type": "stdio",
      "command": "uvx",
      "args": ["tasq", "serve"],
      "env": { "TASQ_DB": "${env:HOME}/.local/share/tasq/tasks.db" }
    }
  }
}

Then open the Copilot Chat Agent view and enable the tasq tools. (User-level config lives under "mcp": { "servers": { … } } in VS Code settings.json.)

It exposes tools (add_task, edit_task, get_task, list_tasks, search_tasks, search_references, transition_task, link_session, unlink_session, agenda, plan, project/label management) and resources (task://{id}, agenda://today, agenda://upcoming, labels://). Labels are surfaced with their descriptions, so an assistant knows what each means and when to apply it. The agent has full read/write access.

Linking a session: link_session(task_id, agent, directory, session_id, launcher) records which AI CLI worked on a task, where, under which session id, and with which command/alias (so a resume can pick the right profile). Ask the agent to "link this session to task #N" and it stores the details for later resumption.

Architecture

The CLI and MCP server are thin adapters over a shared core:

tasq.cli  ─┐
           ├─▶ tasq.services.Core ─▶ tasq.repository ─▶ SQLite
tasq.mcp  ─┘        (use cases)         (typed rows)

• models.py — enums + frozen, fully-typed dataclasses (the domain objects).
• repository.py — the only place that touches sqlite3 rows.
• services.py — use cases, transactions, and domain rules.
• references.py / search.py — URL extraction and fuzzy (FTS5 + rapidfuzz) search.
• serialize.py — one shared dict shape for CLI --json and MCP output.

Development

uv run pytest        # tests
uv run mypy          # strict type checking
uv run ruff check .  # lint
uv run ruff format . # format