What tasqx is

tasqx is the organiser for your AI: a backlog, a memory and a brief for your coding agent, and a fast, terminal-first task manager for you. It is a headless Rust core engine that exposes one stable, versioned JSON API — and every surface you touch (the CLI, the MCP server, the HTML report, this guide) is a client of that one contract.

The five ideas that shape everything else

How the pieces fit

The core is a plain Rust library. The CLI links it and calls functions in-process — no IPC on the hot path. The JSON API is a thin envelope over that same dispatch layer, so "call a function" and "send a JSON command" run identical code. There is exactly one dispatch table.

Every mutation is logged, in the same transaction

Adding, modifying, completing — each writes its row to an append-only events table inside the same SQLite transaction as the change itself. The log cannot drift from the data, because there is no window in which one exists without the other. That is what makes charts, reminder dedupe, and sync possible without a migration.

Where your data lives

Settings

tasqx config list shows every setting with the layer that supplied it. Resolution order is the CLI flag, then the TASQX_* environment variable, then config.toml, then the built-in default.

tasqx config edit opens the same settings on a full-screen editor: up and down move, enter toggles a switch or opens a theme picker, escape leaves. Moving through the theme list repaints the screen in that theme before anything is written, which is the one thing editing config.toml by hand cannot do. default_project is shown there but not editable — it lives in the store and is set with tasqx use. Piped or redirected, config edit refuses and exits 2 instead of writing escape codes into your pipe; scripts should use config set. A Sync section sits below the settings: c connects a tasqx-remote-* connector found on PATH through a form (the connector's own fields, then the sync passphrase, twice), s runs tasqx sync, and d disconnects after confirming — the remote itself is untouched either way.

Install and quickstart

tasqx is a single static binary with no runtime and no dynamic linking. Install it with a package manager, an installer script, or build it from source.

With a package manager

Updates then come from brew upgrade tasqx / scoop update tasqx, and brew switches Tab completion on by itself. macOS and x86-64 Linux, with Homebrew (there is no prebuilt ARM Linux binary yet, so ARM Linux builds from source):

brew install dimitritholen/tasqx/tasqx

Windows, with Scoop:

scoop bucket add tasqx https://github.com/dimitritholen/scoop-tasqx
scoop install tasqx

With the installer script

macOS and x86-64 Linux:

curl -fsSL https://raw.githubusercontent.com/dimitritholen/tasqx/main/install.sh | sh

Windows (the first statement makes older PowerShell able to download at all):

[Net.ServicePointManager]::SecurityProtocol=[Net.SecurityProtocolType]::Tls12; irm https://raw.githubusercontent.com/dimitritholen/tasqx/main/install.ps1 | iex

Prebuilt archives for Linux, macOS and Windows are also on the project's GitHub Releases page.

Or build from source

git clone https://github.com/dimitritholen/tasqx.git
cd tasqx
cargo install --path crates/tasqx-cli --force

Requires Rust 1.95 or newer. On Windows the MSVC toolchain is discovered automatically — you do not need it on your PATH.

That installs tasqx alone. To sync between machines, also build the connector you use:

# a synced folder
cargo install --path crates/tasqx-remote-dir --force
# or an R2 bucket
cargo install --path crates/tasqx-remote-r2 --force

Sixty seconds with tasqx

Create a project, capture some work, and look at it.

tasqx init work.tasqx --desc "The tasqx project itself"

work.tasqx
created   now your default project

Now capture a task. Everything after add is the title — except the bits tasqx recognises as structure. That is the inline sugar: +tag, project:, !priority, due:, est:, repeat:, remind:. Whatever is left over is the title.

tasqx add "Ship the v1 JSON API freeze +api +release project:work.tasqx !high due:friday est:4h"

▌ #1  Ship the v1 JSON API freeze
▌ added   H ▄▄▄▄ 15.7   work.tasqx   due Fri   +api +release   est 4h

The sugar was consumed; only the real title remains. Tags and a due date, no project — init made work.tasqx the default, so it is filled in for you:

tasqx add "Write the user guide +docs due:friday"

▌ #2  Write the user guide
▌ added   - ▄▄▄▁ 9.7   work.tasqx   due Fri   +docs

Every field is also available as a flag, which is what you want when a value contains spaces or comes from a variable:

tasqx add "Renew the TLS cert" project:work.tasqx +ops --due -1d

▌ #3  Renew the TLS cert
▌ added   - ▄▄▄▄ 12.0   work.tasqx   due yesterday   +ops

Look at the working set

tasqx list shows the @working filter: everything pending or active that is not blocked, hottest first. A bare tasqx prints the same table wherever it is not talking to a person — piped, redirected, or under --json — and opens the dashboard when it is.

tasqx list

@working   3 tasks · 1 overdue

  ID          URG  TASK                         PROJECT     DUE        TAGS
   1  H ▄▄▄▄ 15.7  Ship the v1 JSON API freeze  work.tasqx  Fri        +api +release
   3  - ▄▄▄▄ 12.0  Renew the TLS cert           work.tasqx  yesterday  +ops
   2  - ▄▄▄▁  9.7  Write the user guide         work.tasqx  Fri        +docs

The line above the table says which filter answered and what the answer holds beyond its own size — how much of it is late, due before the day is out, running, or blocked. In the DUE cells a deadline inside the coming week is named by its weekday, one further out by its date, and today and tomorrow carry a clock when the store holds one.

That URG column is urgency — a computed score, not something you set. The letter in front of it is the priority you did set. tasqx next is the "what now" button: the single hottest unblocked task.

tasqx next

next    #1  Ship the v1 JSON API freeze
        H ▄▄▄▄ 15.7   work.tasqx   due Fri   +api +release
        tasqx start 1  ·  tasqx why 1

And tasqx why shows its arithmetic, so the ranking is never a mystery:

tasqx why 1

#1  Ship the v1 JSON API freeze

  priority   H                 6.0
  deadline   due Fri           9.7
  age        created today     0.0
  urgency                     15.7

Work it, finish it

tasqx start 1
tasqx stop 1
tasqx done 1

▌ #1  Ship the v1 JSON API freeze
▶ started   H ▄▄▄▄ 15.7   work.tasqx   due Fri   +api +release   est 4h
▌ #1  Ship the v1 JSON API freeze
▌ stopped   H ▄▄▄▄ 15.7   work.tasqx   due Fri   +api +release   est 4h
▌ #1  Ship the v1 JSON API freeze
▌ done today   work.tasqx   due Fri   +api +release   est 4h

Where to go next

The filter grammar

One small grammar, used everywhere a query is taken: list, report, export, watch, task.list, and the MCP tools. Learn it once.

The grammar

filter     := or_expr
or_expr    := and_expr ( "or" and_expr )*
and_expr   := term ( "and"? term )*        # juxtaposition = implicit AND
term       := "(" or_expr ")" | predicate
predicate  := "+" VALUE                    # require tag; VALUE not empty, lowercased (D172)
            | "-" VALUE                    # exclude tag; VALUE not empty, not starting with a dash, lowercased
            | "@working"                   # status in {pending,active} AND not blocked; a chooser (next, pick, a list with an actor) also skips other holders' live claims (D236)
            | "@blocked" | "+blocked" | "status:blocked"   # the blocked flag
            | "@claimed"                   # under a live claim, anyone's (D236)
            | "project:" VALUE
            | "proj:" VALUE                  # alias of project: (#229 item 5)
            | "status:" VALUE                # `any` or `all` = every status, done and cancelled too (D210)
            | "priority:" VALUE
            | "title:" VALUE                 # substring of the title, case-insensitive (D210)
            | WORD | QUOTED                    # a bare word or quoted phrase is "title:" of itself
            | "due.before:" DATE
            | "due.after:"  DATE
            | "completed.before:" DATE       # when the task was finished
            | "completed.after:"  DATE

VALUE      := CHUNK*                       # chunks abut; nothing may come between them
CHUNK      := WORD | QUOTED
WORD       := a run of characters, none of them whitespace, a quote or a paren
QUOTED     := a run between double quotes; backslash escapes a quote or a backslash
DATE       := any date `due:` accepts      # tomorrow, friday, 2026-07-25,
                                           # "in 3 days", eom, 2026-07-20T17:00

Predicates

Values with spaces

A space separates predicates, so a project whose name contains one must be double-quoted: project:"Home Renovation". A tag never contains one — tags are stored lowercased and a spaced tag is refused, so +API matches api.

• Inside quotes, spaces and parentheses are ordinary characters and and/or are ordinary words, so a project named a (b) does not break the grouping.
• Write \" for a literal quote and \\ for a literal backslash.
• Quoting changes where a predicate ends, not what it means: "project:x" is still a project match.
• The quotes must reach tasqx, so protect them from your shell: 'project:"Home Renovation"'.

tasqx add and tasqx modify split their inline sugar with the same scanner, but the two sides differ on purpose. The write side also honours the argument boundary your shell drew, so tasqx add "paint" project:Home Renovation files the task. The read side refuses the same words: project:Home Renovation could equally be a project match plus a stray token, and guessing would answer with the wrong rows at exit 0. A refused read costs a retype; a wrong one cannot be noticed. The quoted spelling works on both sides, so learn that one. A name containing a quote needs the escaped form on both sides: project:"My \"Big\" Project".

tasqx list project:"Home Renovation" +paint

Combining

A space is an implicit and. or and parentheses are explicit, and both keywords are case-insensitive.

tasqx list "(+api or +ops) and status:pending"

(+api or +ops) and status:pending   2 tasks · 1 overdue

  ID          URG  TASK                         PROJECT     DUE        TAGS
   1  H ▄▄▄▄ 15.7  Ship the v1 JSON API freeze  work.tasqx  Fri        +api +release
   3  - ▄▄▄▄ 12.0  Renew the TLS cert           work.tasqx  yesterday  +ops

Two behaviours worth knowing

Dates compare as instants, not strings. due.before: and due.after: parse both sides to timestamps and compare those. 2026-07-17T00:00:00Z and 2026-07-17T02:00:00+02:00 are the same instant, and the filter knows it — a lexicographic comparison would not. A relative bound resolves once, when the filter is parsed, so every row in one query is compared against the same tomorrow. A date the parser cannot read is refused by name rather than quietly matching nothing.

Where the grammar stops

On purpose, and permanently: no arithmetic, no computed expressions, no subqueries. A filter language that grows those becomes a query language nobody can predict. For anything beyond this, export to JSON and use a real tool — jq, a script, whatever you like. The store is yours.

Getting Started

tasqx is the organiser for your AI: a backlog, a memory and a brief for your coding agent, and a task manager that lives in your terminal. Your tasks are stored in a single SQLite file on your own disk — no account, no cloud, works offline.

Install

With a package manager — updates then come from brew upgrade tasqx / scoop update tasqx, and brew switches Tab completion on by itself.

macOS and Linux, with Homebrew:

brew install dimitritholen/tasqx/tasqx

Windows, with Scoop:

scoop bucket add tasqx https://github.com/dimitritholen/scoop-tasqx
scoop install tasqx

Or without one — Linux and macOS:

curl -fsSL https://raw.githubusercontent.com/dimitritholen/tasqx/main/install.sh | sh

Windows (the first statement makes older PowerShell able to download at all):

[Net.ServicePointManager]::SecurityProtocol=[Net.SecurityProtocolType]::Tls12; irm https://raw.githubusercontent.com/dimitritholen/tasqx/main/install.ps1 | iex

Prebuilt binaries for Linux, macOS and Windows are also on the Releases page (https://github.com/dimitritholen/tasqx/releases), and you can build from source with cargo install --path crates/tasqx-cli.

Each release archive, the Homebrew formula and the Scoop manifest also carry tasqx-remote-dir and tasqx-remote-r2, the connectors Syncing Between Machines uses. brew install and scoop install put both on PATH for you; the curl/irm installers above only place tasqx itself, so a connector from the archive needs copying onto PATH by hand, or building it from source: cargo install --path crates/tasqx-remote-dir and cargo install --path crates/tasqx-remote-r2.

Install fine print

Both installer scripts pick the newest release, resolve your target triple, verify the archive against its published checksum, and put files only in the install directory: ~/.local/bin, or %LOCALAPPDATA%\Programs\tasqx\bin on Windows. The Windows installer also adds that one directory to your user PATH, a setting outside it, and -Uninstall takes it back out. Neither touches a shell startup file unless you ask.

A pipe passes no arguments, so flags need the longer form:

curl -fsSL https://raw.githubusercontent.com/dimitritholen/tasqx/main/install.sh | sh -s -- --dry-run

&([scriptblock]::Create((irm https://raw.githubusercontent.com/dimitritholen/tasqx/main/install.ps1))) -DryRun

The rest are --uninstall/-Uninstall (which also takes out the completion block an older tasqx added to your shell's startup file) and --help/-Help; every switch also has an environment variable (TASQX_UNINSTALL, TASQX_DRY_RUN, …), TASQX_VERSION pins a tag, and TASQX_INSTALL moves the destination.

Honesty about what that buys you:

• The checksum is integrity, not provenance. It catches a truncated transfer or a corrupt CDN object; it is served from the same host as the archive, so it proves nothing about who built it. Nothing here is signed.
• The binaries are unsigned. On macOS the curl route goes around Gatekeeper rather than passing it — that is why the install just works.
• The Linux build links your system glibc (SQLite is bundled; there is no other runtime). The floor is whatever GitHub's current ubuntu-latest provides. There is no musl build — an older distro builds from source.

All of it applies to the package-manager routes too: the Homebrew formula and the Scoop manifest are generated per release from the same published checksums and point at the same unsigned archives.

The whole loop is four commands

• tasqx init work: create a project — just a name, no folder
• tasqx add Buy milk: capture a task (lands in the default project)
• tasqx next: the one thing to do now
• tasqx done 1: complete it

tasqx init work
tasqx add Buy milk
tasqx next
tasqx done 1

That's a working task manager. Everything else on this wiki is optional depth.

A few things worth knowing on day one:

• A project is just a name. init creates no folder and touches nothing on disk except the task store. The first project you create becomes the default, so bare tasqx add knows where to file things.
• Every task gets a short id (#1, #42). That id is how you refer to it in every other command: tasqx done 42, tasqx show 42.
• Capture takes shortcuts inline. tasqx add Ship it due:friday +api !high sets a due date, a tag and a priority in one line. See Adding and Editing Tasks.
• A bare tasqx in a terminal opens the dashboard — a full-screen overview. In a script or pipe it prints the task table instead. See Dashboard and Live View.

Getting help

tasqx ships its own documentation — no internet needed.

tasqx manual

Alias: man

The complete guide, in your terminal. tasqx manual shows the table of contents; tasqx manual <command> or tasqx manual <topic> opens one section. projects and daemon are both a command and a topic, and open both pages.

tasqx docs

The same guide as one self-contained HTML page, opened in your browser. No external requests, nothing tracked — it's generated from the binary itself.

tasqx about

Who made tasqx, where to find it, and what build you are on. Five labelled rows: the author, his LinkedIn, the project on GitHub, the build this binary was made from, and the store it would open. It opens no store and no network — the store line is the path a command would use, resolved without creating anything.

tasqx about

The build line is the same string tasqx --version prints: the crate version plus the commit it was built from, or unknown for a build from a source tarball, which has no git to ask. Quote it when you report a bug.

tasqx about --notices prints the third-party notices: the attribution and licence texts of the embedding model built into the binary for memory search.

Per-command help

Every command answers -h with usage, flags and copy-pasteable examples:

tasqx add -h

Where your data lives

The store is a SQLite file at $TASQX_DB if you set it, otherwise in your platform's data directory. tasqx config store tells you exactly which file a command would write to. Back it up any time with tasqx export.

Projects

A project in tasqx is just a name that groups tasks — work, home, kitchen-remodel. No folder is created, nothing appears on your disk. A task belongs to at most one project: tasqx add with no default project files it under none, and tasqx modify --clear project takes it out of one.

tasqx init

Create a project.

tasqx init work
tasqx init home --desc "Everything around the house"

• If the store has no default project yet, the new one claims it. So on a fresh install, tasqx init work is all the setup you need.
• Creating a second project does not move the default. Use tasqx use for that.

tasqx use

Choose the default project — the one a bare tasqx add files tasks into.

After this, tasqx add ... lands in home:

tasqx use home

• The project must already exist and not be archived.
• tasqx projects marks the current default with a *.

tasqx projects

List your projects.

--all is the only way to see archived projects — without it the table shows only the projects that add and use will accept.

tasqx archive

Retire a project. Think shelf, not shredder: the tasks keep their history and stay in the store, the project just leaves the rotation.

tasqx archive kitchen-remodel

Things to know before you archive:

• Once archived, no command will accept the project's name anymore — you can't use it, and you can't add or modify a task into it.
• If you archive the project that is your default, the default is cleared: a bare tasqx add then has no home until you run tasqx use again. The command tells you when this happened.
• Tasks in an archived project are left out of tasqx next and of the @working set — the dashboard's working list included — because those answer "what should I do now". Name the project and they come back: tasqx next project:kitchen-remodel. list, report and agenda still show them. The rule applies to any filter that mentions @working, so @working or +x also hides a pending +x task in an archived project; leave @working out of the filter to see it.
• tasqx unarchive is the way back. tasqx undo does not reverse an archive, because archiving the default project also cleared the default, which the log does not restore.

tasqx unarchive

Put an archived project back into rotation.

tasqx unarchive kitchen-remodel

• The project's tasks never left, so nothing else is restored; the line says how many open tasks are back in next.
• A project that is not archived exits 5, an unknown name exits 4.
• It does not point the default project back at it. tasqx use does that.

Adding and Editing Tasks

Capture fast, refine later. add and modify share the same tricks: inline shortcuts in the title, natural-language dates, and flags for everything if you prefer being explicit.

tasqx add

Aliases: a, new

Create a task. The simplest form is just a title:

tasqx add Buy milk

The title can carry inline shortcuts ("sugar"), so one line captures everything:

tasqx add Ship the release due:friday +api !high est:4h

Every shortcut also exists as a flag (--due friday, --tag api, --priority H, …) — same result, pick whichever reads better in your scripts.

More on dates, recurrence and reminders: Dates, Reminders and Recurrence.

A task without a project lands in your default project (tasqx use changes which one that is).

When an open task in the same project already reads like the new one, add still adds it and prints a note: line naming that task, up to three of them. --json carries them as similar, an empty list when there are none.

tasqx modify

Aliases: mod, m, edit

Change an existing task. Takes the same inline sugar and dates as add:

Setting and clearing are different moves. Setting is due:friday; removing is --clear due. There is no magic empty value:

tasqx modify 42 --clear due --clear remind

--clear works for: project, priority, due, scheduled, wait, remind, recurrence, estimate, tracked, budget_tokens. Tags are the exception — a tag comes off by name, with tasqx untag.

A task's status is not a field you set: it moves through start, stop, done, cancel and reopen — see Working on Tasks.

What a write prints

Every write answers with the same card: the task it named, then the outcome and what changed, then the rest of that row. Bold is the write's own mark — it says THIS is what changed, and nothing else wears it, because bold is the one emphasis that survives NO_COLOR.

tasqx start 49

▌ #49  Fix token refresh race on Android
▶ started   H ▄▄▄▄ 17.0   mobile   due tomorrow 17:00 UTC   +bug   est 4h
  #48  stopped · Ship the v2 pricing page

The rail at the left carries the state: ▶ while the task runs, ⊘ while it is blocked, ▌ otherwise. Another task the write moved gets a line of its own under the card:

tasqx done 50

▌ #50  Rate-limit the /search endpoint
▌ done today   api   due Sat   +perf   est 3h
  #51  unblocked · Write the migration guide for SDK 3.0
note: no token counts were self-reported — tasqx done --help names the flags

Through a pipe the same words print, unfitted: the rail spells itself * for running and B for blocked, and the gauge and the ▌ go. --json is unchanged.

tasqx check

Acceptance criteria: the things that have to be true for a task to count as done.

tasqx check add 42 the notes name every breaking change
tasqx check set 42 <id> passed --evidence "cargo test: 0 failed"
tasqx check rm 42 <id>

tasqx show numbers each check (2 [ ] the notes name every breaking change). <id> is that position, counting from 1 — tasqx check set 42 2 failed marks the second one — or the check's full id. A mistyped id is refused with the task's real checks listed.

check add, check set and check rm answer with the one check they touched and how many have passed, not the whole task; tasqx show has the rest. A criterion may begin with -- (tasqx check add 42 --since 2026-01 is honoured): after the task, a dash-led word that is not one of check add's own flags (--json, --no-daemon, …) is part of the criterion.

tasqx never runs a check. The criterion is a claim and the evidence is a citation — both are stored exactly as you typed them and neither is interpreted. If you want something run, a hook you installed runs it and calls tasqx check set with the result, like any other client would.

Criteria in an annotation look the same and are not: an annotation is prose, so nothing can ask at completion time whether it was met. A check has a state.

Completing a task with a criterion still open or marked failed is not refused — tasqx is a file on your disk, not a supervisor, and a refusal is something a script routes around. tasqx done says so in one line, naming how many failed and how many are still open, and it is counted: a completion is proven only when every check passed, and tasqx report --outcomes has an UNPROVEN column for the rest, adding N failed when any had a failed check. That column is where the pattern shows up.

failed is a normal outcome and worth recording. Remove a check only when the criterion was the wrong thing to ask — deleting one the work failed hides the finding.

Token budgets

--budget-tokens sets a size gauge on a task:

tasqx add Port the payment adapter --budget-tokens 200000

It counts fresh tokens — input, output and cache creation — and ignores cache reads, because a budget dominated by re-reads measures how often an agent re-read its own context rather than how big the work was. tasqx show prints the pair once a budget is set.

It stops nothing. tasqx is a file on your disk that an agent talks to between turns; it never sees the turn and could not interrupt one. An overrun is a signal, and usually one signal in particular: the task was too big to hand over whole. tasqx report --outcomes counts overruns so you can see which kinds of work keep being cut too large.

For scripts that must not clobber a concurrent edit: --expected-rev makes the modify fail (exit 5) if the task changed since you last read it.

tasqx tag

Attach one or more tags.

Re-adding a tag the task already has is fine — the answer is simply the resulting tag set.

Tags are stored lowercase, so +API and +api are the same tag, and a tag cannot contain a space — tasqx tag 42 "needs paint" is refused; write needs-paint. A filter's +API matches it too. A store written by an older tasqx is folded into this form the first time it is opened (spaces become hyphens, duplicates merge), and each task it touched gets a tag.normalize event naming every from → to it applied — event.list with that task's ref shows them (see tasqx api).

tasqx untag

Remove one or more tags.

tasqx untag 42 api

All or nothing: if any named tag isn't on the task, none are removed and the command tells you which tags the task does have. A typo never quietly succeeds.

tasqx annotate

Attach a timestamped note to a task. The text is stored exactly as you typed it — multi-line, markdown, links, all preserved.

tasqx annotate 42 Called the plumber, waiting on a quote

Annotations show up in tasqx show, and they're searchable: the memory system indexes them alongside your knowledge documents, so "what did we decide about the plumber" is one tasqx memory search away.

For a long or multi-line note, give the text on stdin. - reads all of stdin, as does a bare annotate when stdin is a pipe:

tasqx annotate 42 - < decision.md

On a terminal, a bare tasqx annotate 42 opens $VISUAL or $EDITOR (else vi) on a temporary file. Saving an empty or unchanged file stores nothing, and so does empty stdin. A note that is only - can't be written as an argument.

tasqx show numbers the notes, oldest first, with a dim [n] in front of each. That number, a unique prefix of at least eight characters of the note's id, or the full id names a note anywhere a note is named. Notes written within about a minute share their first eight characters, so a prefix is often ambiguous (exit 5, listing the candidates); the number is the short way.

To correct a note instead of adding another, name it with --edit:

tasqx annotate 42 --edit 2 Plumber quoted 400, booked for Friday

The text is replaced in place: the note keeps its id, its timestamp and its place in the history, so the first note is still the box card's Description, and search finds the new text rather than the old. tasqx undo puts the old text back. --edit takes the same stdin and editor forms; the editor opens on the note's current text.

Put a note on the wrong task? Move it instead of retyping it:

tasqx annotate 42 --move 2 --to 57

The note keeps its id, text and timestamp and lands on #57 in its place by age; search finds it there. tasqx undo puts it back on #42.

tasqx unannotate

Permanently scrub one annotation's text:

tasqx unannotate 42 2

This is a hard delete, not a hide: the text is overwritten in the store, not merely removed from what tasqx shows you — use it to take back a secret, a customer name, or a wrong root cause pasted into a note by mistake. What stays behind is a tombstone (the id and when it was removed), for audit, with no text in it. The tombstone is not hidden away: tasqx show and task.get both list it, and the box card's Notes row counts it.

Name the note by the [n] position tasqx show prints, a unique id prefix of eight or more characters, or its full id (annotations[].id in --json). tasqx undo does not cover this: by the time the removal is recorded, there is nothing left in the log to restore. An unknown id, or one already removed, exits 4 rather than silently doing nothing.

Finding Tasks

Five commands answer "what's on my plate?", each from a different angle — plus a small filter language they all share.

tasqx list

Aliases: ls, l

The task table. With no filter it shows your working set: open tasks you can actually act on right now (blocked and hidden-until-later tasks are left out).

A list shows at most 100 rows. When more match, the head says so (100 of 192 tasks) and a last line gives the command for the rest: --offset 100 for the next page, --limit 192 for all of them (--limit tops out at 10,000). tasqx agenda reads every match, so it is never cut.

A bare tasqx in a pipe or script does the same thing; on an interactive terminal it opens the dashboard instead.

tasqx next

The "what now" button. Prints the single most urgent task that isn't blocked.

tasqx next

--card prints that task as the same 72-column box-drawn card tasqx show --card draws, meant for pasting into a document rather than reading at a terminal; --ascii draws its borders with + - |.

tasqx agenda

Aliases: ag, cal

What's coming up, ordered by time and grouped by day — the calendar view of your tasks.

• Each task appears on the earlier of its due date and its scheduled date — the first day it asks something of you — and the WHEN column says which of the two that was.
• Overdue tasks always show, no matter the window.
• Tasks it can't place (no date, or past the horizon) are counted under the table rather than silently dropped, with the exact command that would reach them: the --days that reaches the furthest one, or tasqx list when it is further out than --days goes.
• Days are UTC days: a bare date is midnight UTC, so a day groups the same way the store holds it.

tasqx show

Alias: get

One task, in full: description, tags, annotations, dependencies, whether it's blocked, and its revision number.

tasqx show 42

--card prints the task as a fixed 72-column box-drawn card instead of the usual screen — meant for pasting into a document, a chat reply or a pull request rather than reading at a terminal. --ascii draws its borders with + - | for destinations that mangle box-drawing characters.

tasqx show 42 --card
tasqx show 42 --card --ascii

When an annotation was removed with tasqx unannotate, show prints one line per removed annotation under the history — a tombstone naming its id and when it was removed — and the box card's Notes row appends ", N removed".

tasqx why

Every open task gets an urgency score, and the ordering of every list comes from it. why shows the arithmetic instead of asking you to trust it:

tasqx why 51

#51  Write the migration guide for SDK 3.0

  priority   M           3.9
  deadline   due Mon     8.0
  age        30 days     0.3
  urgency               12.2
  blocked by #50 Rate-limit the /search endpoint — `next` skips this task

Each row names the input in the words the rest of the terminal uses — the priority letter, how the deadline reads on a list, how old the task is — and the last row is the score every list sorts by.

Urgency is recomputed on every read, so the deadline row — and the total it feeds — climb as the due date approaches. The scores in any capture, including this one, are an illustration; the rows are the contract.

If tasqx ranks something surprisingly high or low, this is where the answer is.

--card prints the box card first, with this same arithmetic underneath it instead of the plain text header above; --ascii draws the card's borders with + - |.

The filter language

Everything that lists tasks (list, agenda, pick, watch, report, export) takes the same filter expressions:

A bare word is a title search, so tasqx list weekly review finds "Weekly planning review". A word that looks like a token but is not one — remind:x, due.before: with no value — is still refused. % and _ in a word are plain characters.

Combine with and, or and parentheses:

tasqx list "project:work and (+api or +ui)"

Values with spaces need quotes that actually reach tasqx — so wrap the whole thing in single quotes (or backslash-escape it) to protect it from your shell. Inside the quotes, parentheses and the and/or keywords are ordinary characters too, as in a shell:

tasqx list 'project:"Home Renovation"'

tasqx never guesses where a quoted value was supposed to end. If the shell eats your quotes, project:Home Renovation is the project Home plus the title word Renovation; a project that does not exist is refused by name, which is the signal to quote. +needs paint is the tag needs plus the word paint; when that matches nothing, list prints a hint: line naming +"needs paint". The same rule is what lets you pass a whole expression as one argument: tasqx list "+api or +web" is the expression.

report takes one axis, as its first word, and refuses report project priority; write title:priority to match that word in titles.

add and modify do not refuse an unquoted multi-word value: it is either not_found (no project named by the leading word) or, when a project is named exactly that leading word, the task is filed there and the remainder is welded onto the title. tasqx add "paint" project:Home Renovation becomes project Home, title "paint Renovation". Quote it on both sides and this cannot happen: tasqx add "paint" project:"Home Renovation".

Write \" for a literal quote and \\ for a literal backslash — a name holding a quote needs that form on both sides: tasqx add "paint" project:"My \"Big\" Project".

due is compared as an instant, not a calendar day.

Working on Tasks

The lifecycle: start, stop, done — with cancel, reopen, pick and undo around it. Nothing here destroys data; every change is recorded and reversible.

tasqx brief

Everything you need before starting a task, in one read.

tasqx brief 42
tasqx brief 42 --memory-limit 3

You get the task's own card, then two things tasqx show never carried:

• Depends on — each prerequisite with what it concluded: its newest annotation, printed under it. That is usually the single most useful thing to read before picking work up, and it used to cost one tasqx show per prerequisite.
• From memory — documents and past annotations relevant to this task, found under a query tasqx builds from the task's own title, tags and project. You do not supply search terms, which matters because a guessed term that finds nothing looks exactly like a store with nothing in it. Half the slots are held for docs, so an imported ruling still reaches the page when a project's own task notes share its words; annotations take the rest, and docs take the whole page when more of them matched than that.

Memory is scoped to the task's project and stays scoped when that finds nothing — it will not quietly search everything instead. When you want wider, tasqx memory search is the read for it.

tasqx show is still the right command when you only want the task.

--card works here too, and prints the same box-drawn card tasqx show --card prints, followed by the brief's own Depends on / Blocks / From memory sections.

tasqx start

Alias: s

Mark a task active and start its timer.

• tasqx start 42 --keep: keep other active tasks running too

tasqx start 42
tasqx start 42 --keep

By default starting one task stops any other active one ("single-active") — --keep opts out.

That stays true for you at a shell. It stops being true across sessions: if an AI agent holds a running timer, starting a task from another session is refused rather than silently stopping their clock, because stopping it would leave the rest of their work untracked and tell only you about it. --keep runs both deliberately.

The extra flags (--client, --session-id, --transcript-path) are for AI agents reporting who is doing the work; see AI Agents and Automation.

tasqx claim

Claim a task so other agents skip it. A claim is a lease: 30 minutes unless --lease names another length, at most 24 hours.

• tasqx claim 42 --holder builder-2: hold #42 for builder-2
• tasqx claim 42 --holder builder-2 --lease 2h: renew it for two hours

tasqx claim 42 --holder builder-2

While the lease is live, anyone else's claim, start, stop, done, cancel or modify to cancelled on the task exits 5 naming the holder and when the lease runs out (--force-claim goes ahead and the log names whose claim it overrode; done --force is only for open dependencies), and starting another task leaves it running instead of stopping it. tasqx next skips it for anyone but the holder, and so does tasqx pick. tasqx list still shows it, with its holder and expiry: a list is a view, and only list --holder <id> @working — an agent choosing its own work — leaves other holders' claims out. tasqx list @claimed lists every live claim, and tasqx show names the holder and the expiry.

Without --holder the shell holds the claim as user, and tasqx next from the same shell still shows it. next, list and pick take --holder to choose work as a named holder, and start, done and cancel take it to act on a task claimed under one (the timer itself stays the shell's):

tasqx start 42 --holder builder-2

An AI agent on the MCP server holds it as its connection unless it names a stable actor. Nothing sweeps an expired lease: once it runs out, anyone may claim the task, and the log records that as a takeover. Claim, renew, release and takeover each land in the event log with the holder.

tasqx release

Give a claim up. Only its holder can: a task with no claim, or someone else's, exits 5. done and cancel end a claim without it. --force-claim releases a claim someone else holds — one left by an agent that crashed or reconnected under a new id — and the log records it as forced. A claim whose lease has run out can be released by anyone, no --force-claim needed.

tasqx release 42 --holder builder-2

tasqx stop

Alias: st

Pause an active task. The tracked time is kept.

tasqx stop 42

While a timer runs, tracked already counts it: list, show, report and the card all include the open interval up to the moment you ask.

tasqx adjust

Correct a task's tracked time when the clock was wrong — a timer left running over lunch, or work that never reached it.

tasqx adjust 42 -2h25m --reason "idle gap"
tasqx adjust 42 +30m --reason "forgot to start"

• The reason is required and stays in the task's history with the correction.
• It works on done tasks too, so report --outcomes calibration can be fixed after the fact. A correction that would take the total below zero is refused.
• show prints the net of every correction beside the total: tracked 2h30m (adjusted -2h25m).
• tasqx undo takes the newest correction back.

tasqx done

Aliases: d, x, complete

Complete a task.

tasqx done 42

• If the task recurs, completing it spawns the next occurrence — the answer shows it.
• If other tasks were waiting on this one, they unblock now, and the answer names them. Finishing work tells you what it made possible.
• A task with dependencies still open is refused, naming them. tasqx done 42 --force completes it anyway; the override is recorded on the completion and tasqx report --outcomes counts it under FORCED. Cancelling a blocked task never needs the flag.
• Report what the work cost with --tool, --model and --input-tokens, --output-tokens, --cache-read-tokens, --cache-creation-tokens (or one unsplit --total-tokens). Any count records a measurement; --tool and --model alone still land on the completion.

tasqx done 42 --tool claude-code --model claude-opus-5 --input-tokens 4200 --output-tokens 900

tasqx cancel

Aliases: delete, del, rm

Cancel a task. This is as close to "delete" as tasqx gets, on purpose: the task keeps its history, stays in the event log, and comes back with reopen.

tasqx cancel 42

If other tasks were waiting on the cancelled one, they're released — a dead prerequisite shouldn't block live work.

tasqx reopen

Bring a done or cancelled task back to pending.

tasqx reopen 42

If open tasks depended on it, they become blocked again — the mirror image of what done unblocked. The answer names them.

tasqx git

Record what happened to a task's pull request, and let the task follow it.

tasqx git event opened --branch task/42-pricing --pr https://github.com/acme/web/pull/7
tasqx git event merged --branch task/42-pricing --pr https://github.com/acme/web/pull/7 --sha 4f9c2e1
tasqx git event closed --branch fix-typo --pr https://github.com/acme/web/pull/8 --task 43

A branch named task/<id>-<slug> names its task, whatever follows the id (task/42-pricing-rebased too); --task names it when the branch does not.

• opened starts a pending task. It stops no other timer.
• merged completes the task, with Merged <pr> (<sha>) as its delivery note, but only when every check passed (or it has none) and nothing blocks it. Otherwise the task stays open and a note names the checks that did not pass.
• closed adds a note and leaves the status alone.

tasqx show lists the branch, the PR and the merge commit under git. Reporting merged again after the checks are fixed completes the task. A PR starts its task once: reporting opened again after you stopped it does nothing, and a task a merge completed that you reopened stays open. An event whose outcome already holds changes nothing, and so does one a recorded merge settled (closed after merged); both say why. When someone holds a claim on the task, the event acts as that holder.

tasqx never asks GitHub, or any network. Something that watched the PR tells it: a script reading gh pr view --json, a CI step, a git hook.

tasqx triage

Work you or an agent finds mid-task can be filed as a proposal instead of going straight into the backlog: tasqx add … --triage (an agent passes status: "triage", or every MCP add lands there once mcp.add_status is triage). A proposal stays out of @working, next and the urgency ranking, and cannot be started or completed until it is accepted. --discovered-from <id> links it to the task it was found on.

tasqx triage

lists the inbox oldest first, with the tool that filed each proposal and the task it was found on. tasqx list status:triage is the same set as a table. Settle each one with a single command, below.

tasqx accept

tasqx accept 12

Makes the proposal pending — or backlog, while a future wait or scheduled still holds it. tasqx undo puts it back in triage.

tasqx decline

tasqx decline 12 --reason "out of scope for this release"

Cancels the proposal and keeps the reason as a note. tasqx undo puts it back in triage; the note stays.

tasqx duplicate

tasqx duplicate 12 --of 7

Cancels the proposal, moves its notes to the task it repeats, makes the tasks that waited on it wait on that one instead (unless that would close a loop) and links the two with duplicates. Undo does not take this one back; tasqx reopen brings the proposal back to triage, and the notes and dependents stay where they went.

The dashboard's header, the HTML report and the desktop app count what is waiting in triage.

tasqx pick

Aliases: p, fzf

A full-screen browser over your tasks, each row the row tasqx list prints.

The bar along the bottom names the keys that can do something where you are, so it is shorter on an empty list, on a card, and on a narrow terminal — the way out is named at every width.

s is the only key that writes. A filter can list work that is done or cancelled, and s on such a row is refused on the key bar's own row with the screen still open.

Captured on a terminal 120 columns wide, since this screen cannot be piped:

 pick   @working   14 tasks · 1 overdue · 1 due today · ▶ #48 running

       ID          URG  TASK                                           PROJECT  DUE             TAGS
 ▸     47  H ▄▄▄▄ 18.1  Renew the TLS certificate for api.example.dev  infra    2d ago          +ops
   ▶   48  H ▄▄▄▄ 17.8  Ship the v2 pricing page                       website  today 17:00     +launch
       49  H ▄▄▄▄ 17.0  Fix token refresh race on Android              mobile   tomorrow 17:00  +bug
       50  H ▄▄▄▄ 15.9  Rate-limit the /search endpoint                api      Sat             +perf
       58  L ▄▄▄▁  9.4  Book the dentist                               home     Tue
       52  M ▄▄▃▁  8.6  Dark mode for the settings screen              mobile   25 Sep          +ui
       56  M ▄▄▁▁  6.0  Accessibility pass on the signup flow          website  28 Sep          +a11y
       54  M ▄▂▁▁  4.3  Cut build time under five minutes              infra                    +ci
       53  M ▄▂▁▁  4.2  Move nightly backups to object storage         infra                    +ops
       55  M ▄▂▁▁  4.0  Add OpenAPI examples for every endpoint        api                      +docs
       57  L ▃▁▁▁  2.0  Replace the carousel on the home page          website                  +ui
       59  L ▃▁▁▁  2.0  Archive last year's analytics dashboards       website
       61  - ▁▁▁▁  0.4  Sketch ideas for the Q4 offsite                home
       60  - ▁▁▁▁  0.1  Investigate flaky checkout test                mobile                   +bug +ci






















 j/k move   / search   enter open   s start   g/G ends   q leave   

The key bar is the screen's bottom row, below the rest of the list:

 pick   @working   14 tasks · 1 overdue · 1 due today · ▶ #48 running

       ID          URG  TASK                                           PROJECT  DUE             TAGS
 ▸     47  H ▄▄▄▄ 18.1  Renew the TLS certificate for api.example.dev  infra    2d ago          +ops
   ▶   48  H ▄▄▄▄ 17.8  Ship the v2 pricing page                       website  today 17:00     +launch
       49  H ▄▄▄▄ 17.0  Fix token refresh race on Android              mobile   tomorrow 17:00  +bug
       50  H ▄▄▄▄ 15.9  Rate-limit the /search endpoint                api      Sat             +perf
       58  L ▄▄▄▁  9.4  Book the dentist                               home     Tue
       52  M ▄▄▃▁  8.6  Dark mode for the settings screen              mobile   25 Sep          +ui
       56  M ▄▄▁▁  6.0  Accessibility pass on the signup flow          website  28 Sep          +a11y
       54  M ▄▂▁▁  4.3  Cut build time under five minutes              infra                    +ci
       53  M ▄▂▁▁  4.2  Move nightly backups to object storage         infra                    +ops
       55  M ▄▂▁▁  4.0  Add OpenAPI examples for every endpoint        api                      +docs
       57  L ▃▁▁▁  2.0  Replace the carousel on the home page          website                  +ui
       59  L ▃▁▁▁  2.0  Archive last year's analytics dashboards       website
       61  - ▁▁▁▁  0.4  Sketch ideas for the Q4 offsite                home
       60  - ▁▁▁▁  0.1  Investigate flaky checkout test                mobile                   +bug +ci






















 j/k move   / search   enter open   s start   g/G ends   q leave   

pick needs a real terminal (it draws a screen), so in scripts use tasqx next to ask the same question and tasqx start <ref> to act on it.

Leaving without starting a task exits 0: reading your tasks and starting none of them is an ordinary way to use it, so tasqx pick && … and a prompt indicator survive q. A filter that matches no task still exits 4, and so does an empty working set: that is a question tasqx could not answer, not a session you ended.

tasqx undo

Alias: u

Take back the newest recorded change.

tasqx undo

undo is deliberately narrow, and honest about it:

• Twelve operations are undoable: done, cancel, modify, tag, stop, untag, undep, annotate, annotate --edit, annotate --move, adjust and accept. Everything else is refused by name, with the command that does take it back — undoing a start is tasqx stop, undoing an archive is tasqx unarchive.
• Undoing a done puts the task back in the status it left. If it was running, the interval reopens and its time comes back off the total; criteria the completion proved (an agent's checks_passed) go back to open. If completing it spawned the next instance of a recurring task, that instance is removed too — but only while nothing has touched it. Touch it (annotate it, change it, start it) and undo refuses, naming it, rather than throw your work away. A completion that also recorded a token measurement is refused too: a measurement is the record of what a turn cost, and undo does not retract one.
• Undoing a cancel puts back the status it left. Undoing a modify puts back every field it changed, and the answer lists them, so a cleared project is back and due is cleared again. Undoing a tag takes off only the tags that call attached, not one the task already had.
• A modify or tag written by an older tasqx did not record what it replaced, so undo refuses those and says so; from this version on every one does.
• It reverses the newest recorded event, which is not always the last command you typed: a command that changed nothing recorded nothing, so undo reaches past it. That's why the answer names exactly what it undid — read it.
• Undo appends its inverse to the event log rather than erasing anything, so your history reads "X happened, then it was undone".
• There is no redo.

Dependencies

"This can't start until that is finished." Dependencies turn a pile of tasks into an ordered plan: blocked tasks drop out of your working set, and finishing a task tells you what it just unblocked.

tasqx dep

Make one task wait on another. The order is: dependent first, prerequisite second.

Make task 2 wait on task 1:

tasqx dep 2 1

Task 2 is now blocked: it disappears from tasqx list's default working set and from tasqx next, because you can't act on it yet. It reappears the moment task 1 is done or cancelled — and tasqx done 1 names it in the answer.

Blocked work isn't invisible, though: the dashboard keeps it on screen — its TASKS panel holds blocked rows alongside the rest and its header counts them — precisely because the default filter hides these tasks everywhere else.

tasqx undep

Remove a dependency edge, same argument order as dep:

Task 2 no longer waits on task 1:

tasqx undep 2 1

If that was the task's last unfinished prerequisite, it unblocks immediately.

Building a chain

Dependencies pay off when you break a feature into steps:

• tasqx dep 2 1: migration waits on schema
• tasqx dep 3 2: shipping waits on migration

tasqx add Design the schema
tasqx add Write the migration
tasqx add Ship it
tasqx dep 2 1
tasqx dep 3 2

Now tasqx next walks you through the chain in order, one actionable task at a time — and an AI agent working through MCP does exactly the same.

Dates, Reminders and Recurrence

tasqx reads dates the way you'd say them, and four different date fields let you say four different things about when.

Every date field — due, scheduled, wait — takes the same natural-language grammar, through the flag or through the sugar. It resolves to RFC3339 at the moment you type it.

Writing a date

Anywhere a date is expected — due:, --scheduled, wait:, remind: — you can write:

tomorrow            friday              friday 17:00
in 3 days           eom                 at 6pm
-1d                 2026-09-15          2026-09-15T17:00

eom is end of month. -1d is yesterday. A bare weekday is the next one after today, so on a Wednesday friday is in two days. next friday is that weekday in the following Monday-to-Sunday week (nine days out), and next week is that week's Monday; this friday and last friday are refused rather than guessed. A bare time that has already passed today rolls to tomorrow. Full RFC3339 works when you want to be exact.

Everything is UTC. A bare date is midnight UTC, and a clock time is a UTC clock — due:17:00 is 17:00 UTC wherever you type it, whatever zone the machine is set to, and every screen prints it back as 17:00. An offset you write yourself (+02:00, or a trailing Z) is honoured as written: 2026-07-20T17:00:00+02:00 means another zone's clock, and is converted to UTC on the way in.

What you can write

The rules that resolve ambiguity

tasqx add "Overdue ping" --due -2h

error [bad_request]: could not parse date: "-2h" (try e.g. tomorrow, friday, 2026-07-20, "in 3 days" (day/week/month/year offsets only, no hours/minutes), eom, or 2026-07-20T17:00)

A leading hyphen needs no escaping

--due -1d works. It looks like it should trip the argument parser into reading -1d as a flag — every date-taking flag opts out of that explicitly, so a signed offset is always a value:

tasqx add "Renew the TLS cert" project:work.tasqx +ops --due -1d

▌ #3  Renew the TLS cert
▌ added   - ▄▄▄▄ 12.0   work.tasqx   due yesterday   +ops

The four date fields

scheduled and wait both keep a task out of your working set until their moment arrives — the difference is what you mean, and tasqx agenda places tasks on scheduled (or due), never on wait.

Estimates

Human durations, parsed at the edge and stored as ISO-8601 so report can total them. 4h, 90m, 1h30m, 2d, 1w, or ISO PT4H directly.

tasqx add "Nail down the schema" est:soon

error [bad_request]: could not parse duration: "soon" (try e.g. 4h, 90m, 1h30m, 2d, 1w, or ISO PT4H)

Reminders

remind: takes an offset from the due date, or an absolute time:

The offset stays symbolic: move the due date and the reminder moves with it.

Reminders fire only while tasqx daemon is running. A task notifies you only if you gave it a remind; nothing else ever puts a task on the reminder heap.

The two forms

The sign is what disambiguates them: a leading - or + means offset, anything else goes to the date parser. Without that rule 3d would be ambiguous — "3 days before due" or "in 3 days"?

Offsets take s, m, h, d, w. Negative is before due, which is what you almost always want.

tasqx modify 1 --remind -1h
tasqx show 1

▌ #1  Ship the v1 JSON API freeze
▌ modified   remind -1h   H ▄▄▄▄ 15.7   work.tasqx   due Fri   +api +release   est 4h   rev 2
▌ #1  Ship the v1 JSON API freeze
▌
▌ status      pending           urgency     H ▄▄▄▄ 15.7
▌ project     work.tasqx        due         Fri (in 3 days)
▌ remind      -1h               estimate    4h
▌ tags        +api +release     created     today 07:51 (just now)
▌ modified    today 07:51 (just now)
▌ rev         2

Who delivers them

The daemon. It keeps an in-memory min-heap of upcoming reminder instants, rebuilt from the store on start and whenever a task changes. A one-shot tasqx command never fires anything — there would be nobody to fire it.

tasqx add "Deploy the release" --due "2026-07-16T09:00" --remind -1h
tasqx daemon --socket tasqx-remdemo

▌ #1  Deploy the release
▌ added   no project · set a default with tasqx use <project>   - ▄▄▄▂ 10.3   due Thu
tasqx daemon: listening on tasqx-remdemo (Ctrl-C to stop)
tasqx daemon: store ~/.local/share/tasqx/tasks.db
tasqx reminder: [#1] Deploy the release (due 2026-07-16T09:00:00Z)

That reminder had already ripened (due 09:00, minus 1h, and it was past 08:00) — so it fired on the next daemon start. A reminder that ripened while the daemon was down still fires, once, on the next start. Sleeping your laptop does not lose it.

It fires exactly once

Firing writes a reminded event, and that event row is the dedupe record. Restart the daemon and the same reminder does not come back:

tasqx daemon --socket tasqx-remdemo   # second start, same store

tasqx daemon: listening on tasqx-remdemo (Ctrl-C to stop)
tasqx daemon: store ~/.local/share/tasqx/tasks.db

Silence — correct. The key is the (task, instant) pair, not just the task: moving due moves a relative reminder to a genuinely new instant, which should fire again.

Delivery never fails

The always-compiled backend writes one line to stderr and returns. That is the headless/CI-safe path: with no notification transport anywhere, delivery degrades to a logged line and exit 0 — never an error.

Native OS toasts (Windows, macOS, Linux/D-Bus) live behind the off-by-default notify-os build feature and need an explicit opt-in:

# config.toml
[notify]
enabled = true

Even then the stderr line still comes first, so the verifiable surface never depends on which backend is live.

Firing one by hand

reminder.fire takes a ref and an at instant, and it is idempotent — the second call reports fired: false rather than notifying twice:

echo '{"tasqx":"1","id":"r1","method":"reminder.fire","params":{"ref":"1","at":"2026-07-16T00:00:00Z"}}' | tasqx api
echo '{"tasqx":"1","id":"r2","method":"reminder.fire","params":{"ref":"1","at":"2026-07-16T00:00:00Z"}}' | tasqx api

{"id":"r1","ok":true,"result":{"at":"2026-07-16T00:00:00Z","fired":true,"short_id":1},"tasqx":"1"}
{"id":"r2","ok":true,"result":{"at":"2026-07-16T00:00:00Z","fired":false,"short_id":1},"tasqx":"1"}

And the event is in the log, where the dedupe check reads it:

{
  "actor": "user",
  "entity": "task",
  "op": "reminded",
  "payload": {
    "at": "2026-07-16T00:00:00Z",
    "due": "2026-07-17T00:00:00Z",
    "remind": "-1h",
    "short_id": 1,
    "title": "Deploy the release"
  },
  "ts": "2026-07-16T08:52:35.4429051Z"
}

Recurrence

repeat: makes a task come back. A recurring task is a template: completing an instance spawns the next one with its date advanced by the rule. Set it with repeat: / every: / --repeat, and stop it with tasqx modify <ref> --clear recurrence.

This is a deliberate subset — not full RRULE. Anything outside it is a clean error.

tasqx add Water plants repeat:"every 3 days"
tasqx add Standup repeat:"weekly on mon,wed,fri"
tasqx add Pay rent due:"2026-09-01" repeat:"monthly on day 1"
tasqx add Team retro repeat:"monthly on the 2nd tuesday"

• Completing a recurring task spawns the next occurrence; the answer shows it. The occurrence keeps the task's first note (its description) and its checks, reset to open, and its Repeats row names the one it came from (every week from #604). tasqx brief on it adds a "Last time" section quoting what the previous occurrence delivered.
• Missed occurrences don't pile up — they collapse into a single next one.
• every N months can drift across short months; anchor with monthly on day 15 when the day of month matters.
• Stop a recurrence with tasqx modify <ref> --clear recurrence.

tasqx add "Water the plants project:home repeat:\"every 3 days\" due:today"
tasqx done 4
tasqx show 5

▌ #4  Water the plants
▌ added   - ▄▄▄▃ 11.4   home   due today 23:59   ↻ every 3 days
▌ #4  Water the plants
▌ done today   home   due today 23:59
  #5  next, due Fri
▌ #5  Water the plants
▌
▌ status      pending           urgency     - ▄▄▃▁ 8.9
▌ project     home              due         Fri (in 4 days)
▌ repeats     every 3 days      created     today 07:51 (just now)
▌ modified    today 07:51 (just now)
▌ rev         1

Missed occurrences collapse

If the computer was off for a week, a daily task does not hand you seven instances. The rule advances at least once and then skips every slot at or before now, so you get exactly one future instance. A backfill storm is never useful.

Month-end, precisely

The two monthly forms differ on purpose, and the difference matters at month boundaries:

Dashboard and Live View

Two ways to watch your work instead of querying it, and the daemon that makes the live one possible.

Screens and pipes

Six commands open a screen instead of printing a table, and each answers a pipe in its own way. tasqx pick, tasqx dashboard and tasqx config edit refuse one outright rather than write escape codes into it. tasqx memory list and tasqx notes print their one-line-per-row tables instead, and tasqx watch prints each update as it arrives rather than repainting a screen — it needs a running daemon either way. tasqx board is the same live view in a browser.

tasqx list never opens a screen. It is the verb that always prints the table, on a terminal and through a pipe alike.

tasqx dashboard

Alias: dash

A full-screen overview of everything: your tasks, your projects, a burndown, recent activity, effort and token spend — six panels (tasks, projects, burndown, pulse, effort, tokens) over one snapshot, with a header that counts what matters (17 open · 1 active · 2 overdue · 3 blocked · 8 done/week).

• It's read-only, with two exceptions: p opens the task browser, pick. Enter there reads a task, and s starts it and brings you back. N opens the notes browser, where a note can be archived, promoted or removed; closing it brings you back. q, Esc and Ctrl-C all close the dashboard.
• Blocked work stays visible here, which is the point: the default task list hides it. There is no BLOCKED panel: the NOW, NEXT UP, DUE, BLOCKED and RECENT panels were folded into the one TASKS panel, so a blocked task keeps its row there (and its "blocked": true under --json), and the header counts them (3 blocked).
• --json is not the screen in text. The document carries a payload for four of the six panels — tasks, projects, burndown and tokens — beside the status header it always writes and a panels array naming what you asked for. pulse and effort are drawn from the screen's own model, so tasqx --json dashboard --panels pulse,effort is a valid request that answers with no panel payload at all.
• Layout adapts to your window; below 56×14 it won't open.
• Configure it under [dashboard] in the config: which panels, in what order, refresh mode and time window (tasqx config list shows the options).

For scripts and agents: the dashboard only opens when both stdin and stdout are an interactive terminal. Piped, redirected, or with --json, a bare tasqx prints the plain task table instead. But an agent or harness that allocates a pty looks interactive, and a bare tasqx there opens a full-screen program that waits for a keypress. So in anything automated, spell the verb: tasqx list always means the table.

tasqx watch

A task list that redraws itself the moment anything changes — from another terminal, from an AI agent, from anywhere.

watch subscribes to a daemon and re-renders on every task.changed push; the daemon pushes a notification on every write. It takes a filter, defaulting to the working set, and any filter narrows what it follows. Ctrl-C stops it. It needs a running daemon and will never auto-spawn one — it hints instead:

tasqx watch --socket nope

tasqx watch: no daemon reachable at nope
hint: start one with `tasqx daemon` (add `--socket nope` to match)

On a terminal it clears the screen and repaints the table. Through a pipe it streams one line per event instead — so it composes with everything else in your shell:

tasqx watch --socket tasqx-docsdemo | cat
# ... meanwhile, in another shell:
#   tasqx --socket tasqx-docsdemo add "Wire up the docs page ..."
#   tasqx --socket tasqx-docsdemo done 3

4 tasks · 1 overdue

  ID          URG  TASK                         PROJECT     DUE        TAGS
   1  H ▄▄▄▄ 15.7  Ship the v1 JSON API freeze  work.tasqx  Fri        +api +release
   3  - ▄▄▄▄ 12.0  Renew the TLS cert           work.tasqx  yesterday  +ops
   5  - ▄▄▃▁  8.9  Water the plants             home        Fri
   2  - ▄▄▂▁  7.1  Write the user guide         work.tasqx  Mon        +docs
task.changed op=add short_id=6
task.changed op=done short_id=3

Leave it open on a second monitor while an agent works through your backlog — you see every task start, complete and unblock as it happens.

tasqx board

The same live view in a browser: a kanban with a column per state, updating as tasks change, where you move a task by dragging its card.

Like watch, board needs a running daemon. Ctrl-C stops it.

The columns are the states tasqx already derives, each headed by the filter that fills it: Triage status:triage (proposals), Backlog status:backlog, Blocked @blocked (which never holds a proposal), Ready @working, Active status:active (one at a time) and Done completed.after:-7d. Inside a column cards are ordered by urgency, on the same scale and in the same three bands as tasqx list; a ▶ marks the running task and ⊘ a blocked one. A card opens (click, or Enter) into its checks, blocked-by list and opening note. The search box filters by title, tag, project and id, and the lanes menu groups a column by project or by priority. The page follows your terminal theme, light or dark by your system setting, and shows daemon · offline if the connection drops.

Keys: j/k move between cards, h/l between columns, Enter opens, / searches, Esc closes, s starts the focused card and d completes it.

Moving a task. Drag a card to another column and the board sends the same command you would type:

While you drag, a tray appears under the card: drop on H, M or L to set the priority, clear to remove it, or cancel to cancel the task. Within a column cards stay ordered by urgency; there is no manual order to drag into. Every drag has a button in the card's panel (click it, or Enter), which is also how you move a task on a touch screen.

A message at the bottom says what happened in the command's own words — which task a start stopped and after how long, which tasks a completion unblocked — with Undo for a stop, completion, cancel or priority/date change. Undo is tasqx undo with one extra condition: it only takes back your drag if nothing has been written since, so it can never undo someone else's change. A start or reopen is undone by dragging the card back.

If something else changed the task after the board drew it — you, in a terminal, or an agent — the drop is refused, nothing is written, and the board says "another session changed it" and shows the task as it now is. Every change the board makes is recorded with board as its actor, so tasqx api event.list tells a drag apart from a command or an agent.

Editing a card. The panel is a form too. Tick or untick a check, add a note, change the due date, estimate, wait or scheduled date, set the priority, and add or remove a dependency; each change is one command with the card's revision, so a task changed elsewhere since is refused rather than overwritten, and the footer always shows the revision as it now is. A note goes into the same search as every annotation (tasqx memory search), so name files and symbols in it. Adding or removing a dependency moves the card between Blocked and its other column without a drag. Titles and project moves stay with the CLI. Undo covers a note, a removed dependency and a field change; a tick or an added dependency is changed back by hand.

--scope read serves the board for a wall screen or a standup: no drag, no buttons, and the server refuses any change that is sent anyway.

Who can reach it. The board binds 127.0.0.1 and nothing else, so it is never reachable from another machine. On a shared computer another user could still connect to a loopback port, so the page is also behind a random secret token: the URL tasqx board prints carries it once, the browser trades it for a cookie, and every other request without that cookie is refused. Requests from another website, or under a hostname other than 127.0.0.1 or localhost, are refused too, which is what stops a web page you are browsing from reading or changing your backlog through your own browser. The server forwards only the handful of commands a drag needs, each carrying the revision the card was drawn at. The board is single-user and local. Put it behind a reverse proxy and authentication is the proxy's job.

Without a fixed port, each run takes a free port and a fresh token. With one (--port, or board.port in the config) the token is kept in a file next to config.toml, readable only by you, so a bookmark of the printed URL keeps working after a restart.

The page is one self-contained file: nothing is fetched from the internet.

The daemon

The daemon is optional. It holds one database connection, serves the JSON API over a local socket to many concurrent clients, pushes change notifications, and runs the reminder scheduler. The CLI never requires it. The agents page covers the rest of it, including the OTLP receiver: tasqx daemon.

One-shot or daemon?

If a daemon is reachable, one-shot commands route through it automatically — single writer, live-update semantics for free. If not, they open the store in-process. Same command surface either way, and a missing or stale socket falls back immediately rather than hanging. --no-daemon forces the in-process path.

$TASQX_DB always wins over a daemon on another store. Naming the file the daemon serves, commands route through it as usual. Naming a different file, a daemon found on the default socket is passed over and the command runs in-process against $TASQX_DB; a daemon named by --socket or $TASQX_SOCK is refused with exit 2, naming both files.

Four surfaces never route through a daemon: api, mcp serve, chart and report --html open the store in-process, always. They refuse an explicit --socket rather than ignore it, because a flag that names a daemon and is silently discarded aims your write at a different store than the one you asked for.

Socket addresses

Resolution order: --socket, then $TASQX_SOCK, then the platform default.

Running it

Diagnostics go to stderr; the socket carries the newline-delimited JSON API. Ctrl-C stops it cleanly, unwinding the accept loop and removing the socket file (a no-op for Windows named pipes). --db points it at a specific store.

tasqx daemon --socket tasqx-docsdemo

tasqx daemon: listening on tasqx-docsdemo (Ctrl-C to stop)
tasqx daemon: store ~/.local/share/tasqx/tasks.db

It stays until you stop it. Set [daemon] idle_timeout to a number of minutes and it will instead exit by itself once that long has passed with no client connected, no subscriber attached, no reminder about to ripen and no telemetry posted to its OTLP receiver — and it says so on stderr on the way out. 0, the default, means it never does. Turning the receiver on does not hold it open: only exports that actually arrive count as work. An idle exit also leaves a note beside config.toml: the first command that then fails to reach the daemon reports the retirement and which store is no longer being served, because a daemon leaving changes where the same command line writes.

Now route a command through it — note this is the ordinary add, unchanged:

tasqx --socket tasqx-docsdemo add "Wire up the docs page +docs project:work.tasqx due:tomorrow"

▌ #6  Wire up the docs page
▌ added   - ▄▄▄▃ 11.4   work.tasqx   due tomorrow   +docs

Reports and Charts

What happened, what's left, and where the time and tokens went — in the terminal, or as an HTML page you can send to someone.

tasqx report

Summary counts, optionally grouped.

The same numbers as one self-contained HTML file:

tasqx report --html --out review.html

The HTML report is a single file with inline styling and no external requests — it works from a mail attachment, a chat upload, or a USB stick. A filter scopes both modes identically, so the page and the terminal table always answer the same question.

The page is a review of a period, the 7 days ending today unless you pick another:

tasqx report --html --since 2026-09-01 --until 2026-10-01 --out september.html

Annotation bodies are not put in the file, because a report is meant to be shared and that is where client detail lives. --with-notes embeds the newest three per task behind a toggle. A filter that names one project (tasqx report project:acme --html) makes a page about that project alone, and a task it depends on elsewhere shows as "a task outside this report".

--all adds cancelled tasks to the search. --metrics picks terminal columns and is refused with --html, and the page is always grouped by project, so tasqx report status --html is refused too.

The TOKENS column names a group's largest bucket with that bucket's own count (cacheR 1.2M), or - when nothing was spent. The four buckets — in, out, cacheR (cache read) and cacheW (cache creation) — are never blended into one figure; --json and report --html carry the full split. They are filled by self-reported counts on task.done (the primary source, via token.add — see tasqx tokens), falling back to parsing local AI-tool transcripts when tokens.enabled = true, or by the daemon's OTLP receiver when otlp.enabled = true (tasqx daemon).

Grouping and what counts

tasqx report [group_by] [filter] [--all] — group by project (default), status, or priority. Estimates total as ISO-8601 durations, which is why est: is parsed at the edge rather than stored as opaque text.

What counts. A report is an aggregation, so it leaves cancelled tasks out — tasqx has no hard delete, and without this every task you ever threw away would inflate your totals forever. Done tasks still count: completed work is real work, and it carries nearly all your tracked time. Two ways to override that: pass --all to count everything including cancelled, or name a status in the filter — tasqx report status:cancelled means what it says and is taken literally.

tasqx report

PROJECT               COUNT         EST  OVERDUE     TRACKED        TOKENS
home                      1        PT0S        1        PT0S             -
work.tasqx                3     PT5H30M        1        PT0S   cacheR 1.2M

tasqx report status

STATUS                COUNT         EST  OVERDUE     TRACKED        TOKENS
pending                   4     PT5H30M        2        PT0S   cacheR 1.2M

The HTML report

tasqx report --html emits a weekly review as one self-contained file — inline CSS, inline SVG charts, no external requests — themed from the same palette as your terminal. Exactly like the tasqx docs guide.

tasqx report --html --out review.html

Wrote self-contained HTML report → review.html

Without --out it writes to stdout. One small inline script does the clicking; the page reads fully without it.

tasqx report --outcomes

tasqx report says what the work cost. --outcomes says how it went.

tasqx report --outcomes

PROJECT  CLOSED  DONE  REWORK  FORCED  SILENT     CALIB  DROPPED  OVER  UNPROVEN  UNBRIEFED               TOKENS
api           7     6     0/6     0/6     0/6  ×1.17 n3      1/7   1/2         -        6/6  cacheR 7.0M ~medium
infra         9     8     0/8     0/8     1/8  ×1.00 n4      1/9   1/1       1/2        8/8  cacheR 2.8M ~medium
mobile       15    13    2/13    0/13    0/13  ×1.35 n2     2/15   1/3       1/3      13/13  cacheR 7.7M ~medium
website      15    13    0/13    1/13    2/13  ×1.58 n9     2/15   0/2       0/5      13/13  cacheR 2.4M ~medium

REWORK / FORCED / SILENT / DROPPED / OVER / UNPROVEN / UNBRIEFED read count over the completions or
closings they were counted against — a rate with no denominator beside it is not a rate. OVER counts
only the completions that had a budget and UNPROVEN only those that had acceptance criteria.
UNBRIEFED counts completions of a task no brief or memory-carrying start was ever read for. CALIB is
the median tracked-over-estimate ratio and the number of completions carrying both figures.

Every rate reads count/n rather than a percentage, deliberately: "3/12" and "3/3" are the same percentage and very different news, and a rate over three completions is not evidence of anything. Check the denominator before you act on the number.

The scope is tasks that closed, by the date they closed — so a completion that was later reopened still counts, which is the whole point of the REWORK column. Open work is invisible here; plain tasqx report is the view for work in flight. Group and filter as usual (tasqx report --outcomes project, tasqx report --outcomes +api), and window with --since/--until.

tasqx chart

Charts drawn right in the terminal, from the event log. A bare tasqx chart draws throughput.

• throughput answers "am I finishing as fast as I'm adding?"
• heatmap answers "when do I actually get things done?"
• burndown answers "is the pile shrinking?" (--days 30 widens the window)

Each takes the same filter DSL list/report/agenda do, so a chart can be scoped to one slice of the store:

tasqx chart burndown project:work

only counts work's own tasks and events — the whole store otherwise. tasqx chart burndown --project work is shorthand for the same thing; project:work on the filter is the more general form, since it combines with a second predicate (tasqx chart burndown project:work +urgent).

The charts degrade cleanly from truecolor terminals down to no color at all.

Chart samples

All three read the append-only event log, so they are history, not a snapshot — and they are pure reads that never touch your tasks.

tasqx chart throughput --weeks 12

Weekly throughput   added [#]  done [#]
  W27  added   0   done   0   net   0
  W28  added   0   done   0   net   0
  W29  added ##########  5   done ##  1   net  +4
  > 4-wk velocity 0.2 done/wk - WIP trending up

tasqx chart heatmap --weeks 4

Completions - last 4 weeks   . 0  : 1-2  + 3-4  # 5+
  Mon . . . . 
      . . . . 
  Wed . . . . 
      . . . : 
  Fri . . . . 
      . . . . 
  Sun . . . . 
  > 1 done - current streak 1 days - best 1

tasqx chart burndown --days 7

Remaining open - all tasks
    4  ______#
    0  2026-07-10 -> 2026-07-16
  > 4 left - up 4 over 7 days

tasqx why

Not a report, but the same spirit: tasqx why <ref> breaks a task's urgency score into its components, so the ordering of every list stays explainable. See Finding Tasks.

Memory

tasqx can remember more than tasks. The memory system stores knowledge — runbooks, decisions, conventions, research — and makes it searchable together with every task annotation you've ever written. For AI agents this is the difference between starting cold every session and starting informed.

tasqx memory add

Store one knowledge document. The body is kept exactly as given.

tasqx memory add "Deploy runbook" "Deploys go through the blue-green pipeline"

• --standing marks the doc as standing: a ruling that belongs in every session of its project (or every project, when unscoped) until it is cleared, so a correction given once is not forgotten by recency. MCP clients receive standing docs when a session starts. Past 15 standing docs in one scope, add answers with a hint to merge or retract.
• --source names where the doc came from, and names one doc: a source another document already holds is refused with conflict (exit 5), naming that document, so import always knows which one to replace. The same goes for update --source.

When a doc of the same project, or an unscoped one, already reads like the new doc, add still stores it and prints a note: line naming that doc, up to three of them, so you can update or remove one instead of keeping both. --json carries them as similar, an empty list when there are none.

tasqx memory list

Browse your documents without a query — the enumeration search cannot do, since ranking needs words to rank.

tasqx memory list

• On a terminal this opens a full-screen browser: j/k move, / searches as you type, Enter reads the document beside the list, q leaves.
• Piped, under --json, or with --limit/--offset, it prints one line per document instead — a screen would be the wrong answer to a pipe.
• Newest-modified first, paged the same way as tasqx list.
• --standing lists only the standing docs (and prints the table).

tasqx memory search

Search over your documents and your task annotations, by meaning as well as by words: a note that says "login errors" is found by sign-in failures. An embedding model built into the binary ranks entries by meaning beside full-text search (bm25), the two lists are fused, and each hit says which found it.

tasqx memory search blue-green

• Plain words are matched as phrases, so hyphens and dots are safe to type.
• An entry with every word ranks above one with only some of them (filler words like "the" aside); a hit with only some is marked some words, so a partial match is never read as a full one.
• A hit found by meaning alone is marked ≈ with its similarity on the line under it; its passage is the one closest to your words.
• An identifier such as D41 or #607 has no word to match by meaning, so it is looked up by its characters alone. --mode lexical does that for any query: exact words only, the way search worked before meaning was added. --mode semantic is meaning only.
• --min-similarity (0 to 1, default 0.30) is how close in meaning a hit must be. Lower finds more distant paraphrases, and more noise.
• The model reads English; text in another language is found mostly where the query shares its words.
• --scope docs or --scope annotations searches only one half (default all). --source-prefix myrepo/docs/adr/ keeps only the docs whose source starts with that text (literal, case-sensitive) and leaves annotations out. A doc imported from a git checkout is sourced under the repository's directory name.
• Power users can pass --raw for FTS5 operator syntax (words only).
• The answer includes the query that actually ran, so "no hits" is distinguishable from "nothing stored about this".
• A doc hit whose origin file has changed since it was imported (or last refreshed) carries the word stale on its line, in memory search and in the FROM MEMORY section of brief, so you can tell a ruling that is behind its file from one that still matches it. --json has it as "stale": true. memory list and memory show do not check the file.

tasqx memory show

Read one document whole, by the id a search hit gave you.

tasqx memory show 019f8422-7b3e-7c41-a2d9-6f1b0e5c8a12

tasqx memory update

Correct a document in place, keeping its id.

tasqx memory update 019f8422-7b3e-7c41-a2d9-6f1b0e5c8a12 --body "corrected text"

• --title, --body, --source, --project and --standing true|false each replace that field; omit one and it stays as it was.
• Guarded by the same optimistic-concurrency rev tasqx modify uses: --expected-rev fails with conflict (exit 5) if the document moved under you since you read it.
• This is the correction path, and the reason rm is rarely the right verb: adding a fixed copy leaves the wrong one searchable, and removing loses the id every search hit and annotation pointed at.

tasqx memory import

Turn a folder of markdown into searchable memory — one document per file, the title taken from the first # heading.

tasqx memory import docs/adr

• One transaction: if any file fails, nothing is imported.
• Re-importing the same directory replaces those documents instead of duplicating them, so it's safe to re-run whenever the sources change. Every document a re-import replaced is named under the summary line, with the title it had (replaced_docs under --json). A document whose title and text are exactly what is stored is left alone — same revision, no event, not counted as replaced — and the summary reports it as unchanged (2 replaced, 3 unchanged; unchanged under --json). Over the JSON API, a batch that names one source twice is refused whole.
• A document whose recorded file still exists and is not the file being imported under its source — two clones under the same directory name — is never replaced: the whole import is refused with conflict (exit 5), naming the document and both files. A worktree and its main checkout are one repository, not two clones, so importing from either replaces the same documents. A recorded file that cannot be checked at all (a permission error) refuses the import too, with exit 2, rather than being taken for gone.
• A replace bumps the document's revision, so an update --expected-rev taken before the re-import is refused with conflict instead of silently overwriting the freshly imported text.
• --project scopes every document in the batch, so an agent's own repo docs land in that project's memory instead of unscoped. Omitted, a new document stays global and an existing one keeps whatever scope it already had (like --standing on a re-import); naming a project moves an existing document's scope there, so re-pointing an import at a different project rescopes it.
• The stored source is the git toplevel's directory name followed by the file's path inside the repo — clouter/README.md — or, outside a git work tree, the current directory's name followed by the path under it. A worktree uses its main checkout's name, so it replaces the same documents. The same folder imported as docs/, ./docs/ or its absolute path, from any directory, is one document per file, not several, and two repos' README.md are two documents, not one. Across machines that holds for checkouts with the same directory name: independent clones under one name share keys and conflict, while differently named checkouts get distinct keys. Documents imported before this keep their old, unprefixed source; the next import of the same file lands beside them. An import that finds a doc already holding an older spelling of the same file never removes it, but prints a note: line naming it so it can be retired by hand — as the same file when that doc recorded which file it came from, and only as a possibility when it did not. A backslash folds to / in that comparison only on Windows; on unix docs/a\b.md is its own file name, never a spelling of docs/a/b.md. A symlink pointing at another file in the same import collapses onto it too — same source once resolved — so only the real file becomes a document, and the alias is named in a note: line instead of refusing the batch.
• tasqx memory import --refresh takes no path. It walks the documents already imported, compares each against the file it was read from, and re-reads the ones whose file has changed — keeping the document's id, its project and its standing flag, and bumping its revision. A file that was only touched, without its text changing, counts as unchanged: the stored size and timestamp are a fast filter, and the bytes are what decides. A document whose file can no longer be read is named and kept, never deleted — the file may be on another machine or a volume that is not mounted — and the command still exits 0, so a refresh in a script does not fail over a file somebody moved. An MCP session runs this same sweep on its own initialize when its scope allows writes, so an agent's session opens on the working tree without a watcher or a daemon job.
• Each imported document also records where it came from: origin_path (the file's absolute path on this machine), origin_mtime (its modification time in unix seconds) and origin_size (its size in bytes), all shown by memory show --json and carried by export. They say what the file looked like when it was read, so a later check can tell whether it has changed since; identity is still source, and memory add never sets them.

Put together, this is one model, not three separate features: memory remembers which file a document came from, and checks that file only when you ask — a search, a brief, --refresh, or an agent session starting — never by watching the filesystem in the background. Nothing is ever deleted because a file moved or disappeared; it's named so you can decide what to do about it.

tasqx memory verify

Check the code that documents talk about, not the file they came from.

tasqx memory verify
tasqx memory verify 019f8422-7b3e-7c41-a2d9-6f1b0e5c8a12

A document cites code through its source (a <repo>/<path> key) and every backticked path, path:line or path::symbol in its body. Run from inside a git checkout, verify checks those against the checkout's working tree: each path must exist, and each symbol must appear as a whole word in the file it names. A path in the body is checked only when its first folder or file exists at the top of the checkout, so a branch name or a path written relative to a subfolder is skipped rather than reported missing. Each document gets one status:

• ok: every cited path and symbol is there.
• missing_path: a cited file or directory is gone, for example renamed.
• missing_symbol: the files are there, but a cited function or type is not.
• unverifiable: nothing could be checked. The document cites no code, its source or its project names a different repository, it is a global document whose source names no repository, or you are not in a git checkout. This is never reported as ok.

The text output lists the stale documents with the references that are gone, then a count per status; --json lists every document. --project checks one project's documents. The command exits 0 even when documents are stale, because it is a report. Nothing is indexed: it is a file check and a text search, run when you ask for it.

A symbol is looked for only in a regular file of at most 4 MB; anything else counts as present. A search hit and memory show --json carry the same check as stale_refs, run in the directory you call them from, and an agent's session start marks a standing ruling whose cited code is gone. Run verify after a rename or a large refactor, and correct what it names with tasqx memory update.

tasqx memory rm

Remove one document, permanently, by id.

tasqx memory rm 019f8422-7b3e-7c41-a2d9-6f1b0e5c8a12

This is a permanent delete, like tasqx unannotate and removing a note, and it exists on purpose: something stored wrong needs a way to be retracted. It is outside undo.

Reach for it only when the document should not exist at all. To fix what one says, tasqx memory update rewrites it in place and keeps the id — no permanent loss, and nothing stale left in the index.

Why this matters for AI agents

An agent connected over MCP reaches this same store — searching works even on a read-only connection. Feed it your ADRs and runbooks with memory import, and past decisions surface while the agent works. And because annotations are indexed too, an agent that documents its work as it completes tasks is building the knowledge base as a side effect.

Notes

A note is for the thing you want to write down before it gets away: an idea, a link to read later, a question for tomorrow. It is not a task. It has no due date and no urgency, it stays out of tasqx list, next, the dashboard's panels and the reports, and memory search never sees it. Write it in a second and forget it safely.

When a note turns out to matter, promote it: it becomes a task, or a memory doc, and the note is archived with a pointer to what it became.

tasqx note

Jot one down. Every word after note is the note, kept exactly as you typed it.

tasqx note try the new tracing exporter
tasqx note https://www.rfc-editor.org/rfc/rfc9457 --project api

• --project files it under a project. Without it the note has none. There is no project: shortcut as add has: a note's words are its own.
• Quote the text when it holds characters your shell reads (#, *, ?, &).
• Notes have their own numbers. Note 3 and task 3 are different things.
• Put -- before text that is a number or starts with -, so it is not read as a note's number or a flag: tasqx note -- -5 degrees tonight.

Read one whole, with its project and the day you added it:

tasqx note 3

Change one by naming it first and saying what to do after:

tasqx note 3 edit try the OTLP exporter instead
tasqx note 3 archive
tasqx note 3 unarchive
tasqx note 3 rm

• edit replaces the text.
• archive puts a note out of sight; it stays under tasqx notes --archived. unarchive brings it back.
• rm deletes it for good. tasqx undo does not cover notes, so archive when you are not sure.

The number always comes first. Any other first word is part of the note, so tasqx note edit the readme writes down "edit the readme". A subverb on its own, or followed by a number (tasqx note archive 7), reads as a command typed the wrong way round: it is refused (exit 2) with the right spelling, and tasqx note -- archive 7 stores it as text.

note used to be another name for annotate. A number followed by text is now refused (exit 2) and names the command you probably meant:

tasqx annotate 42 "called the plumber, waiting on a quote"

tasqx notes

List your notes, newest first.

tasqx notes

2 notes

ID  NOTE                                                                          PROJECT  ADDED
2   idea: a dark-mode toggle in the docs header                                            yesterday
1   read https://www.rfc-editor.org/rfc/rfc9457 before the error-format chan…  ↗  api      2d ago

Each line has the note's number, its first line, ↗ (L without Unicode) when it holds a link, its project and the day you added it. A note that is only a link is never cut short, so you can still copy it; its line runs past the edge of the terminal instead.

• --links shows only notes holding an http:// or https:// link.
• --archived shows the archived ones, promoted notes among them. --all shows open and archived together.
• --search <text> keeps notes containing that text, ignoring case. It is a plain match, not the ranked search memory search does.
• --project <name> keeps the notes filed under that project.

tasqx notes --links
tasqx notes --search exporter --all

The notes browser

On a terminal, tasqx notes opens a full-screen browser over the same notes, and the flags above decide where it opens: --search becomes the search you can edit, --archived and --all choose which notes it holds. Piped, or with --json, it prints the table.

Each change says what it did on the line above the keys, and a refusal is shown there too: a note someone changed after the browser read it is refused rather than overwritten, and the list is read again. A promoted note does not offer t and m. From the dashboard, N opens the same browser, and closing it takes you back.

Promote a note

When a note is worth doing, make it a task:

tasqx note 3 promote task
tasqx note 3 promote task --title "Evaluate the OTLP exporter"

The task lands in the note's project, or your default project when it has none. Its title is --title, or the note's first line cut at 80 characters; when that title does not say everything, the whole note becomes the task's first annotation. The echo is the same card tasqx add prints.

When it is something to remember rather than something to do, make it a memory doc:

tasqx note 3 promote memory --title "Tracing exporters we tried"

Either way the note is archived and remembers what it became. That happens in one step: if the task or doc cannot be made, the note is left as it was. Promotion is final, so a promoted note cannot be promoted again or unarchived. Cancelling the task later does not bring the note back; to capture the idea again, write a new note.

Notes, tasks, memory and triage

Use a note when you are not yet sure. A task asks to be done; a proposal in triage is a task waiting for your yes; a memory doc is something an agent should read before it works. A note asks for nothing.

Every command here takes --json and prints the API's answer. Agents reach notes through the MCP tools tasqx_add_note, tasqx_list_notes, tasqx_get_note (one note; a body over max_body_bytes is cut and marked body_truncated, so raise it to read all), tasqx_update_note, tasqx_remove_note and tasqx_promote_note.

AI Agents and Automation

tasqx treats an AI agent as a normal user. There's one JSON API underneath everything; the CLI is one client of it, and the built-in MCP server is another. An agent gets the same data, the same rules and the same safety properties you do.

tasqx setup

Connects tasqx to Claude Code, Codex CLI and Gemini CLI in one step. For each tool it finds, it registers the MCP server (user level, write access) and installs the tasqx-workflow and retro skills. A tool appears only when claude, codex or gemini is on your PATH; with none of them, setup says how to install one.

tasqx setup

It's a checklist screen — Space toggles an item, Enter installs what's ticked, q quits. Run it again later and it shows what's already in place. Without a terminal it prints that list and exits.

• tasqx setup --list: what is installed, per item
• tasqx setup --yes: install everything not yet present, no screen
• tasqx setup --only retro: limit to one item (mcp, tasqx-workflow, retro); repeatable. Codex and Gemini items carry the tool's name: codex:mcp, gemini:retro
• tasqx setup --yes --force: also overwrite a skill file that differs from the one tasqx carries

Each tool is registered through its own command (claude mcp add, codex mcp add, gemini mcp add); tasqx never edits their config files. The skills land in ~/.claude/skills, ~/.codex/skills and ~/.gemini/skills.

The skill text is compiled into tasqx, so an upgrade brings new skill text with it. A skill file you edited is kept unless you pass --force or tick it on the screen.

tasqx mcp

The built-in MCP (https://modelcontextprotocol.io) server — the standard way AI tools like Claude Code connect to external systems.

• tasqx mcp serve: read-only by default
• tasqx mcp serve --scope write: explicit write access

tasqx mcp serve
tasqx mcp serve --scope write

To wire it into Claude Code by hand, without the skills that tasqx setup adds:

claude mcp add --scope user tasqx -- tasqx mcp serve --scope write

By hand for the other two, the commands tasqx setup runs:

codex mcp add tasqx -- tasqx mcp serve --scope write
gemini mcp add --scope user tasqx tasqx -- mcp serve --scope write

Any other MCP client takes the same shape in its config:

{
  "mcpServers": {
    "tasqx": { "command": "tasqx", "args": ["mcp", "serve", "--scope", "write"] }
  }
}

What the agent can do: list and read tasks, add and modify them, complete them (and learn what that unblocked), start and stop timers, tag, annotate, wire up dependencies, create projects, and search and store memory.

mcp serve works on the store itself, not through a running daemon, so it ignores $TASQX_SOCK (and says so on stderr). That does not hide an agent's writes from tasqx watch or the desktop app: a running daemon notices changes made by other processes on its store, so they show up live, within about half a second.

Forty-three tools, one verb each. Twelve reads: list_tasks, get_task, brief_task, next, summary, outcomes, list_projects, search_memory, get_memory, list_memory, list_notes, get_note. Thirty-one writes: add_task, modify_task, complete_task, reopen_task, cancel_task, triage_task, start_timer, stop_timer, claim_task, release_task, adjust_tracked, tag_task, untag_task, annotate_task, update_annotation, move_annotation, remove_annotation, add_tokens, add_check, set_check, remove_check, add_dependency, remove_dependency, add_memory, update_memory, remove_memory, add_note, update_note, remove_note, promote_note, create_project (all prefixed tasqx_).

What makes this more than remote CRUD:

• One call before starting, instead of five. brief_task returns the task, each prerequisite with what that task concluded, what this one blocks, and relevant memory — under a query tasqx derives from the task's own title, tags and project. The agent supplies no search terms, which matters because a guessed term that finds nothing looks exactly like a store with nothing in it.
• "What now" and "where was I" in one call. next is tasqx next over MCP: the most urgent unblocked task, scoped by project and filter, with the first paragraph of its opening note. With resume: true it also lists the active tasks (and who holds each clock) and the five open tasks annotated most recently, each with the start of its newest note and when it was written. Like get_task, it answers the rendered view, and include_json: true adds the machine block.
• A task with its criteria and prerequisites, in one call. add_task takes checks (strings) and depends_on (short ids or UUIDs) and creates them with the task, all or nothing: an unknown prerequisite or a blank check refuses the whole add and creates nothing.
• Completing a task returns what it unblocked, so an agent can decompose a feature into a dependency chain with add_dependency and then walk it, picking up each task the moment its prerequisites clear.
• "Done" can mean something. Acceptance criteria are rows with a state and a citation (add_check, set_check), not prose in an annotation that nothing can ask about. tasqx never runs a check — the criterion is a claim and the evidence is text it stores verbatim. Completing with one still open is not refused; it is counted.
• The agent can read its own record. outcomes is on the read scope, so even a read-only session can ask what its rework rate on this project is before deciding how carefully to work.
• Agents get long-term memory. search_memory gives even a read-only agent retrieval by meaning and by words over your imported docs and every task annotation — feed it your ADRs with tasqx memory import docs/, and past decisions surface while it works. Annotations feed the same index, so an agent that documents its work is building the knowledge base as a side effect.
• Token spend lands on the task. complete_task takes token counts plus who spent them — or total_tokens, one unsplit number, when that is all the harness reports — and add_tokens records a count that arrives after completion; a log-parse fallback fills gaps and refuses contested samples rather than guess. The table, the dashboard and the HTML report all show what each task cost.

Safety properties worth knowing:

• Read-only sessions can't see the write tools at all — an agent can't call what it isn't offered. (Scope configures the local process; it's not authentication.)
• There's no bulk-delete tool, on purpose. Cancelling goes through the same reversible, logged path as everything else, so an agent can't quietly destroy a week of work.
• The permanent deletes (remove_memory, remove_annotation, remove_note) each say so in their description, so the host's confirmation gate applies.
• initialize answers with instructions, a scope-aware workflow the host may inject into the agent's system prompt; under read-only scope it names no write tool. It also carries the session's standing memory docs, for the project named by the directory mcp serve runs in (or one of its parents), else the default project, within a 3 KB budget.
• A write-scoped initialize also refreshes imported docs from disk before it answers, so a session opens on the working tree with no watcher and no daemon job needed; a read-only session skips the sweep, and instructions names how many docs were refreshed or went missing only when that count is not zero.

tasqx_get_task and tasqx_brief_task take a view argument, "markdown" by default. Pass view: "card" when a person has to decide on the task — one the agent proposes adding, or one they asked about: the rendered block becomes a fixed-width, box-drawn card meant to be pasted whole into a chat reply or a document, instead of the usual prose. The same card is available from a shell: tasqx show 42 --card prints the identical bytes.

Routine events do not need a card. Starting or completing a task is one line the agent writes from what it already read — the brief and the completion's unblocked list:

▶ #711 Add unc output style · M · 20m · 0/2 checks
✔ #711 done · 2/2 checks · unblocked #712

A subagent handed a task runs tasqx show <id> --card itself instead of receiving the card pasted into its brief.

Both tools answer the rendered view and nothing else. The machine-readable JSON block is the same result a second time, so it is sent only when you ask for it with include_json: true — worth doing when a script parses the answer, and a waste of the response budget when an agent is going to read it.

A few more places the response is shaped for the reader that is actually paying for it:

• tasqx_list_tasks answers a compact row by default — short_id, title, status, priority, urgency, blocked, due, project, tags — with any null key omitted; an explicit fields list, [] included, returns the engine's own full row.
• tasqx_complete_task refuses a task with open blockers and names them; force: true completes it anyway, and the override is recorded and counted in tasqx_outcomes. Pass view: "card" when a person has to decide on the outcome: the answer then leads with the box card of the task as completed, so no tasqx_get_task re-read is needed. A routine completion leaves it out and prints the one ✔ line above.
• A long annotation body is cut in a tasqx_get_task/tasqx_brief_task response with a marker naming its real size; max_body_bytes raises the cap, and a removed annotation is listed as a tombstone rather than disappearing from the count.
• tasqx_brief_task holds half its memory page for knowledge docs (from memory add / memory import), so a ruling is not buried under a project's own, more numerous, task annotations.
• tasqx_brief_task pages the task's annotations the way tasqx_get_task does: the newest 20 by default, annotations_limit and annotations_offset to choose another page. A brief over the response budget drops memory hits first, then older annotations, and the view names the annotations_offset that reads the rest.

Why the tool descriptions are short

Every tool description states its contract — what the call does, what it returns, and the one rule you need to call it right — and cites a D-number when a design decision is behind that rule. The reasoning is in DESIGN.md §12 under that number, and tasqx_search_memory finds it once the repository's docs have been imported with tasqx memory import. The descriptions are short because most clients inject the whole roster into every request, a few thousand tokens on every prompt.

A few facts the short descriptions no longer spell out, that you may still want to act on:

• annotations_limit and include_json spend the same budget. A tasqx_get_task response is fitted to a byte budget, and the machine-readable JSON block is charged first. A big annotation page together with include_json: true therefore buys less history than the page you asked for.
• budget_tokens stops nothing. tasqx is called between turns and cannot interrupt one. It counts fresh tokens only — input, output and cache creation, never cache reads — so a task that blows its budget is a signal it was too large to hand over whole, not an error.
• tasqx_start_timer takes actor and keep. Each MCP connection gets its own actor id, and starting a task while a different actor holds a running clock is refused rather than silently stopping their timer. Pass keep: true to run both deliberately — which is what several agents working in parallel need.
• tasqx_claim_task is how parallel agents stay off each other's work. A claim is a lease, 30 minutes unless lease names another length and at most 24 hours, held by the connection (or the actor you name). While it is live the task leaves every other connection's @working and tasqx_next, their tasqx_stop_timer, tasqx_complete_task and tasqx_cancel_task on it need force_claim, and their tasqx_start_timer on it is refused naming the holder and the expiry. Claim again to renew; tasqx_release_task, completing or cancelling gives it up; an expired lease is anyone's. Claim before you start when more than one agent works the same store. The connection id changes when the server restarts, so an agent that may reconnect should pass its own stable actor (its session id) to claim, start, complete, cancel and release; a claim stranded by a dead session is freed by force_claim: true on tasqx_release_task or by its lease running out.
• tasqx_remove_annotation redacts the event too. It overwrites the body in the annotation row and in the original write's audit event, in one transaction, so a secret pasted into a note is also gone from an export. tasqx undo cannot bring it back.
• tasqx_update_annotation corrects a note in place. The id, timestamp and position stay, so a corrected first note is still the card's Description, and memory search stops finding the old sentence. tasqx undo puts the previous text back.
• tasqx_move_annotation moves a note to another task. For a note written on the wrong task: the id, text and timestamp are kept, search follows, and tasqx undo puts it back. tasqx_update_annotation and tasqx_remove_annotation take the note's full id, a unique prefix of eight or more characters, or its 1-based position on the task.
• Proposals can wait in triage. tasqx_add_task with status: "triage" files a task outside @working, next and the urgency ranking, so work an agent discovers mid-task does not compete with the planned backlog; discovered_from links it to the task it was found on. Set tasqx config set mcp.add_status triage and every MCP add that names no status lands there. tasqx_triage_task (or tasqx accept, decline, duplicate at a shell) settles each one; tasqx triage lists the inbox with the tool that filed each proposal.

The server's instructions block is the short version of how to work, so a fresh install already nudges the agent to search before deciding and to write as it works. The skill in .claude/skills/tasqx-workflow/ — tasqx setup installs it for you, or Claude Code picks it up automatically inside the tasqx repository — is the fuller version.

For the full workflow — what deserves a backlog entry, searching memory before starting, annotating before completing — see the AI agent guide and the agent starter prompt. For the session-end retrospective that has the agent record what each task taught, see A self-improving agent.

tasqx api

The JSON API without a server: one request envelope in on stdin, one response out on stdout.

echo '{"tasqx":"1","method":"task.list","params":{"filter":"@working"}}' | tasqx api

Method and params go in; a result or an error comes out. Every method the engine has is callable this way — tasqx docs carries the full method table. Exit codes mirror the error model: 0 ok, 2 bad request, 4 not found, 5 conflict, 6 unsupported API version — plus 1 for internal, or for a failure beneath the request such as a store that would not open.

token.add self-reports a turn's token counts against a task — the primary source the TOKENS column reads (tasqx tokens). And tasqx export / tasqx import round-trip the store as canonical JSON.

tasqx daemon

A long-lived server on a local socket (or named pipe on Windows). You don't need it for everyday use — every command works standalone — but it adds three things:

tasqx daemon

1. One writer, many clients. While it runs, ordinary commands automatically route through it, so several agents and terminals can hammer the same store without stepping on each other.
2. Live pushes. Every change is announced to subscribers — that's what tasqx watch listens to.
3. Reminders fire. The daemon is the process that watches the clock; see Dates, Reminders and Recurrence.

Ctrl-C stops it cleanly. --no-daemon on any command skips the routing when you need a command to run strictly in-process.

$TASQX_DB always wins over a daemon on another store. If it names the file the daemon serves, commands route through the daemon as usual. If it names a different file, a daemon found on the default socket is passed over and the command runs in-process against $TASQX_DB. A daemon you named yourself, with --socket or $TASQX_SOCK, that serves a different file is a contradiction: the command is refused with exit 2, naming both files.

otlp.enabled = true (in config.toml) starts a local OTLP/HTTP receiver in the daemon on 127.0.0.1 (otlp.port, default 4318), capturing an AI tool's own token telemetry live instead of parsing its transcript after the fact. For Claude Code:

export CLAUDE_CODE_ENABLE_TELEMETRY=1
export OTEL_LOGS_EXPORTER=otlp
export OTEL_EXPORTER_OTLP_PROTOCOL=http/json
export OTEL_EXPORTER_OTLP_ENDPOINT=http://127.0.0.1:4318

Gemini CLI takes the same two OTEL_EXPORTER_OTLP_* variables, and Codex the [otel] table in ~/.codex/config.toml. The receiver is independent of tokens.enabled: self-reported counts (task.done, token.add) work with both settings off. The token accounting guide has the rest.

tasqx tokens

Maintenance for token accounting — the feature that answers "what did agent work on this backlog actually cost?"

Agents self-report token counts when completing a task (that's the primary channel — only the agent knows which task a conversation served). A log-parsing fallback fills gaps by reading session transcripts, and it refuses to guess: a sample claimed by two tasks' time windows is dropped rather than attributed to the wrong one.

Stop any running daemon before --apply — this one runs strictly in-process.

Where the numbers surface: the task table's TOKENS column, the dashboard's TOKENS panel, and the HTML report's header tiles — always as separate buckets (input, output, cache read, cache creation), never a misleading blended total. A count reported as one number stays one number, shown as total (unsplit). What each confidence grade means, and why a self-report is medium, is in the token accounting guide.

Token accounting

When an agent (or script) drives the CLI instead of MCP, the same reporting travels as flags on start and done:

tasqx start 42 --client 'claude-code 2.1' --session-id $SID
tasqx done 42 --client 'claude-code 2.1' --session-id $SID

--client selects the transcript parser; without these flags no transcript is ever read and the task simply reports zero tokens.

One rule for anything automated

A bare tasqx on what looks like an interactive terminal opens the full-screen dashboard and waits for a key. Harnesses that allocate a pty look interactive. So in scripts and agent tooling, always spell the verb: tasqx list, never bare tasqx.

Import and Export

Your data, in and out, as plain JSON. This is the backup story, the migration story, and the "way back" for anything archived.

Your data is yours. export emits canonical JSON — stable UUIDs, every field, sorted keys — that is git-diffable, greppable, and round-trips exactly.

tasqx export

Dump tasks as canonical JSON to stdout, or to a file with --out.

• tasqx export project:work > work.json: any filter narrows it
• tasqx export --out backup.json: writes the same document to a file, replacing it whole, so an export that fails halfway leaves the previous backup as it was, and prints where it went and what it left out

tasqx export > backup.json
tasqx export project:work > work.json
tasqx export --out backup.json

• The document carries projects, your memory docs, your quick-capture notes, the graph's links and your default-project setting too, so a restore gives back the store, not just its tasks.
• A filtered export that cuts across a dependency (one task in, its prerequisite out) drops that edge and says so in the answer (dropped_dependencies), rather than exporting a broken reference. A link (link.add in the API) is kept only when both of its ends are in the document, and the rest are counted under dropped_links for the same reason.
• An unfiltered export carries every project, every memory doc, every link and the event log — the full backup. What it leaves out is what you removed, and each kind is counted (see Checking a restore). The one link it leaves out is one pointing at an annotation you removed: a removed annotation is not in the document, so the edge to it is dropped and counted under dropped_links like any other. Any other filter scopes those four to what the exported tasks actually need, and reports what it left out (dropped_projects, dropped_docs, dropped_notes, dropped_links, dropped_events; notes follow a doc's project rule): sharing tasqx export project:ledger no longer ships every other project's knowledge along with it. A doc that carries no project ships only with --include-unscoped, which is refused on an unfiltered export — there is nothing to widen from. The store's default project is carried only when it is among the projects the filter kept, so a filtered export whose scope drops it comes back with no default rather than a document tasqx import would refuse.

tasqx export project:work --include-unscoped > work-and-global.json

With no filter you get everything. With a filter you get a slice. Human output is the JSON document — there is no separate pretty mode to drift from it.

tasqx export +api

{
  "default_project": "work",
  "docs": [],
  "dropped_dependencies": 0,
  "dropped_docs": 0,
  "dropped_events": 0,
  "dropped_links": 0,
  "dropped_notes": 0,
  "dropped_projects": 0,
  "events": [ ... ],
  "links": [],
  "notes": [],
  "projects": [ ... ],
  "tasks": [
    {
      "_rev": 4,
      "annotations": [
        {
          "body": "Blocked on the D12 decision",
          "created": "2026-07-16T08:51:09.6830568Z",
          "id": "019f6a1f-62f3-75f0-bf57-e5ff9c7c452a"
        }
      ],
      "completed": null,
      "created": "2026-07-16T08:51:09.2509427Z",
      "depends_on": [],
      "due": "2026-07-17T00:00:00Z",
      "estimate": "PT4H",
      "id": "019f6a1f-6142-70d3-be5b-e28dc6060e6c",
      "modified": "2026-07-16T08:51:09.6830568Z",
      "priority": "H",
      "project": "work.tasqx",
      "recurrence": null,
      "remind": null,
      "scheduled": null,
      "short_id": 1,
      "status": "pending",
      "tags": [
        "api",
        "release"
      ],
      "title": "Ship the v1 JSON API freeze",
      "urgency": 17.5,
      "wait": null
    }
  ]
}

Filtered exports and dependency edges

A filter selects a subset, so a dependency pointing out of that subset cannot travel with it — the target is not in the document. Those edges are trimmed, and you are told, on stderr:

tasqx export +docs > slice.json

note: 1 dependency points outside the export, left out — widen the filter to keep it

The --json form reports the same thing as data — dropped_dependencies is always present, and is 0 for an unfiltered export:

tasqx export +api --json

{
  "default_project": "work",
  "docs": [ ... ],
  "dropped_dependencies": 0,
  "projects": [ ... ],
  "tasks": [ ... ]
}

What a document carries

An export is a self-contained document, and a project is part of it: the projects array carries every project row — name, description, archived state, identity — and default_project names the project a bare tasqx add inherits. So are your memory docs: the docs array carries every knowledge document, all of them regardless of any filter — a filter selects tasks, and knowledge is not attached to a task. Restoring gives you back the store you exported, not just its tasks. These sections are optional on import, so a file written by an older tasqx still restores: with no projects section there is nothing to check a task’s project against, so the row is created from the tasks and import says which ones it made. With one, the document is authoritative — a task naming a project it does not define is refused, exactly as tasqx add refuses a --project no init ever created.

tasqx import

Load tasks from a JSON file, or from stdin with -.

• tasqx export | tasqx import -: round-trip

tasqx import backup.json
tasqx export | tasqx import -

Takes a file, or - for stdin. It accepts either the document export prints or a bare array of tasks (which is what every older export wrote). Import is an upsert on the UUID — re-importing the same document is a no-op, not a duplicate.

tasqx import slice.json

imported   2 tasks · 1 project · 3 memory docs

tasqx export +api | TASQX_DB=/tmp/other.db tasqx import -

imported   1 task · 1 project · no memory docs

A task whose number is already taken by a different task in this store keeps its id and gets the next free number instead of refusing the import; every move is listed under renumbered, with the number it came in as and the one it took. Dependencies, annotations and checks follow the id, so nothing breaks — but a branch name or a #n written down somewhere still points at the old number. A task this store already holds keeps the number it has here, so importing the same document twice changes nothing.

A memory doc whose source a different doc in this store already holds is the same doc under two ids — which is what two machines that each imported the same docs/ folder end up with — so it merges onto the doc already here instead of refusing the import. The stored id is kept, the payload's is dropped, and the later modified wins the text; a payload no newer than the copy here leaves it untouched. Every merge is listed under docs_merged, with the source, the kept id, the copy that won, and the dropped id — null when the payload document carried no id of its own — and links pointing at the dropped id follow the doc that kept the source.

Links come in last, after everything they point at, and are counted under links_imported. Both ends are resolved against what this store holds after the import — a project it already knew keeps its own row, and the link follows it there. A link naming an end that is neither in the document nor already here refuses the whole import, naming the link and the missing end, rather than restoring an edge nothing can see.

The export document also records each project's archived flag, and importing restores it. To un-archive a project directly, use tasqx unarchive.

A project this store already knows keeps its own description when it has one: projects carry no modified stamp the way a task does, so there is no later-wins comparison to make, only a present-vs-absent one. A non-empty local description always wins over the payload's, which is dropped and reported under project_description_conflicts; a local description that is empty, or a project this store has never seen, takes the payload's.

imported   no tasks · 1 project · no memory docs
note: project "api" kept its description here; the import's was "B's api description"

tasqx import backup.json --dry-run runs the whole import against this store and rolls it back instead of keeping it: every renumbering, merge and refusal prints exactly as a real import would, and the run ends with nothing was written. There is no separate preview logic — it is the same import, undone.

tasqx import backup.json --dry-run

tasqx import other.json --merge folds a second live store into this one instead of restoring over it. A task the document carries and this store has never seen is imported exactly as it would be without the flag. For a task this store already holds:

• The annotations, checks, tags and dependency edges written on either side are unioned — nothing written on either side is thrown away.
• A field that can only have one value (title, status, priority, project, the dates) is taken from whichever side changed that field last, going by each side's history, so a task completed here and retitled there comes back completed and retitled. Status travels with its completion time, and the four dates travel together.
• Tracked time adds up: the time the other store logged since the two last met joins the total here instead of replacing it, and importing the same document again adds nothing.
• The _rev check is skipped, because two stores count their own revisions and neither number means anything to the other.
• One line per task names each field that differed and the side it came from, and how much tracked time arrived.

A note or a check both sides hold under the same id stays one row: a check follows its own last edit, so a passed recorded here is not rolled back by a copy that never saw it pass, and a note follows the task's. A memory doc both stores hold under the same id keeps the copy with the later modified, whatever its _rev; a tie keeps the one here.

Removals travel too. A tag, check, note, dependency edge, link or memory doc removed on one machine stays removed when that machine merges the other's older copy, and is removed on the other machine when it merges this one. Each side's history decides: a removal counts when it is later than the last time the row was added or changed, so a tag added back after it was removed elsewhere stays. A removed note is scrubbed on the other machine the same way tasqx unannotate scrubs it here: its text leaves the file.

Without --merge, the document stays authoritative about a task it names: its notes, checks, tags and edges replace what is here. That is what a restore should do, so it stays the default.

Either way, a note or a check id the document hands to one task while a different task here already holds it refuses the whole import, naming both tasks: one note, and one criterion, belongs to exactly one task.

A recurring task completed on both machines spawned its next occurrence on each, under two different ids. When an import finds two tasks with the same predecessor and the same due and scheduled dates, with or without --merge, they fold into the older one: it takes the other's notes, checks, tags and dependency edges, the status of whichever copy was started, stopped or finished last, and the tracked time of both, and the other copy is deleted. Each fold prints one line, for example note: occurrence #12 duplicated #9 (both spawned from #4); kept #9, and is listed under deduplicated. Both machines keep the same copy with the same contents, so importing in the other direction, or the same file twice, ends in the same place. If the two copies were wired into opposite ends of one dependency chain, the survivor's edge that would close the loop is dropped and the note names it. Completing a task again after reopening it does not spawn a second next occurrence for the same date.

A field the schema does not name is rejected

A task object may carry only the keys the schema names, and nothing else (the site's page lists them, generated from the code; tasqx docs opens it):

id, short_id, title, status, priority, project, tags, due, scheduled, wait, estimate, recurrence, remind, depends_on, annotations, tokens, urgency, created, modified, completed, _rev, status_unrecognized, tracked_seconds, tracked_adjustment_seconds, budget_tokens, active_since, checks, delivered_annotation_id, spawned_from, claimed_by, claim_expires, git_refs

An annotation may carry id, body, created. A key outside that set is a bad_request naming the task and the field, because the alternative is worse than an error: a misspelled tags used to import as ok with the tags silently gone, so the report said your data arrived when it had not.

error [bad_request]: store.import: task 019f6a0f-99df-…, unknown task field `tag`
  (accepted: id, short_id, title, …) — check the spelling or drop it; it was silently
  ignored before, so the import reported success and the value never arrived

Two of those keys are accepted and deliberately ignored: urgency is recomputed on the way in (it is derived from priority, due date and age, so a supplied value could contradict the ranking rule) and status_unrecognized is a read-side flag rather than stored state. They are listed because export emits them and a round trip has to keep working.

A dangling edge is rejected, not repaired

A dependency target must be in the payload or already in the store. Anything else fails with bad_request naming the id — and because the whole import is one transaction, a rejection writes nothing.

error [bad_request]: store.import: task 019f6a0f-99df-… depends on 019f6a0f-99b5-…,
  which is neither in the payload nor in the store (export the dependency too, or drop the edge)

That is a deliberate choice. An edge to an unknown id means the wrong slice was exported; repairing it quietly would hide exactly the mistake worth seeing. Payload order does not matter — tasks are written first, edges second, so a forward reference is fine.

Checking a restore

A store exported and imported into an empty one comes back with every task, project, memory doc, quick-capture note, link, check, tag, dependency, timer and task annotation, and the event history behind them. Counted straight from the database, three numbers still differ, on purpose, and tasqx export --out backup.json names each one under the path it wrote (--json gives the counts as fields):

Wrote 240 tasks → /home/me/backup.json
Left out: 3 removed notes, 12 events earlier imports logged about themselves

• removed_annotations: notes you removed. Removing a note scrubs its text and keeps an empty row; that row stays behind, and the record of the removal travels in the event log.
• dropped_events: on an unfiltered export, the history of a memory doc you removed, apart from the removal itself, because it names the title the removal took away. This one is also in the document.
• skipped_events: the entries an earlier import wrote about itself.

The import adds entries of its own, one per task, project and doc it brought in, reported as events_logged beside events_imported. So the store's event log is the document's events plus dropped_events and skipped_events, and the restored one holds events_imported plus events_logged.

The simplest check is to export the restored store and compare: the document is the same, apart from dropped_events and each task's urgency, which is scored when the export runs.

tasqx export --out before.json
tasqx import before.json
tasqx export --out after.json

Run the import and the second export against the new store.

Merging two machines

Each machine exports, and each imports the other's document. Rehearse with --dry-run first — it prints the same report and keeps nothing.

On machine A:

tasqx export > a.json

Copy a.json to machine B, then there:

tasqx import a.json --merge --dry-run
tasqx import a.json --merge
tasqx export > b.json

Copy b.json back to machine A and do the reverse:

tasqx import b.json --merge --dry-run
tasqx import b.json --merge

Both stores now hold both sides' work.

tasqx sync

The same merge, without carrying files around: each machine syncs with one shared remote. See Syncing Between Machines for setup, what merges and wins, secrets and headless use.

Recipes

Good habits

A dated backup, in one line:

tasqx export --out "backup-$(date +%F).json"

The store itself is a single SQLite file (tasqx config store prints its path), so file-level backups work too — but the JSON export is human-readable, diff-able, and version-control friendly.

Syncing Between Machines

Your tasks live in a single SQLite file on the machine you're on — see Import and Export. Sync is how a second machine gets the same store without you carrying a file around: each machine keeps its own copy, both agree on one shared remote, and tasqx sync merges the two through it. It is local-first — every machine works offline and merges when it next syncs — never a shared live database, and each store has at most one remote.

The no-account start: a shared folder

The simplest remote is a folder every machine can already reach: a dedicated folder inside your Dropbox, iCloud Drive or Syncthing share — not the one your other files live in, so nothing else in it collides with tasqx's own files. tasqx-remote-dir keeps the snapshot there.

tasqx sync setup dir --set path="$HOME/Dropbox/tasqx-sync"
tasqx sync

Nothing to sign up for: the folder's own sync client (Dropbox, iCloud Drive, Syncthing) is what moves the bytes between machines: tasqx sync on one machine writes into the folder, and the next tasqx sync on the other reads it back once that client has caught up. When two machines write near the same moment, the folder's client can leave more than one copy of the current snapshot behind — a "conflicted copy" file, a HEAD 2, a .sync-conflict-… name, depending on which client it is. tasqx-remote-dir recognises all three shapes, hands every one of them back on the next pull beside the real one, and a push that merges them removes exactly the ones it merged — so a conflict from the folder client heals itself on the next sync instead of piling up.

Cloudflare R2, step by step

R2 is the other connector, tasqx-remote-r2: one object in an R2 bucket instead of a folder, for when there's no shared folder to reuse.

1. Create a bucket. In the Cloudflare dashboard, under R2, create a bucket. tasqx does not create it for you.

2. Create an API token scoped to that one bucket. Under R2 > Manage API tokens, create a token with Object Read & Write permission, scoped to the bucket from step 1 and nothing wider. Copy its Access Key ID and Secret Access Key — the secret is shown once.

3. Find your account ID. It's on the R2 overview page: 32 hexadecimal characters.

4. Run setup:

   $Copy

   tasqx sync setup r2

   You'll be asked for the account ID, the bucket, the Access Key ID and the Secret Access Key (masked, not echoed), and an object key — leave it empty and it defaults to tasqx/snapshot.tqx inside the bucket.

5. The passphrase. Every setup, whichever connector, ends by asking for a sync passphrase twice. This is what encrypts the snapshot before either connector ever sees it — the folder or the bucket holds ciphertext, never your tasks in the clear. Give every machine that syncs with this remote the same passphrase. Lose it and the remote's snapshots cannot be read by anyone, on any machine — each machine's own store is untouched, but there is nothing to recover the remote from. It's kept in a file beside your store, readable by you alone; it is never sent anywhere.

Repeat tasqx sync setup r2 with the same account/bucket/token and the same passphrase on every other machine that should join this remote.

config edit's Sync section

tasqx config edit shows a Sync section below the settings: the connector in use, the last version synced and how long ago, and whether a passphrase is set up.

• c — connect: lists the tasqx-remote-* connectors found on your PATH, and once you pick one, shows its fields as a form (label, help text, a masked field for a secret), then the passphrase twice. This is the same write tasqx sync setup makes — there's exactly one way "set up" happens either screen uses.
• s — sync now: runs the same sync tasqx sync runs and reports one line.
• d — disconnect: after a confirmation, removes this store's sync setup (the connector record and the passphrase file). The remote itself is untouched — another machine still synced to it keeps working.

tasqx sync

tasqx sync
tasqx sync --status

tasqx sync pulls every snapshot the remote holds, merges each one into this store exactly the way tasqx import --merge does (see Import and Export), then exports and pushes the result back. If another machine pushed in between, it merges that too and tries again, three times at most; failing on the third names it a conflict and says to run tasqx sync again (exit code 5, conflict, so a script can retry on it) — nothing already merged is lost, since merging is idempotent. When the remote already holds exactly this store (nothing changed on either side), nothing is pushed. Sync has no MCP tool: it runs in your shell, not from an agent session.

tasqx sync --status prints the connector, the last version synced (eight characters) and when (today, 2d ago, never synced, or not set up before the first setup).

What merges, and what wins

The same rules tasqx import --merge applies (see Import and Export for the full account):

• A field that can only hold one value — title, status, priority, project, the dates — is taken from whichever side changed that field last.
• Notes, checks, tags and dependency edges are unioned: nothing either side wrote is thrown away.
• Tracked time adds up across both stores' histories.
• Removals travel: a tag, check, note, edge, link or memory doc removed on one machine stays removed once its later history reaches the other.
• A recurring task completed on two machines, which each spawned its own next occurrence, folds the two duplicates into one.

Secrets

A connector's secret fields (an R2 Secret Access Key, for instance) are never accepted on the command line: sync setup --set refuses a field the connector marks secret, since argv lands in shell history and ps. Give it at the no-echo prompt, or set TASQX_SYNC_<KEY> (the field's key, upper-cased, with anything that isn't a letter or a digit turned into _ — secret_access_key becomes TASQX_SYNC_SECRET_ACCESS_KEY) when there's no terminal to prompt at. tasqx sync setup reads it once and hands it straight to the connector; it is never stored by tasqx itself. tasqx-remote-r2 keeps its own copy of the secret in the OS keyring, not in a file.

Headless machines and CI

Off a terminal, every setup field must come from --set (a missing one is refused, naming it) or the environment — a secret field still cannot come from --set. For tasqx-remote-r2 specifically, TASQX_R2_SECRET_ACCESS_KEY answers the Secret Access Key without a keyring, which a headless box may not have. TASQX_R2_ENDPOINT replaces the default https://<account_id>.r2.cloudflarestorage.com for a bucket in a jurisdiction, such as https://<account_id>.eu.r2.cloudflarestorage.com for the EU. The sync passphrase itself, needed by sync setup and read again by every later sync, comes from TASQX_SYNC_PASSPHRASE.

TASQX_R2_SECRET_ACCESS_KEY=... TASQX_SYNC_PASSPHRASE=... \
  tasqx sync setup r2 --set account_id=... --set bucket=tasqx \
    --set access_key_id=... --set object_key=
TASQX_SYNC_PASSPHRASE=... tasqx sync

Limits

• One remote per store. Two stores on one machine (a second $TASQX_DB, or a scratch store) sync to their own remotes and never see each other's setup.

• No background sync. tasqx sync runs once and returns; nothing polls or watches a remote on its own. Schedule it yourself — cron on Linux/macOS, Task Scheduler on Windows:

  $Copy

  # crontab -e — sync every 15 minutes
  */15 * * * * TASQX_SYNC_PASSPHRASE=... /usr/local/bin/tasqx sync >>~/tasqx-sync.log 2>&1

  $Copy

  schtasks /create /tn "tasqx sync" /sc minute /mo 15 /tr "tasqx sync"

• A running daemon is fine. tasqx sync is a client of the same dispatch every other command uses, so with tasqx daemon running its merges go through the daemon like any other write instead of opening the store beside it.

Settings and Themes

Settings live in a TOML file, but you never have to hand-edit it — every read and write goes through a command, and there's a full-screen editor with live theme preview.

Default output should be something you want to look at. Themes drive the terminal and the HTML report from the same palette, and degrade honestly when the terminal cannot keep up.

tasqx config

Worth knowing:

• Resolution order is: command-line flag, then $TASQX_* environment variable, then config.toml, then the built-in default. config list's SOURCE column names the layer that won, so "why is this setting on?" has a lookup, not a hunt.
• config edit opens an interactive screen — arrow through themes and watch the whole screen repaint in each one before anything is written. It needs a real terminal; scripts use set/unset.
• config store answers which SQLite file a command would actually write to, and why: through a running daemon, or in-process — including the case where your $TASQX_DB names a different file than the daemon serves, so the daemon was passed over.

Every setting

tasqx config list prints these with their live value and source.

tasqx theme

Built-ins: nord, gruvbox, dracula, solarized, mono — plus any theme file you drop in yourself. A one-off try is tasqx --theme dracula list, and $TASQX_THEME sets it per environment.

Themes

tasqx theme list

  THEME
* nord
  gruvbox
  dracula
  solarized
  mono

The * marks the theme in effect. tasqx theme show [name] previews every role, a sample drawn in it beside its colour and emphasis, plus the urgency ramp's bands, rendered at your terminal's real capability. Set one permanently:

# config.toml
[theme]
name = "gruvbox"

Drop a .toml in $TASQX_CONFIG_DIR/themes/ and it appears in theme list alongside the built-ins.

Four environment variables override the detection:

Shell Completion

Tab completion for bash, zsh, fish, elvish and PowerShell — the same five shells on Linux, macOS and Windows. It completes more than most tools: verbs, flags, value sets, file paths, your actual task ids, project and tag names, the capture sugar (+tag, project:x, !high) and the whole filter grammar.

tasqx completions

Completion isn't on after install unless Homebrew installed tasqx. Turn it on by adding one line to your shell's startup file. tasqx completions <shell> prints that line, so for bash this is the whole setup:

tasqx completions bash >> ~/.bashrc

tasqx never edits the file itself. With no shell named, it reads $SHELL. This is where each line belongs.

bash, in ~/.bashrc:

source <(TASQX_COMPLETE=bash tasqx)

zsh, in ~/.zshrc, after your compinit line:

source <(TASQX_COMPLETE=zsh tasqx)

fish, in ~/.config/fish/completions/tasqx.fish:

TASQX_COMPLETE=fish tasqx | source

elvish, in ~/.elvish/rc.elv:

eval (E:TASQX_COMPLETE=elvish tasqx | slurp)

PowerShell, in $PROFILE:

$env:TASQX_COMPLETE = "powershell"; tasqx | Out-String | Invoke-Expression; Remove-Item Env:\TASQX_COMPLETE

Platform notes

zsh: the line must come after compinit runs. Earlier, zsh prints command not found: compdef, registers nothing, and carries on at exit 0. oh-my-zsh and prezto run compinit for you; a hand-written .zshrc may not.

Windows: no Windows shell sets $SHELL, so name the shell, and let PowerShell expand its own profile path — $PROFILE is a PowerShell variable, not an environment variable, and it differs between Windows PowerShell 5.1, PowerShell 7 and the ISE:

tasqx completions powershell >> $PROFILE

And PowerShell must be allowed to run your profile at all: a stock Windows client ships with execution policy Restricted, which silently never runs it. Get-ExecutionPolicy tells you; Set-ExecutionPolicy -Scope CurrentUser RemoteSigned is the minimum that does.

cmd.exe can't be completed by any program (that's cmd, not tasqx), and nushell completes external commands through its own mechanism that tasqx can't activate yet. Any other shell is refused, naming the five above.

How it behaves

• Task ids come with their titles in zsh, fish and PowerShell (bash and elvish can only show bare ids — their completion protocol has nowhere to put a title; that is upstream's protocol, not a tasqx setting).
• The id menu shows every task by urgency, not just open ones — reopen and why need the closed ones.
• An alias only surfaces when no canonical name claims the prefix: ls<TAB> gives ls, mod<TAB> gives modify.

Before you switch it on

The activation variable is TASQX_COMPLETE, deliberately not the generic COMPLETE that clap tools usually take. The protocol cannot tell a callback from a real command: with a recognised shell name in that variable, tasqx add -- "a real task" writes nothing, exits 0, and does not add the task. A tasqx-specific name makes that state improbable rather than impossible, so do not export it by hand. COMPLETE on its own does nothing to tasqx.

A Tab press READS your store — through a running daemon if there is one, otherwise the SQLite file opened read-only — inside a 150 ms budget. If anything fails, you get no candidates rather than an error smeared across the line you're typing. That read leaves tasks.db-shm and tasks.db-wal beside your store: SQLite's doing, and an ordinary tasqx list creates the same two and removes them again. Your database is never altered by a Tab press — no migration, not a byte. TASQX_NO_COMPLETE_LOOKUP=1 turns the store lookups off; verbs, flags and value sets still complete.

Feature development with tasqx

The pattern: one sub-project per feature, tasks ordered by dependencies, context in annotations. It replaces a board for solo work — the dependency graph does the sprint grooming for you.

Set up the feature

A feature is a sub-project under your product, named with a dot:

• tasqx init myapp: once, for the product
• tasqx init myapp.checkout: the feature

tasqx init myapp
tasqx init myapp.checkout

Capture the work, then wire the order. A task with an unresolved dependency is blocked and stays out of your working set until its turn comes:

• tasqx dep 2 1: #2 waits for #1
• tasqx dep 3 2: #3 waits for #2

tasqx add "Design the checkout data model" project:myapp.checkout !high est:4h
tasqx add "Implement cart-to-order endpoint" project:myapp.checkout !high est:6h
tasqx add "Payment provider integration" project:myapp.checkout est:1d
tasqx dep 2 1
tasqx dep 3 2

Put the context on the task

Annotations are stored verbatim — newlines, markdown, code blocks and all. This is where acceptance criteria, links and implementation notes live:

tasqx annotate 2 '## Acceptance criteria
- [ ] POST /api/orders returns 201 + order id
- [ ] Prices recomputed server-side; client prices are a hint, never truth
- [ ] Idempotency-key header prevents duplicate orders on retry

See ADR-012 for the locking decision.'

tasqx show 2 prints it back, unmangled.

Work it, one task at a time

• tasqx next: the single highest-urgency unblocked task
• tasqx done 1: prints #2 unblocked - <title> under the done line for each task it released

tasqx next
tasqx start 1
tasqx done 1

If your pull requests follow the task/<id>-<slug> branch naming, tasqx git event, called from a CI step, a hook or a script, can start and complete the task when the PR opens and merges (a merge completes it only when every check passed and nothing blocks it); see Working on Tasks. Moving to another machine? See Syncing Between Machines.

done announces what its completion released — you never have to work out what is next by hand. tasqx list project:myapp.checkout shows the whole feature; tasqx report project:myapp.checkout totals the feature's estimates — done work included, since a plain report skips only cancelled tasks. Name a status when you want less: tasqx report "project:myapp.checkout status:pending" totals what you have not started yet.

Where this stops

tasqx is single-user and local. There are no sprints, and tasqx claim keeps agents off the same task but assigns nothing to a person. The moment a second person needs to work the same backlog, you have outgrown this pattern.

Personal task management with tasqx

The capture-everything, trust-the-list workflow. The design goal: adding a task is one line with no ceremony, and the list you look at shows only what is actionable now.

Capture without friction

Everything after add is the title, except the parts tasqx recognises as structure:

tasqx add Buy milk
tasqx add "Renew passport due:friday !high +errands"
tasqx add "Water the plants" repeat:"every 3 days"
tasqx add "Call the dentist due:tomorrow remind:-1h"

Dates take natural language — tomorrow, friday 17:00, in 3 days, eom — and reminders anchor to the due date, so when the due date moves, the reminder moves with it.

Not sure it is a task yet? tasqx note "read the RFC about retries" captures it outside your list, and tasqx notes shows them later; see Notes.

Look only at what matters

tasqx list is the working set: pending and active tasks that are not blocked, hottest first. (A bare tasqx opens the dashboard on a terminal, and prints this same table everywhere else — in a pipe, a redirect, or under --json.) Urgency is computed from priority, due proximity and age — and tasqx why 42 shows the arithmetic, so the ordering is never a mystery.

Things you cannot act on yet stay out of sight until they become actionable:

Defer, don't delete

cancel is not delete: the task stays in the event log and out of your reports' way. There is no destructive path in daily use.

The five-minute weekly review

Standups, reviews and reports

Everything below is a pure read of the same API the CLI uses — reports never mutate.

The morning standup

What you finished, what is in flight, what is stuck:

• tasqx list "status:done completed.after:yesterday": yesterday's output
• tasqx list: today's working set

tasqx list "status:done completed.after:yesterday"
tasqx list
tasqx list "status:pending" --json | jq '[.tasks[] | select(.blocked)]'

The weekly view

Charts render natively in the terminal from the event log — every add, done and cancel was recorded transactionally, so the history is complete by construction, not sampled.

A report you can send someone

tasqx report --html --out review.html

One self-contained file: inline CSS and SVG, no external requests, both light and dark schemes. Open it in a browser, attach it to a mail, drop it in a channel. Five built-in themes (--theme nord, gruvbox, dracula, solarized, mono). It opens with what changed in the last 7 days against the 7 before, then a standup — done yesterday, in progress, blocked and by what, the next five — so it doubles as the notes for the meeting. --since/--until pick another period. Annotation bodies stay out of the file unless you add --with-notes.

Time tracking honesty

tasqx start/stop accumulate tracked time per task, and reports show tracked against estimate per project — which is how you find out your "4h" tasks are 9h tasks before you promise the next deadline.

The retrospective the numbers can carry

tasqx report says what the work cost. --outcomes says how it went:

tasqx report --outcomes project --since -30d

REWORK counts completions that were later reopened. SILENT counts completions nobody annotated — the ones that taught the next session nothing. CALIB is the median tracked-over-estimate ratio, which is the "4h tasks are 9h tasks" sentence above as a number. DROPPED is work that was started and then cancelled. FORCED counts completions that overrode an open blocker with --force. OVER counts completions that went past their token budget, UNPROVEN those that closed with an acceptance check still open or failed, and UNBRIEFED those whose task has no recorded tasqx brief (or memory-carrying tasqx_start_timer); each is read against the completions that could have been one. Reports and Charts has the full column table.

Every rate reads count/n, never a percentage, and the reason is worth a sentence at a standup: 3/12 and 3/3 are the same percentage and very different news. Check the denominator before you act on the number — a rework rate over three completions is not evidence of anything.

Driving tasqx from an AI agent

tasqx ships an MCP server, so an agent reads and mutates your tasks through the same core API your shell uses. No glue code, no scraping --json output.

Wire it up

For Claude Code, Codex CLI and Gemini CLI, one command sets up the server and installs the tasqx-workflow and retro skills for each tool it finds on your PATH:

tasqx setup

It's a checklist screen — Space toggles an item, Enter installs what's ticked, --yes installs everything not yet present without the screen. Run it again later and it shows what's already in place. To wire up only the server by hand:

claude mcp add --scope user tasqx -- tasqx mcp serve --scope write
codex mcp add tasqx -- tasqx mcp serve --scope write
gemini mcp add --scope user tasqx tasqx -- mcp serve --scope write

Any other MCP client takes the same command/args shape:

{
  "mcpServers": {
    "tasqx": {
      "command": "tasqx",
      "args": ["mcp", "serve", "--scope", "write"]
    }
  }
}

Leave off --scope write and the server is read-only: the write tools are not just refused, they are absent from the tool list, so the agent cannot even try. Start read-only; grant write once you have watched what the agent does with read.

Shelling out: always spell the verb

An agent that runs shell commands must write tasqx list, never a bare tasqx.

A bare tasqx opens a full-screen dashboard whenever stdin and stdout are both terminals — and a harness that gives its child a pty (pexpect, node-pty, tmux, docker run -t) satisfies exactly that, however unattended it is. The child then switches to the alternate screen and blocks on a keypress that never comes: measured at 80x24 and 120x40, no exit, no parseable output, and the tool call times out. Setting CI=true does not help, because nothing reads it — the stream check is the whole condition.

Killing it does not undo the screen either: the leave-alternate-screen sequence is never sent, so a harness that reuses one pty runs its next command inside the alternate buffer.

Either of these is enough:

• tasqx list: the verb always means the table
• TASQX_DASHBOARD=false tasqx: switches the screen off for the whole image instead

tasqx list
TASQX_DASHBOARD=false tasqx

The MCP server above is unaffected: it speaks JSON-RPC over pipes, so it is on the non-interactive side by construction.

The loop an agent runs

The tool surface is designed around one loop — work the backlog one task at a time:

1. tasqx_list_tasks with "project:myapp.checkout" — see the feature, blocked tasks marked. The default row is compact — short_id, title, status, priority, urgency, blocked, due, project, tags — so pass fields for any other column, or fields: [] for the whole row.

2. tasqx_brief_task — everything needed before starting, in one call: the task and its annotations, each prerequisite with what that task concluded, what this one blocks, and relevant memory under a query tasqx derives from the task's own title, tags and project. The answer is one content block: tasqx-rendered markdown. That is the intended reading — layout is tasqx's job, so the agent uses it as-is rather than recomposing the detail from JSON — and the detail.time_format config key (iso, relative or both) decides how it writes timestamps. Pass include_json: true when a script needs the raw JSON beside it; it is the same result again, so the agent that reads the markdown is paying twice for it.

   tasqx_get_task is still the right call when you only want the task itself.

3. tasqx_start_timer, do the work, tasqx_complete_task — the completion result names any tasks it unblocked, which is the agent's cue for what to pick up next. Pass the turn's token counts on completion (input_tokens, output_tokens, cache_read_tokens, cache_creation_tokens): the agent is the only party that knows which task the spend served, so self-report is the primary measurement channel — completing without counts earns a tokens_hint in the response saying exactly that. Pass view: "card" when a person will read the outcome: the completion then leads with the box card of the task as completed (Delivered row, checks), so no tasqx_get_task re-read is needed.

4. tasqx_annotate_task — write back what was done, decisions made, anything the next session needs.

tasqx_add_check puts acceptance criteria somewhere a completion can be held to them: an annotation is prose and nothing can ask whether it was met, while a check has a state. tasqx never runs one — the criterion is a claim and the evidence a citation, both stored verbatim — so the agent marks them itself, or names them in checks_passed on completion. Completing with a criterion still open is not refused; it is counted, and tasqx_outcomes reports the count.

tasqx_add_dependency lets the agent decompose a feature itself: capture subtasks with tasqx_add_task, wire the order, then work the chain.

Several agents, proposals and notes

• Claims. With more than one agent on a store, tasqx_claim_task first and tasqx_release_task when done: a claimed task leaves the other agents' next and @working, and @claimed lists what is held. See Working on Tasks.
• Proposals. tasqx config set mcp.add_status triage makes a task an agent adds over MCP without naming a status a proposal that waits for your tasqx triage, accept, decline or duplicate. See Working on Tasks.
• Duplicates. tasqx_add_task returns similar, the open tasks in the same project that read like the new one; look before adding another.
• Notes. tasqx_add_note and its siblings capture a thought that is not yet a task or a memory doc. See Notes.
• Pull requests. A CI step, hook or script that calls tasqx git event starts or completes the task a PR names; tasqx does not watch GitHub itself. See Working on Tasks.
• Stale rulings. A memory hit carries stale_refs, the files and symbols it cites that the checkout no longer has. See Memory.
• Setup. tasqx setup --list shows what is installed and --yes --only retro installs one item without the checklist. See AI Agents and Automation.

Give the agent memory

tasqx memory import docs/ turns a directory of markdown docs — ADRs, runbooks, company patterns — into a searchable knowledge store. tasqx_brief_task consults it for you at the moment you pick a task up; tasqx_search_memory is for consulting it mid-task (both work read-only, deliberately). Imported docs carry no project, which makes them global: a brief scoped to one project still surfaces them, and only another project's notes are held back. The import is not recursive: a directory means its own *.md files, so run it once per folder that holds docs rather than pointing it at the root of a tree. Task annotations are searchable through the same tool, so decisions written down during one task resurface during the next:

1. tasqx_brief_task before touching payment code — the query is derived from the task, so nothing is guessed.
2. Hits come back ranked by words and by meaning, with snippets — docs and past annotations alike, each saying which of the two found it. Half the slots are held for docs, so an imported ruling still reaches the page when a project's own task notes share its words; annotations take the rest. The brief's page defaults to five hits; a caller-named memory_limit widens it.
3. tasqx_search_memory with "payment idempotency" for anything the brief's scope did not reach.
4. After the work, tasqx_add_memory stores what the next session should know.

Read how the last run went

tasqx_outcomes is the other half of measurement: tasqx_summary answers what the work cost, this answers whether it worked. Over the tasks that closed, it reports rework (completions that were later reopened), estimate calibration, token cost, silent completions (no annotation written), abandoned work, token overruns, unproven completions, forced completions (completions that overrode open blockers) and unbriefed completions (a task closed without a tasqx_brief_task, or a tasqx_start_timer that carried memory, ever having read the project's rulings) — each rate beside the n it was computed over, because a rework rate over three completions is not evidence.

tasqx report --outcomes project --since -30d

It is on the read scope, so a read-only agent has it, and it is worth a call before a big piece of work on a project you have touched before: a high silent count means the annotations your next session will search for are not being written, and a high rework count means completions are being called too early. A retrospective (A self-improving agent) that cites these numbers is answering from evidence rather than from its own memory of the session.

Safety properties you get for free

• tasqx_modify_task is optimistic-concurrency-checked: the server pins the task's revision before writing, so if you edited the task in another shell mid-flight the agent gets a conflict and re-reads instead of clobbering. The other writes — complete, tag, annotate, timers, dependencies — take an optional expected_rev but the server does not pin one for you, so without it they are last-write-wins, which is why field edits belong on modify.
• There is deliberately no bulk-delete tool. Cancelling goes through the same reversible, logged path as everything else.
• Every agent action lands in the append-only event log, so tasqx chart and the history are as true for agent work as for yours.

Giving an agent memory in any client

The initialize result carries an instructions field: a condensed form of the block below, so a host that surfaces server instructions — Claude Code and others do — gets the nudge with no setup at all. Paste the block below when your host ignores or truncates instructions, when you want the reasons behind each rule, or to tune the placeholders: the import directory, and cutting the write half for a read-only server.

The block works anywhere the tools do: CLAUDE.md, AGENTS.md, .cursorrules or .cursor/rules/, a Zed rules file, a Codex instructions file, or the system prompt of a bare MCP host. It covers the backlog as well as memory, because the two are one store: an annotation written while working a task is what the next session's search finds. Paste it whole. The searching half works under a read-only server; the storing and tracking halves need tasqx mcp serve --scope write, which Driving tasqx from an AI agent argues you grant after watching a read-only session rather than before — until then the block tells the agent to hand you the text it could not store.

Paste this

## tasqx is your organiser: your backlog and your long-term memory

tasqx holds a backlog of tasks and one searchable index over two things: knowledge
docs, and the annotations written on tasks. Reach it over MCP (`tasqx_*` tools) and,
for the verbs MCP does not carry (`undo`, `memory import`, `report --html`),
the `tasqx` CLI — always spell the verb (`tasqx list`, never a bare `tasqx`, which opens
a full-screen dashboard and hangs a tool call). Use it instead of in-conversation todo
lists and instead of any other memory file.

Reading and writing are equally mandatory — an agent that only searches leaves the
store as empty as it found it. If `tasqx_add_memory` and `tasqx_annotate_task` are
missing from your tool list the server is read-only: say so once, keep searching, and
put what you would have stored into your reply. Never silently drop the write. If no
`tasqx_*` tool responds and the CLI is missing too, say so and track the work in the
conversation — do not pretend it was recorded.

### Search before you decide

Call `tasqx_search_memory` before you:

- resume work, or answer "where were we"
- choose between two designs, libraries, schemas or file layouts
- touch a convention-bearing file (config, CI, migration, public API)
- contradict something that looks deliberate, or answer "why is it built this way"
- assert that something is "how this project does it"

Search first, form the opinion second. Report what you found; if a decision contradicts
a hit, say which one and why.

Query with two or three keywords, not a sentence. Search matches meaning as well as
words, so `sign-in failures` finds a note about "login errors"; each hit's `via` says
whether its words (`lexical`), its meaning (`semantic`) or `both` matched. An entry with
every word ranks above one with only some, so `retry idempotency` and `tokens.css` work
as typed; a hit with only some of the words says `partial: true`, and the result says
`relaxed: true` when one is on the page. `matched` shows the all-words expression that
ran, `matched_any` the any-word one. For an exact name, id or error string, pass
`mode: lexical` to match its characters and nothing else.
Run two searches with different wording before concluding nothing is there; no tool
lists the store, so searching is the only way in. A hit is a snippet, not the document:
read a doc whole with `tasqx_get_memory` on its `id`, and a hit whose `source` reads
`task:#<id>` is an annotation — read that task with `tasqx_get_task` before acting on it.

### Track multi-step work as tasks

A real unit of work — a feature, anything multi-step, anything that could outlive this
session or block something else — goes in the backlog. A question, a single command or
a one-line fix does not; do it and move on.

- One project per repo or initiative. Check `tasqx_list_projects` before
  `tasqx_create_project`; name it after the repo so every session finds the same one.
- Decompose with `tasqx_add_task` (title, project, priority H/M/L, estimate) and order
  the pieces with `tasqx_add_dependency`. Acceptance criteria go in `tasqx_add_check`,
  where something can ask at completion time whether they were met; other context goes
  in an annotation, not the title.
- Pick work from `tasqx_list_tasks` with filter `project:<name> @working`. Blocked and
  waiting tasks are hidden there by design: an empty working set with open tasks means
  everything is blocked, not that the work is gone. The default row is compact — short_id,
  title, status, priority, urgency, blocked, due, project, tags — so pass `fields` for
  any other column, or `fields: []` for the whole row.
- Per task: `tasqx_brief_task` for everything you need before starting — the task, what
  each prerequisite concluded, and relevant memory under a query tasqx derives, so you
  supply no search terms. Then `tasqx_start_timer`, do the work, annotate the outcome,
  and `tasqx_complete_task` naming in `checks_passed` what you actually proved. Its
  `unblocked` result names what to pick up next; pass token counts when you know them.
- Work that became obsolete is cancelled (`tasqx_cancel_task`, or `tasqx cancel <id>`),
  never left open. Nothing in the backlog is hard-deleted.

### Day one: import what already exists

Memory starts empty, and an empty store makes the search rule a no-op — if searches
keep returning nothing, it was never seeded. From the repo root, once per folder that
holds markdown docs:

    tasqx memory import [YOUR DOCS DIRECTORY]

No MCP tool imports; run it in the shell, or ask me to run it. It is non-recursive — a
directory means its own `*.md` files. Re-running replaces docs from the same source
rather than duplicating, keyed on the repo's directory name and each file's path inside
the repo (`clouter/README.md`), so any spelling of the directory finds the same docs and
two repos' files never replace each other.

### Store what the next session needs

Call `tasqx_add_memory` (`title`, `body`, `source`) when a decision is made and we stop
arguing about it, when you learn a convention written down nowhere, when a session ends
with work in flight, and when you get something wrong and find out why. Record the
ruling *and* the why; a ruling without its reason gets reopened. Write for retrieval:
the words a future search will use in the title, the ruling in the first line, the
reasoning under it, and the repo or path in `source`. Do not store what is already a
file in the repo — import it instead — and do not store transcripts, task lists or
progress narration; the backlog and its annotations already hold those.

When an entry turns out to be wrong, retract it rather than filing a correction beside
it: search ranks both with nothing to say which is true. Read it with
`tasqx_get_memory`, then remove it with `tasqx_remove_memory` on that id and add the
corrected entry. Removal is permanent — `tasqx undo` does not cover memory — so remove
only what you have read, and ask first if you did not write it.

### Annotate as the work happens

`tasqx_annotate_task` (`ref`, `body`) stores the body verbatim and indexes it into the
same store `tasqx_search_memory` reads — not bookkeeping, but how the next session finds
this work at all. Annotate the approach when you start, every decision, blocker or
change of direction as it lands, and what was delivered, measured and deliberately
skipped before `tasqx_complete_task`. Only the body is indexed, never the task title, so
name the files, symbols and terms inside the note.

Tune it

One placeholder, in the import command: the directory holding your markdown. Fill it before the first paste — an unfilled import command fails rather than importing something wrong. In a user-level file that applies to every repo, such as ~/.claude/CLAUDE.md, there is no one directory to name; replace the placeholder with the instruction to find the repo's markdown folders and ask before importing them.

Running the server read-only on purpose? Cut the tracking, storing and annotating sections and keep the search half, which works read-only by design. A store the agent only reads is thinner than one it maintains, and still worth the paste.

Import is the bulk load; tasqx_add_memory in a loop is not.

The one way re-importing bites

The source key is the repo's directory name plus the file's path inside the repo, not the path as it was handed in, so the obvious spellings of one directory land on the same document:

tasqx memory import ~/notes        # 1 doc
tasqx memory import ~/notes/       # the same doc, unchanged
tasqx memory import ~/./notes      # the same doc, unchanged

What makes a second document is a key written under another root or by an older build. Import tells you when it sees one: is an older key of the same file as, with the tasqx memory rm <id> that removes the old copy. tasqx_remove_memory does the same over MCP, and tasqx memory search prints the source path with each hit, which is how you spot one the note did not catch.

Where this stops

A pasted prompt is a suggestion the client re-reads at its own discretion, so it will not survive an aggressively compacted context the way a tool description does. In Claude Code the skill at .claude/skills/tasqx-workflow/SKILL.md covers the backlog loop in more depth and loads on demand instead of sitting in context; it carries no trigger list for when to search and no read-only fallback, so keep those two and let the skill do the rest. Read Driving tasqx from an AI agent first for the wiring, the work loop and the safety properties this file assumes you already have.

A self-improving agent: a session-end retrospective

Every completed task is a moment where the agent knows what worked and what did not: the edit it reverted, the command it re-ran twice, the convention it found out the hard way. By the next session all of it is gone, unless something writes it down where tasqx_search_memory can find it again. tasqx gives the agent two ways to do that: a retrospective block on every completion, and an optional skill for a closer look at the end of a session.

This guide assumes tasqx is already wired into your agent over MCP. If it is not, start with Driving tasqx from an AI agent.

The retro block

On a write-scope connection, the result of tasqx_complete_task carries a retro block of about 1 KB. It holds six questions, the routing rules and a retraction step, so any MCP client runs the retro with no hook and no skill installed:

1. Did the user correct or redirect you?
2. Goal versus delivered?
3. Rework?
4. A discovery written down nowhere?
5. Would you redo anything?
6. A procedure others will repeat?

A task that went straight through answers in one line (straight through, nothing to record) and stops. Anything worth keeping goes in a retro: annotation on the task. Each correction from the user becomes a standing: true memory doc; the write-scope instructions tell the agent to store it the moment it lands. Before adding a ruling, the agent searches memory for a doc on the same subject and, if the new one supersedes it, removes the old one with tasqx_remove_memory, so two contradictory docs never stand side by side.

Pass include_retro: false to leave the block out, for a batch of completions that already ran one retro. A read-scope connection cannot complete tasks and never receives the block.

The retro skill

The retro skill is an optional convenience for Claude Code, Codex and Gemini. Nothing triggers it automatically: run /retro at the end of a session, or /retro 123 for one task. It looks at every task the session completed, but only writes about the ones that had rework, an undocumented discovery, a blocked or refused step, or an executor whose result came back wrong. A task that went straight through is named as such and gets no annotation.

For each task that qualifies, the session assembles a small evidence bundle:

1. The task read whole: tasqx_get_task with include_json: false and annotations_limit set to the task's annotations_total. A long history is still cut to the response budget; a non-null annotations_next_offset means there is more, so page until it is null.
2. The executor's final report for that task, verbatim.
3. tasqx_outcomes for the task's project.
4. Two or three lines on anything the planning session itself reworked.

It hands the bundles to a fresh general-purpose agent, not a fork, so the cost does not grow with the length of the session. That agent answers five questions per task (goal versus delivered, rework, discovery, redo, procedure), routes each finding, and writes the retro: annotation. A fact goes to memory after a search shows it is not already there. A prohibition is named to you as a hook candidate; creating the hook is your call. A procedure must pass two gates, procedural and non-obvious, and is promoted to a skill only on its second sighting.

Install it with:

tasqx setup --only retro

The skill text is compiled into tasqx, so each release installs the version that matches it; the source is .claude/skills/retro/SKILL.md in the repository. With Claude Code on your PATH it installs ~/.claude/skills/retro; with Codex or Gemini it also installs ~/.codex/skills/retro and ~/.gemini/skills/retro (--only codex:retro, --only gemini:retro). A SKILL.md that differs from the bundled one, your own edit or an older copy, is kept; tasqx setup --yes --only retro --force replaces it.

What accumulates, and how to read it

The agent finds the first two by itself: both live in the store tasqx_search_memory covers, so the next task on the same code reads last time's annotation (Memory explains the ranking). Candidates are the part you look at. On a second sighting the skill drafts a real SKILL.md, records the path on the candidate and cancels it; list the open ones now and then, and promote one by hand when you already know it recurs.

Other clients

A client without a skills mechanism needs nothing more: the block arrives with every completion. To run the longer procedure there, put the five questions, the scope gate and the routing rules from .claude/skills/retro/SKILL.md into the agent's system prompt, next to the block from Giving an agent memory in any client, and tell it to run them at the end of a session against the same evidence bundle.

Counting AI token spend per task

tasqx attributes AI token usage to the task the spend served — always as four separate buckets (input, output, cache read, cache write), never a blended total: cache-read tokens cost a fraction of fresh ones, so one number would destroy exactly the split a cost report needs. The terminal report's TOKENS column names the largest bucket and its own count (cacheR 13.6M); tasqx report --json and the HTML report carry all four.

Turn it on

tasqx config set tokens.enabled true

That switch lets the daemon parse tool transcripts after a completion — nothing is measured through it without a running daemon (tasqx daemon). Self-reports on completion need no daemon and no switch.

Three channels

Self-report — the primary channel. An agent completing a task over the API or MCP passes what it spent: input_tokens, output_tokens, cache_read_tokens, cache_creation_tokens (any one count is enough) plus an optional tool and model. The agent is the only party that knows which task the spend served; completing without counts earns a tokens_hint saying so.

A harness that reports only one number passes total_tokens instead of the four, never beside them. It is stored as its own kind, shown as total (unsplit), and never split into input and output. A count that arrives after the task was completed goes through tasqx_add_tokens over MCP, or from a shell:

tasqx tokens add 602 --total 37898
tasqx tokens add 602 --in 18400 --out 2600 --tool claude-code

Log-parse — the fallback. Name the calling tool on start/done and the daemon reads the tool's own transcript afterwards:

tasqx done 4 --client "claude-code 2.1" --session-id "$SID" --transcript-path "$TP"

Parsers exist for Claude Code, Codex, Gemini CLI and GitHub Copilot CLI, picked from --client by substring — without it no transcript is ever read.

Telemetry — the opt-in OTLP receiver below. Samples are matched to the task by session id, and beat log-parsing when both are available.

How much to trust a figure

Every measurement carries a confidence. It grades how firmly the tokens are tied to this task, not how precise the counts are: every channel reads per-request figures.

A self-report is medium and can never be high. Only the agent knows which task the spend served, so self-report is the primary channel. But nothing tasqx holds can check the number, and the grade describes how checkable a figure is, not how much the reporter is trusted. A report stays unverifiable however much you trust whoever sent it.

The OTLP receiver

tasqx config set otlp.enabled true makes the daemon listen on 127.0.0.1:4318 (otlp.port to change it) — loopback only, never exposed. Point Claude Code at it with four environment variables:

export CLAUDE_CODE_ENABLE_TELEMETRY=1
export OTEL_LOGS_EXPORTER=otlp
export OTEL_EXPORTER_OTLP_PROTOCOL=http/json
export OTEL_EXPORTER_OTLP_ENDPOINT=http://127.0.0.1:4318

The endpoint is the base URL — the exporter appends /v1/logs itself, which is the path tasqx parses (/v1/metrics is accepted so exporters do not retry, but never parsed). Receiver and exporter are both off by default, so no telemetry moves until you turn on both.

The rules

One task never mixes channels: a self-report is authoritative, and log-parsing stands down for a task the agent already measured. A transcript sample banked by one task is claimed globally — no other task can earn it, whatever its re-read timestamp later says — and a sample falling inside two tasks' windows is contested and banked for no one. Only contest ever removes tokens: a transcript that goes missing or re-reads differently keeps its counts with confidence downgraded to low, never deleted blind.

Budgets: the other direction

Accounting tells you what a task cost once it is over. A budget is the same number read before that:

tasqx add Port the payment adapter --budget-tokens 200000

It counts fresh tokens — input, output and cache creation — and ignores cache reads, because a budget dominated by re-reads measures how often the agent re-read its own context rather than how big the work was. An unsplit total_tokens counts in full: nothing can say how much of it was cache reads, and counting none of it would let an unsplit report hide an overrun. That is not a blend of the four buckets; those stay split everywhere they are reported.

It stops nothing. tasqx is a store an agent calls between turns: it never sees the turn and could not interrupt one. An overrun is a signal, and usually one signal in particular — the task was too big to hand over whole. tasqx report --outcomes counts overruns so you can see which kinds of work keep being cut too large.

Repairing old history

The one verb in the API built to delete measurement rows, so the dry-run default is the safety, not a convenience. It parses transcripts and runs in-process only — a daemon refuses it over the socket; stop the daemon and run tasqx --no-daemon tokens recompute.

Writing a connector

tasqx sync keeps its remote behind an interface, not a library: a connector is a small standalone executable that speaks one JSON protocol on stdin and stdout (DESIGN.md D198). Point it at a database, an object store, an SFTP drop, whatever holds bytes for you — tasqx never links against it, and it never links against tasqx.

The protocol

tasqx runs your executable once per verb. It writes one JSON request to its stdin, reads one JSON reply from its stdout, and judges you by the exit code: 0 is an answer, 2 means "push conflict" and nothing else, anything else is a failure whose stderr is shown to the person running tasqx sync. Every request and every reply carries "protocol": 1 — the version this tasqx speaks; answering with anything else, or nothing, is treated as a protocol mismatch.

These are copied straight from the request and reply types in remote.rs (the crate's remote module) — Request, Description, Field, ConfigureReply, PullReply, Snapshot and PushReply — so a mismatch here is a bug in this page, not a second source of truth.

describe — say who you are and what you need. A real reply, spelled the way tasqx-remote-dir answers it:

{
  "protocol": 1,
  "name": "dir",
  "version": "0.16.0",
  "fields": [
    {
      "key": "path",
      "label": "Folder",
      "secret": false,
      "help": "An existing folder every machine can reach: a network share, or one Dropbox, Syncthing or iCloud Drive keeps in step."
    }
  ]
}

Every field needs a non-empty key and label; keys must be unique. Mark a field secret: true when it's a password or a token — tasqx then masks it while typing and refuses it on sync setup --set's command line.

configure — validate the user's answers (by actually connecting to the remote, typically) and keep whatever you need to pull/push later, in your own state directory (below). A rejection is an answer, not a failure: exit 0 with {"ok": false, "error": "…"}. tasqx stores none of these values itself.

{"protocol": 1, "verb": "configure", "values": {"path": "/mnt/share/tasqx"}}

{"protocol": 1, "ok": true}

pull — write every snapshot the remote holds into out_dir (created for you) and name each file, absolute or relative to out_dir; tasqx refuses a name that resolves outside it. An empty remote answers with an empty list. Normally there is exactly one; a connector may hand back more (a folder connector's conflict copies).

{"protocol": 1, "verb": "pull", "out_dir": "/tmp/tasqx-sync-x1/pull"}

{
  "protocol": 1,
  "snapshots": [{"version": "3f9c2e…", "path": "3f9c2e….tqx"}]
}

push — upload in_path if, and only if, the remote's current version equals expected_version; null means "only if the remote is empty". This is the whole conflict story: a real conditional write (S3-style If-Match/If-None-Match, a database row's own version column, a lock file plus a compare), not read-then-write with a gap in the middle. Losing the race answers {"conflict": true} and exit 2, and changes nothing; the caller pulls, merges, and tries again.

{"protocol": 1, "verb": "push", "in_path": "/tmp/tasqx-sync-x1/push/out.tqx", "expected_version": "3f9c2e…"}

{"protocol": 1, "version": "8a71b0…"}

The blob is opaque. It is always sealed ciphertext by the time your connector sees it — you never need to parse or validate it, only store and hand back exactly the bytes you were given.

On PATH, named tasqx-remote-<name>

Build a binary named tasqx-remote-<name> (.exe on Windows) and put it on PATH, the way git finds git-remote-<scheme>. tasqx sync setup <name> and tasqx config edit's connector picker both find it by searching every directory on PATH for that exact name — on Unix it also has to carry an execute bit, or it's treated as though it weren't there.

State directory

Every call carries TASQX_REMOTE_STATE_DIR in the environment: a directory of your own, created for you before the first call, where you keep whatever configure decided to save. It's scoped per store and per remote name (remotes/<name>/ beside the store file), so two stores never share one, and it's created private to its owner (0700 on Unix) — keep secrets in the OS keyring rather than a file there when you can; the state directory is meant as a fallback, not a vault. tasqx-remote-r2 uses the keyring for its Secret Access Key and only a non-secret config in the state directory; tasqx-remote-dir has nothing secret to keep at all.

Environment rules

You inherit tasqx's environment — HOME, PATH, the keyring's session bus (XDG_RUNTIME_DIR, DBUS_SESSION_BUS_ADDRESS), proxies, CA bundles, SYSTEMROOT on Windows, and any override you define yourself (tasqx-remote-r2's own TASQX_R2_SECRET_ACCESS_KEY) — with one exception: every variable whose name starts with TASQX_SYNC_ is stripped before you're run. Those are tasqx sync's own secrets — the encryption passphrase and the TASQX_SYNC_<KEY> answers to your secret fields — and you're never meant to see them; a secret field's value reaches you exactly once, in the JSON configure request.

Timeouts

The runner kills a call that runs too long: 120 seconds by default, except pull and push, which tasqx sync gives 10 minutes — a multi-megabyte snapshot on a slow link needs the room. Keep your own per-request timeout, if you have one, comfortably under that: tasqx-remote-r2's HTTP timeout is 540 seconds, held there by a unit test that compares it against the runner's constant.

Testing against the conformance suite

The suite every connector is held to lives behind a feature flag in the core crate, not copied into each connector: add it as a dev-dependency with features = ["conformance"], same as both shipped connectors do, and call run on your own built binary.

[dev-dependencies]
tasqx-core = { version = "0.16", features = ["conformance"] }

Then, in a test of your own, import remote::conformance::{self, Setup} off that dev-dependency, build a Setup { program, work_dir, good, bad } — the executable under test, a scratch directory the suite may fill, the values that configure an empty remote, and at least one value set configure must refuse — and call conformance::run(&setup). crates/tasqx-remote-dir/tests/conformance.rs is a real, working copy of exactly that, Setup and all, ready to copy and point at your own binary. Run it the same way any other test runs: cargo test -p tasqx-remote-dir (or your own crate's name). The suite walks describe, configure with both good and bad values, an empty pull, a push-then-pull round trip, and a conflicting push, stopping at the first check that fails and naming it — everything goes through the same Connector runner tasqx itself uses, so a connector that passes is one tasqx can actually drive.

Two reference connectors

Read crates/tasqx-remote-dir/src/main.rs first — the simplest connector that does something real, one setting (a folder path), content-addressed blobs, and its handling of the conflict copies a Dropbox/Syncthing/iCloud client leaves behind. crates/tasqx-remote-r2/src/main.rs is the other shape: a hand-rolled SigV4 signer over a cloud object store, a secret kept in the OS keyring instead of the state directory, and conditional PUT for compare-and-swap. Between the two they cover every decision this page describes in working code.

Every command

Every verb is a thin translation to exactly one core API method: it builds a params object, dispatches, and renders. Add --json to any of them to get the raw API result instead of the table. Each section below is generated from the same command table tasqx <verb> -h prints and from clap's own argument list, so a flag that exists is a row here.

Global flags

These work on every subcommand.

--jsonflagoptional

Print the raw JSON API result instead of the human table.

--theme<name>optional

Override the theme (nord, gruvbox, dracula, solarized, mono, or a user file). Beats $TASQX_THEME and the config.

--socket<addr>optional

Socket / named pipe of a daemon. Overrides $TASQX_SOCK. Refused by api, mcp, chart and report --html, which open the store in-process and cannot honour it (D73).

--no-daemonflagoptional

Never route through a daemon; always run in-process. The escape hatch for scripts.

--help, --versionflagoptional

The source of truth for this page.

The verb table

57 verbs, each with a section below. The method column is the API call the verb makes — that mapping is the whole contract.

Getting started

tasqx next [filter…] [--card [--ascii]] [--holder ID]

tasqx next project:work

tasqx next --card

tasqx next

next    #47  Renew the TLS certificate for api.example.dev
        H ▄▄▄▄ 18.1   infra   due 2d ago   +ops
        tasqx start 47  ·  tasqx why 47

tasqx dashboard [--json] [--panels <LIST>]

tasqx --json dashboard

tasqx dashboard

┌tasqx · 17 open · 1 active · 1 overdue · 1 blocked · 2 triage · 3 done/week───────────────────────────────────────────────────────┐
├──2─ PROJECTS ──────────────────────────────────────────────────┬──1─▸TASKS ──────────────────────────────────────────────────────┤
│  *website 5 open · 36h25/38h                                   │  ▍ infra — 3 open · 1 overdue                                   │
│   api 4 open · 4h15/16h                                        │▸   #47  H ▄▄▄▄ 18.1  Renew the TLS certificate fo…  +ops 2d ago │
│   infra 3 open · 1 overdue · 5h10/15h                          │    #54  M ▄▂▁▁  4.3  Cut build time under five minutes     +ci  │
│   mobile 3 open · 9h50/18h                                     │    #53  M ▄▂▁▁  4.2  Move nightly backups to object sto…  +ops  │
│   home 2 open                                                  │  ▍ website — 4 open                                             │
├──3─ BURNDOWN ──────────────────────────────────────────────────┤  ▶ #48  H ▄▄▄▄ 17.8  Ship the v2 pricing …  +launch 0s          │
│17┤──────────────────────────────────────────────────────────── │    #56  M ▄▄▁▁  6.0  Accessibility pass on the s…  +a11y 28 Sep │
│  │ ·········                                                   │    #57  L ▃▁▁▁  2.0  Replace the carousel on the home pa…  +ui  │
│  │          ·········                                          │    #59  L ▃▁▁▁  2.0  Archive last year's analytics dashboards   │
│  │                   ·········                                 │  ▍ mobile — 3 open                                              │
│  │                            ·········                        │    #49  H ▄▄▄▄ 17.0  Fix token refresh ra…  +bug tomorrow 17:00 │
│  │                                     ·········               │    #52  M ▄▄▃▁  8.6  Dark mode for the settings sc…  +ui 25 Sep │
│  │                                              ·········      │    #60  - ▁▁▁▁  0.1  Investigate flaky checkout test  +bug +ci  │
│ 0┤                                                       ····· │  ▍ api — 3 open                                                 │
│  ┴ 7 days · now 17 · net +1                                    │    #50  H ▄▄▄▄ 15.9  Rate-limit the /search endpoint  +perf Sat │
├──4─ PULSE ─────────────────────────────────────────────────────┤  ⊘ #51  M ▄▄▄▄ 12.2  Write the migration guide for …  +docs Mon │
│done 3 7d · 6 14d · 13 30d                                      │    #55  M ▄▂▁▁  4.0  Add OpenAPI examples for every en…  +docs  │
│cycle 10.0d median · 15.5d last 14d, slower                     │  ▍ home — 2 open                                                │
│oldest #58 38d · 8 untouched ≥14d                               │    #58  L ▄▄▄▁  9.4  Book the dentist                       Tue │
│scope -1 over the window                                        │    #61  - ▁▁▁▁  0.4  Sketch ideas for the Q4 offsite            │
├──5─ EFFORT ────────────────────────────────────────────────────┤                                                                 │
│48h est left · 0s tracked on it                                 │                                                                 │
│website              ▄▄▄▄▄▄▄▄ 14h                               │                                                                 │
│mobile               ▄▄▄▄▄▄▄▁ 12h                               │                                                                 │
│api                  ▄▄▄▄▄▄▄▁ 12h                               │                                                                 │
│infra                ▄▄▄▄▄▄▁▁ 10h                               │                                                                 │
│                                                                │                                                                 │
│                                                                │                                                                 │
│                                                                │                                                                 │
│                                                                │                                                                 │
│                                                                │                                                                 │
│                                                                │                                                                 │
└────────────────────────────────────────────────────────────────┴─────────────────────────────────────────────────────────────────┘
 1-6 panel   tab cycle   j/k move   g/G ends   r refresh   R auto   w window   enter open   p pick   l list   ? help   q close   

tasqx pick [filter…] [--holder ID]

tasqx pick project:work +api

tasqx pick

 pick   @working   14 tasks · 1 overdue · 1 due today · ▶ #48 running

       ID          URG  TASK                                           PROJECT  DUE             TAGS
 ▸     47  H ▄▄▄▄ 18.1  Renew the TLS certificate for api.example.dev  infra    2d ago          +ops
   ▶   48  H ▄▄▄▄ 17.8  Ship the v2 pricing page                       website  today 17:00     +launch
       49  H ▄▄▄▄ 17.0  Fix token refresh race on Android              mobile   tomorrow 17:00  +bug
       50  H ▄▄▄▄ 15.9  Rate-limit the /search endpoint                api      Sat             +perf
       58  L ▄▄▄▁  9.4  Book the dentist                               home     Tue
       52  M ▄▄▃▁  8.6  Dark mode for the settings screen              mobile   25 Sep          +ui
       56  M ▄▄▁▁  6.0  Accessibility pass on the signup flow          website  28 Sep          +a11y
       54  M ▄▂▁▁  4.3  Cut build time under five minutes              infra                    +ci
       53  M ▄▂▁▁  4.2  Move nightly backups to object storage         infra                    +ops
       55  M ▄▂▁▁  4.0  Add OpenAPI examples for every endpoint        api                      +docs
       57  L ▃▁▁▁  2.0  Replace the carousel on the home page          website                  +ui
       59  L ▃▁▁▁  2.0  Archive last year's analytics dashboards       website
       61  - ▁▁▁▁  0.4  Sketch ideas for the Q4 offsite                home
       60  - ▁▁▁▁  0.1  Investigate flaky checkout test                mobile                   +bug +ci






















 j/k move   / search   enter open   s start   g/G ends   q leave   

tasqx config <list|get <key>|describe <key>|set <key> <value>|unset <key>|path|store|edit>

tasqx config get theme.name

tasqx config describe daemon.idle_timeout

tasqx config path

tasqx config store

tasqx config set theme.name gruvbox

tasqx config edit

tasqx config list

SETTING              VALUE                                 SOURCE
theme.name           nord                                  default
dashboard.enabled    true                                  default
dashboard.panels     tasks,projects,burndown,pulse,effort  config.toml
dashboard.refresh    auto                                  default
dashboard.window     week                                  default
notify.enabled       false                                 default
tokens.enabled       false                                 default
otlp.enabled         false                                 default
otlp.port            4318                                  default
board.port           0                                     default
daemon.idle_timeout  0                                     default
default_project      website                               store
mcp.add_status       pending                               default
detail.time_format   both                                  default

tasqx docs [--out PATH | --no-open | --stdout] [--screen NAME]

tasqx docs

tasqx docs --stdout

tasqx docs --screen list

tasqx about [--notices]

tasqx about

tasqx about --notices

tasqx manual [<command|topic>]