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

# 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

[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.
"""

tasq serve

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

claude mcp add tasq -- uvx tasq serve

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

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

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

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