uv sync
uv run tasq --help            # or symlink the ./tasq wrapper onto your PATH

uv run tasq demo --ui         # seeds a demo.db and opens `tasq ui`
# …or explore piece by piece:
tasq demo                     # prints the exact commands to try (agenda, plan, …)

tasq add "Write the launch post" -p blog --priority 2 --due 2026-08-20
tasq ui                       # your board (1-5 = priority · n = new · ! = flag · a = agent)

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 · ! = flag for attention · p = project filter · v = plan view
                                 # a = start in an AI agent · x = delete
                                 # L = references view (u = unique · / = search · b = open as HTML)
                                 # r = reload · R = resume in iTerm
                                 # enter = edit (shows clickable refs + AI session, has Delete)
                                 # ⟳ = linked AI session (resumable) · ⚠ = needs attention (rings a bell)
                                 # auto-refreshes every 5s (configurable), so agent/CLI changes just appear

# 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

# Flag a task as awaiting your attention (an AI agent can do this via MCP)
tasq flag 3 -m "which auth provider — okta or auth0?"   # stands out + rings a bell in the UI
tasq list --attention            # everything currently flagged
tasq unflag 3                    # clear it once you've answered

# 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                        # every extracted URL (PRs, JIRAs), newest first
tasq refs --unique               # collapse duplicate URLs → one row per link + task count
tasq refs -o html --browser      # write an HTML report of the references and open it
tasq refs github                 # …or fuzzy-search them
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

# Pull work in from external sources (PRs to review, JIRAs, emails), deduplicated
tasq fetch reviews --org acme        # PRs awaiting your review (via `gh`) → tasks, deduped
tasq fetch reviews --user octocat --print   # …or just print the ingest JSON
your-fetcher | tasq ingest --source jira     # any fetcher: upsert JSON by (source, external_id)
tasq list --source github-reviews            # what's been synced
# re-running never duplicates; see docs/ingestion.md for the item schema + example fetchers

# 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

[ui]
refresh_seconds = 5      # how often `tasq ui` polls for changes (0 disables auto-refresh)

[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