@pxlabz/tasq-cli 0.1.31 → 0.3.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +5 -110
- package/package.json +8 -29
- package/tasq.js +11 -0
- package/.tasq-skill.md +0 -216
- package/dist/tasq.js +0 -9656
- package/examples/mention-runner.sh +0 -135
- package/examples/release-narrator.sh +0 -142
package/README.md
CHANGED
|
@@ -1,116 +1,11 @@
|
|
|
1
|
-
# @pxlabz/tasq-cli
|
|
1
|
+
# @pxlabz/tasq-cli is now tasqmate
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
This package is the old name of the Tasqmate CLI. It runs [`tasqmate`](https://www.npmjs.com/package/tasqmate), so the `tasq` command and the scripts that call it keep working. It is published until 15 January 2027.
|
|
4
4
|
|
|
5
|
-
|
|
6
|
-
npx @pxlabz/tasq-cli --help
|
|
7
|
-
# or
|
|
8
|
-
npm install -g @pxlabz/tasq-cli
|
|
9
|
-
tasq --help
|
|
10
|
-
```
|
|
11
|
-
|
|
12
|
-
## Sign in
|
|
13
|
-
|
|
14
|
-
```sh
|
|
15
|
-
tasq auth login # magic-link code flow, stores a user token
|
|
16
|
-
tasq workspace use acme # default workspace
|
|
17
|
-
```
|
|
18
|
-
|
|
19
|
-
Agents skip the login and pass their key through the environment:
|
|
20
|
-
|
|
21
|
-
```sh
|
|
22
|
-
TASQ_API_KEY=tq_ag_… TASQ_WORKSPACE=acme tasq task list
|
|
23
|
-
```
|
|
24
|
-
|
|
25
|
-
## Commands
|
|
26
|
-
|
|
27
|
-
```
|
|
28
|
-
tasq workspace list | use <slug>
|
|
29
|
-
tasq task list | view <ref> | create | update <ref>
|
|
30
|
-
tasq task create|update … [--field <key=value>]…
|
|
31
|
-
tasq field list [--all]
|
|
32
|
-
tasq comment add <ref> <body> [--reply-to <commentRef>] [--mention <name>]…
|
|
33
|
-
tasq comment add --doc <docId> <body> [--thread <threadId>] [--propose <text>]
|
|
34
|
-
tasq time log <ref> <duration> [--day YYYY-MM-DD] [--note <text>] [--billable yes|no]
|
|
35
|
-
tasq time list <ref> | edit <entryId> [--duration] [--day] [--note | --no-note] [--billable] | delete <entryId>
|
|
36
|
-
tasq clients hours <client> [--month YYYY-MM] [--billable]
|
|
37
|
-
tasq clients billing <client>
|
|
38
|
-
tasq week [--day YYYY-MM-DD]
|
|
39
|
-
tasq timesheet request [--day YYYY-MM-DD] | show <draft> | log <draft> | dismiss <draft> | reply <draft> <message>
|
|
40
|
-
tasq timesheet save <draft> --line TASK=DURATION[=BILLABLE[=REASON]]… [--message <text>]
|
|
41
|
-
tasq clients close <client> --month YYYY-MM
|
|
42
|
-
tasq clients invoice <client> --month YYYY-MM [--ref <reference>]
|
|
43
|
-
tasq clients reopen <client> --month YYYY-MM
|
|
44
|
-
tasq events listen [--wait <seconds>] [--once]
|
|
45
|
-
tasq events ack <id>…
|
|
46
|
-
tasq project list | star <project> | unstar <project>
|
|
47
|
-
tasq project share <project> <guest> [--access view|comment] | access <project> <guest> <view|comment> | unshare <project> <guest>
|
|
48
|
-
tasq initiative list | create <name> | rename <initiative> <name> | archive <initiative>
|
|
49
|
-
tasq initiative link <initiative> <project> | unlink <initiative> <project>
|
|
50
|
-
tasq cycle current
|
|
51
|
-
tasq auth login | logout
|
|
52
|
-
```
|
|
53
|
-
|
|
54
|
-
`project share` gives a guest (invited from the web app) a project, with comment access unless `--access view`; `project access` changes it and `project unshare` removes it. Admins and the project lead only; an agent key is refused.
|
|
55
|
-
|
|
56
|
-
`field list` prints the workspace's custom fields with the key `--field` takes, the type, whether it applies to tasks or projects, and a select's option names; `--all` includes archived ones. `--field key=value` is repeatable on `task create` and `task update` and is set after the task is written, one step per field. A multi-select or people field takes `a,b`; options and people go by name (a person also by email); `key=` clears the field. The action reads the rest forgivingly (`1,200` is a number, `yes` ticks a checkbox) and says why when it cannot. `task view` lists the task's values under `Fields:`.
|
|
57
|
-
|
|
58
|
-
`time log` reads a duration as `1h 30m`, `1h30m`, `90m`, `1.5h` or `1:30` (quotes optional) and logs it on today, your local date, unless `--day` says otherwise. One entry is at most 24 hours. `time list` prints each entry with its id, then the total including direct subtasks. Time tracking is member-only: a guest is refused. `clients hours` reads one month of a client's hours by project and person, and lists entries with no billable flag; it works where a team with a project for that client has Client hours on. `clients billing` lists the client's months with their hours and state; `close`, `invoice` and `reopen` lock, mark and unlock one month where a team has Billing periods on, and only an admin can run them. A closed month refuses every change to its hours until it is reopened. The invoice reference is a label; tasq never computes an amount. `week` prints your Monday-to-Sunday hours, the chosen day's entries, and the tasks you changed or commented on that day without logging time; it works where a team has My week on. `timesheet` covers agent-drafted timesheets: `request` asks your team's drafting agent for a day, `show` prints a draft, `log` logs its ticked lines as your time, `dismiss` sets it aside, and `reply` answers the agent so it drafts again. `save` is the drafting agent's side and replaces the draft's lines; it works where a team has Agent timesheet drafts on and picked that agent.
|
|
59
|
-
|
|
60
|
-
Every command takes `--json` for raw output and `-w, --workspace <slug>` to override the default. Task refs accept either the human key (`ENG-42`) or the UUID.
|
|
61
|
-
|
|
62
|
-
### Mentions and replies
|
|
63
|
-
|
|
64
|
-
`--mention <name>` is repeatable and matches a person's or an agent's name exactly, ignoring case; a person also matches by email. A name that matches more than one member — two people, two agents, or a person and an agent — is a usage error (exit 2) that lists the candidates rather than a guess. Each mentioned person gets a `mentioned` notification and a `mentioned <name>` line. After the comment is written, one line per mention says `delivered to <name>`, or `<name>: suppressed: agents are isolated` when one agent mentioned another — agents do not deliver mentions to each other in this release.
|
|
65
|
-
|
|
66
|
-
`--reply-to` takes a comment id, or the `ENG-42#<id>` form `task view` prints. The parent must be a comment on the same task.
|
|
67
|
-
|
|
68
|
-
### Listening for mentions
|
|
69
|
-
|
|
70
|
-
`tasq events listen` streams NDJSON — one compact JSON object per line, per event — whatever `--json` says, because the output is meant for a runner loop rather than a reader:
|
|
71
|
-
|
|
72
|
-
```sh
|
|
73
|
-
TASQ_API_KEY=tq_ag_… TASQ_WORKSPACE=acme tasq events listen --wait 20 |
|
|
74
|
-
while read -r event; do handle "$event"; done
|
|
75
|
-
```
|
|
76
|
-
|
|
77
|
-
Each poll holds the connection open for up to `--wait` seconds (0-25; the server clamps) and is charged once against the read budget, so `--wait 20` costs at most three reads a minute of the 120 available. An empty response means the window expired with nothing waiting, and the listener reconnects at once. On a 429 it sleeps for `Retry-After` and carries on rather than exiting, so a supervised runner cannot turn a rate limit into a restart loop that burns the same budget. Ctrl-C aborts the in-flight poll and exits 0.
|
|
78
|
-
|
|
79
|
-
Events stay deliverable until acknowledged: `tasq events ack <id>…` marks them, and an unacked event is offered again ten minutes after it was delivered. A runner that crashes mid-work therefore sees the event once more rather than losing it.
|
|
80
|
-
|
|
81
|
-
## For agents
|
|
82
|
-
|
|
83
|
-
Two files ship with the package for the agent side of this.
|
|
84
|
-
|
|
85
|
-
- **`.tasq-skill.md`** — a skill file written for a coding agent: what Tasq is, when to reach for it, the full command reference, the mention → read → reply → ack workflow, the exit codes, and the isolation rule. Point your harness at it, or read it yourself.
|
|
86
|
-
- **`examples/mention-runner.sh`** — a reference loop over `tasq events listen`. It exports `TASQ_EVENT_ID`, `TASQ_EVENT_KIND`, `TASQ_EVENT_TASK_KEY`, `TASQ_EVENT_TASK_ID`, `TASQ_EVENT_COMMENT_ID` and `TASQ_EVENT_MENTIONED_BY`, runs `$TASQ_AGENT_CMD` once per event, and acks only when that command exits 0 so a failure is redelivered rather than lost.
|
|
5
|
+
To move, remove this package first: both packages provide the `tasq` command, and npm refuses to install the second one over it.
|
|
87
6
|
|
|
88
7
|
```sh
|
|
89
|
-
|
|
90
|
-
TASQ_AGENT_CMD='claude -p "handle $TASQ_EVENT_TASK_KEY"' \
|
|
91
|
-
./node_modules/@pxlabz/tasq-cli/examples/mention-runner.sh --wait 20
|
|
8
|
+
npm rm -g @pxlabz/tasq-cli && npm i -g tasqmate
|
|
92
9
|
```
|
|
93
10
|
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
## Configuration
|
|
97
|
-
|
|
98
|
-
| Source | Purpose |
|
|
99
|
-
| --- | --- |
|
|
100
|
-
| `TASQ_API_KEY` | Agent key (`tq_ag_…`); wins over a stored user token |
|
|
101
|
-
| `TASQ_USER_TOKEN` | User token (`tq_us_…`) without running `auth login` |
|
|
102
|
-
| `TASQ_WORKSPACE` | Default workspace slug |
|
|
103
|
-
| `TASQ_API_URL` | API origin; defaults to `https://tasq.pxlabz.com` |
|
|
104
|
-
| `TASQ_CONFIG_DIR` | Where the stored token lives; defaults to `$XDG_CONFIG_HOME/tasq` |
|
|
105
|
-
|
|
106
|
-
## Exit codes
|
|
107
|
-
|
|
108
|
-
| Code | Meaning |
|
|
109
|
-
| --- | --- |
|
|
110
|
-
| 0 | Success |
|
|
111
|
-
| 1 | Error (details on stderr) |
|
|
112
|
-
| 2 | Usage error — including an `--mention` name that matches no one or more than one member |
|
|
113
|
-
| 3 | Rate limited; the message includes when to retry. `events listen` does not exit here: it sleeps for `Retry-After` and carries on |
|
|
114
|
-
| 4 | The agent's policy denied the action |
|
|
115
|
-
|
|
116
|
-
Built as a single file on top of [`@pxlabz/tasq-sdk`](https://www.npmjs.com/package/@pxlabz/tasq-sdk). Node 20.3 or newer (for `AbortSignal.any`).
|
|
11
|
+
The new package installs two commands, `tasqmate` and `tasq`, which do the same thing. Environment variables are now `TASQMATE_*`, and the config folder is `~/.config/tasqmate`; the `TASQ_*` names still work, and your sign-in is copied across the first time you run it.
|
package/package.json
CHANGED
|
@@ -1,12 +1,10 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@pxlabz/tasq-cli",
|
|
3
|
-
"version": "0.
|
|
4
|
-
"description": "
|
|
3
|
+
"version": "0.3.0",
|
|
4
|
+
"description": "Renamed to tasqmate. This package runs it so existing installs keep working until January 2027.",
|
|
5
5
|
"keywords": [
|
|
6
|
-
"
|
|
7
|
-
"cli"
|
|
8
|
-
"agents",
|
|
9
|
-
"project-management"
|
|
6
|
+
"tasqmate",
|
|
7
|
+
"cli"
|
|
10
8
|
],
|
|
11
9
|
"license": "MIT",
|
|
12
10
|
"author": "Paul Cedrick Artigo",
|
|
@@ -14,20 +12,15 @@
|
|
|
14
12
|
"repository": {
|
|
15
13
|
"type": "git",
|
|
16
14
|
"url": "git+https://github.com/pxlabz/tasq.git",
|
|
17
|
-
"directory": "packages/cli"
|
|
18
|
-
},
|
|
19
|
-
"bugs": {
|
|
20
|
-
"url": "https://github.com/pxlabz/tasq/issues"
|
|
15
|
+
"directory": "packages/legacy-cli"
|
|
21
16
|
},
|
|
22
17
|
"private": false,
|
|
23
18
|
"type": "module",
|
|
24
19
|
"bin": {
|
|
25
|
-
"tasq": "./
|
|
20
|
+
"tasq": "./tasq.js"
|
|
26
21
|
},
|
|
27
22
|
"files": [
|
|
28
|
-
"
|
|
29
|
-
"examples",
|
|
30
|
-
".tasq-skill.md",
|
|
23
|
+
"tasq.js",
|
|
31
24
|
"README.md",
|
|
32
25
|
"LICENSE"
|
|
33
26
|
],
|
|
@@ -37,21 +30,7 @@
|
|
|
37
30
|
"engines": {
|
|
38
31
|
"node": ">=20.3"
|
|
39
32
|
},
|
|
40
|
-
"scripts": {
|
|
41
|
-
"build": "tsup && chmod +x dist/tasq.js",
|
|
42
|
-
"typecheck": "tsc --project tsconfig.json --noEmit",
|
|
43
|
-
"lint": "cd ../.. && bun --bun ./node_modules/oxlint/bin/oxlint packages/cli",
|
|
44
|
-
"test": "bun test"
|
|
45
|
-
},
|
|
46
33
|
"dependencies": {
|
|
47
|
-
"
|
|
48
|
-
"cli-table3": "^0.6.5",
|
|
49
|
-
"commander": "^14.0.0"
|
|
50
|
-
},
|
|
51
|
-
"devDependencies": {
|
|
52
|
-
"@pxlabz/tasq-sdk": "0.1.18",
|
|
53
|
-
"@types/bun": "^1.3.12",
|
|
54
|
-
"tsup": "^8.5.0",
|
|
55
|
-
"typescript": "^5.7.2"
|
|
34
|
+
"tasqmate": "0.3.0"
|
|
56
35
|
}
|
|
57
36
|
}
|
package/tasq.js
ADDED
|
@@ -0,0 +1,11 @@
|
|
|
1
|
+
#!/usr/bin/env node
|
|
2
|
+
// @pxlabz/tasq-cli is now `tasqmate`. This runs it, so a global install or a
|
|
3
|
+
// script that calls `tasq` keeps working. The move notice goes to a person at
|
|
4
|
+
// a terminal only, never into an agent's or a pipe's output.
|
|
5
|
+
if (process.stderr.isTTY) {
|
|
6
|
+
process.stderr.write(
|
|
7
|
+
"@pxlabz/tasq-cli is now tasqmate. To move: npm rm -g @pxlabz/tasq-cli && npm i -g tasqmate\n",
|
|
8
|
+
);
|
|
9
|
+
}
|
|
10
|
+
|
|
11
|
+
await import("tasqmate/dist/tasqmate.js");
|
package/.tasq-skill.md
DELETED
|
@@ -1,216 +0,0 @@
|
|
|
1
|
-
---
|
|
2
|
-
name: tasq
|
|
3
|
-
description: Read and write Tasq tasks, projects, threads, comments and mentions from the shell with the `tasq` CLI. Use when you are working in a repository whose issues live in Tasq, when someone asks you to look at a task by its key (ENG-42), when you need to comment on or update a task, or when you are running as a Tasq agent and want to receive the mentions and thread messages addressed to you. Covers authentication, the full command reference, the mention-reply-ack workflow, threads, release narratives, exit codes, and working alongside other agents.
|
|
4
|
-
---
|
|
5
|
-
|
|
6
|
-
# Tasq
|
|
7
|
-
|
|
8
|
-
Tasq is a task tracker whose write path is one action registry, reachable equally by a person in the web app and by an agent holding a key — the same permission checks and the same audit trail either way. The `tasq` CLI is that surface for a shell.
|
|
9
|
-
|
|
10
|
-
Tasq is not an agent runtime. It stores work, delivers mentions addressed to you, and records what you did. It never starts, supervises, or schedules you; that harness is the owner's.
|
|
11
|
-
|
|
12
|
-
## When to use it
|
|
13
|
-
|
|
14
|
-
- A task key like `ENG-42` appears in a request, a branch name, or a commit message.
|
|
15
|
-
- You have been asked to read, create, update, or comment on a task.
|
|
16
|
-
- You are running under a Tasq agent key and want the mentions queued for you.
|
|
17
|
-
|
|
18
|
-
Do not reach for it to store notes that belong in the repository, and do not create tasks nobody asked for.
|
|
19
|
-
|
|
20
|
-
## Authentication
|
|
21
|
-
|
|
22
|
-
The CLI reads its credentials from the environment. Nothing needs to be installed beyond the CLI itself.
|
|
23
|
-
|
|
24
|
-
| Variable | Meaning |
|
|
25
|
-
| --- | --- |
|
|
26
|
-
| `TASQ_API_KEY` | Agent key (`tq_ag_…`). This is what you hold when you run as an agent. |
|
|
27
|
-
| `TASQ_WORKSPACE` | Default workspace slug, so commands need no `--workspace`. |
|
|
28
|
-
| `TASQ_API_URL` | API origin. Defaults to `https://tasq.pxlabz.com`. |
|
|
29
|
-
|
|
30
|
-
A human instead runs `tasq auth login` once, which stores a user token. If `TASQ_API_KEY` is set it wins over any stored token. Never print a key, and never write one into a file in the repository.
|
|
31
|
-
|
|
32
|
-
## Command reference
|
|
33
|
-
|
|
34
|
-
Global flags, valid on every command: `-w, --workspace <slug>`, `--api-url <url>`, `--json`. Task refs accept the human key (`ENG-42`) or the UUID.
|
|
35
|
-
|
|
36
|
-
```
|
|
37
|
-
tasq workspace list
|
|
38
|
-
tasq workspace use <slug>
|
|
39
|
-
|
|
40
|
-
tasq task list [--team <identifier>] [--status <name>] [--assignee <id>]
|
|
41
|
-
[--priority urgent|high|medium|low|none] [--project <id>]
|
|
42
|
-
[--cycle <id>] [-q, --q <text>] [--include-archived]
|
|
43
|
-
tasq task view <ref>
|
|
44
|
-
tasq task create <title> [--team <identifier>] [--description <markdown>]
|
|
45
|
-
[--priority <priority>] [--project <id>]
|
|
46
|
-
[--labels <a,b,c>] [--due <YYYY-MM-DD>]
|
|
47
|
-
[--start <YYYY-MM-DD>] [--parent <ref>]
|
|
48
|
-
[--field <key=value>]…
|
|
49
|
-
tasq task update <ref> [--title <title>] [--description <markdown>]
|
|
50
|
-
[--priority <priority>] [--status <name>]
|
|
51
|
-
[--due <YYYY-MM-DD|none>] [--start <YYYY-MM-DD|none>]
|
|
52
|
-
[--parent <ref> | --no-parent] [--field <key=value>]…
|
|
53
|
-
|
|
54
|
-
tasq field list [--all]
|
|
55
|
-
|
|
56
|
-
tasq comment add <ref> <body> [--reply-to <commentRef>] [--thread <threadId>]
|
|
57
|
-
[--mention <name>]…
|
|
58
|
-
tasq comment add --project <id|name> <body> [--reply-to <commentRef>]
|
|
59
|
-
[--thread <threadId>] [--mention <name>]…
|
|
60
|
-
tasq comment add --doc <docId> <body> [--thread <threadId>] [--propose <text>]
|
|
61
|
-
|
|
62
|
-
tasq time log <ref> <duration> [--day <YYYY-MM-DD>] [--note <text>] [--billable <yes|no>]
|
|
63
|
-
tasq time list <ref>
|
|
64
|
-
tasq time edit <entryId> [--duration <duration>] [--day <YYYY-MM-DD>] [--note <text> | --no-note] [--billable <yes|no|unset>]
|
|
65
|
-
tasq time delete <entryId>
|
|
66
|
-
tasq clients hours <client> [--month <YYYY-MM>] [--billable]
|
|
67
|
-
tasq clients billing <client>
|
|
68
|
-
tasq week [--day <YYYY-MM-DD>]
|
|
69
|
-
tasq timesheet show <draftId>
|
|
70
|
-
tasq timesheet save <draftId> --line <task>=<duration>[=<yes|no>[=<reason>]]… [--message <text>]
|
|
71
|
-
tasq timesheet request [--day <YYYY-MM-DD>] | log <draftId> | dismiss <draftId> | reply <draftId> <message> # people
|
|
72
|
-
tasq clients close|reopen <client> --month <YYYY-MM> # admins
|
|
73
|
-
tasq clients invoice <client> --month <YYYY-MM> [--ref <ref>] # admins
|
|
74
|
-
|
|
75
|
-
tasq thread view <threadId>
|
|
76
|
-
tasq thread context <threadId> [--markdown]
|
|
77
|
-
|
|
78
|
-
tasq events listen [--wait <seconds>] [--once]
|
|
79
|
-
tasq events ack <id>…
|
|
80
|
-
|
|
81
|
-
tasq project list
|
|
82
|
-
tasq cycle current [--team <identifier>]
|
|
83
|
-
|
|
84
|
-
tasq release list [--team <identifier>]
|
|
85
|
-
tasq release view <releaseId>
|
|
86
|
-
tasq release context <releaseId> [--markdown]
|
|
87
|
-
tasq release diff <releaseId>
|
|
88
|
-
tasq release export <releaseId> [--out <file>]
|
|
89
|
-
tasq release narrate <releaseId> (--body <markdown> | --file <path>)
|
|
90
|
-
|
|
91
|
-
tasq update list <project>
|
|
92
|
-
tasq update draft <project> --health <on_track|at_risk|off_track> (--body <markdown> | --file <path>)
|
|
93
|
-
tasq update send <updateId>
|
|
94
|
-
tasq update delete <updateId>
|
|
95
|
-
|
|
96
|
-
tasq auth login [--email <email>]
|
|
97
|
-
tasq auth logout
|
|
98
|
-
tasq auth whoami
|
|
99
|
-
```
|
|
100
|
-
|
|
101
|
-
`--parent <ref>` makes the task a subtask of another task on the same team (one level only: a subtask cannot take subtasks, and an archived task cannot be a parent). A subtask's project and phase follow its parent, so `task create` refuses `--parent` together with `--project`; move the parent instead. `--no-parent` on `task update` detaches it and leaves its placement alone. `task view` prints `Parent: <key>` on a subtask and `Subtasks: <done>/<total> done` on a parent.
|
|
102
|
-
|
|
103
|
-
Custom fields: `tasq field list` shows each field's key, type, whether it applies to tasks or projects, and a select's option names (`--all` adds archived fields). `--field key=value` sets one on `task create` or `task update`, repeatable, one step per field after the task is written; `update` with only `--field` is fine. A multi-select or people field takes `a,b`; options and people go by name, a person also by email; `key=` clears it. Anything else is read forgivingly by the server (`1,200` is a number, `yes` ticks a checkbox) and a value that cannot fit is refused with the reason. An unknown key is a usage error naming the task fields, before anything is written. `task view` lists the values under `Fields:`.
|
|
104
|
-
|
|
105
|
-
`--mention` is repeatable and matches a person or agent name exactly, ignoring case; a person also matches by email. A name that matches more than one member (two people, or a person and an agent) is a usage error that lists the candidates. Agents are woken; people get a `mentioned` notification, and the output prints `mentioned <name>` for each.
|
|
106
|
-
|
|
107
|
-
`task view` and `thread view` print every message with its id on the header line, as ` <createdAt> <author> #<id>` with the body indented beneath it. That `#<id>` is what `--reply-to` and `--thread` take; the `ENG-42#<id>` form is also accepted. The parent must be a message on the same task or project.
|
|
108
|
-
|
|
109
|
-
`--thread <threadId>` is an alias for `--reply-to` that reads right when you are answering an event: the `threadId` an event carries is exactly what it wants. Passing both is fine if they name the same message; two different ids is a usage error.
|
|
110
|
-
|
|
111
|
-
A comment goes on a task or a project, never both and never neither: give the task ref as the argument, or pass `--project <id|name>` instead. Project names match exactly, ignoring case.
|
|
112
|
-
|
|
113
|
-
## When you are mentioned
|
|
114
|
-
|
|
115
|
-
`tasq events listen` prints NDJSON — one compact JSON object per line, per event — whatever `--json` says, because it is meant to be read by a loop. Each object carries ids only: `{ id, kind, workspace, taskId, taskKey, projectId, threadId, commentId, releaseId, mentionedBy, deliveryCount, createdAt }`. `kind` is `mention`, `thread_message`, `cycle_closed`, `timesheet_due` or `timesheet_reply`; on the first two exactly one of `taskId` and `projectId` is set, and `mentionedBy` carries `{ memberId, type, name }` whose `type` is `user` or `agent`. On a `cycle_closed` every one of those is null and only `releaseId` is set — see **Release narratives**. On the two timesheet kinds only `timeDraftId` is set — see **Timesheet drafts**. There is no comment body in the event, on purpose: every read you make from those ids goes through your policy, so you see exactly what you are allowed to see.
|
|
116
|
-
|
|
117
|
-
The loop is:
|
|
118
|
-
|
|
119
|
-
1. **Listen.** `tasq events listen --wait 20`. Each poll holds the connection open for up to 25 seconds and costs one read, so a listener is about three reads a minute.
|
|
120
|
-
2. **Read the task.** `tasq task view <taskKey> --json`. This is where the body of the mention, the rest of the thread, and the task's state come from.
|
|
121
|
-
3. **Gather context.** `tasq thread context <threadId>` assembles the entity, the transcript and the recent activity in one call — see **Threads** below. The `task view` payload carries the same comments and activity log if the mention is on a task and you want the raw shape. Read before you write.
|
|
122
|
-
4. **Reply in the thread.** `tasq comment add <taskKey> "…" --thread <threadId>`, using the `threadId` from the event so your answer lands in the conversation rather than at the bottom. On a project mention, `tasq comment add --project <id|name> "…" --thread <threadId>`. On a doc mention the event carries `documentId`: `tasq comment add --doc <documentId> "…" --thread <threadId>`. When you are asked to rewrite the thread's passage (`thread context` shows it as **Passage**), add `--propose "<new text>"` (empty deletes it): a member sees it struck and rewritten and accepts or rejects it. Propose the passage only, not the whole doc.
|
|
123
|
-
5. **Acknowledge.** `tasq events ack <eventId>`, and only after the work is done.
|
|
124
|
-
|
|
125
|
-
Ack last, deliberately. An unacknowledged event is offered again ten minutes after delivery, so a crash between step 2 and step 4 costs nothing; an event acked up front is gone. On a 429 the listener sleeps for `Retry-After` and carries on rather than exiting, so do not wrap it in a restart loop that would spend the same budget twice.
|
|
126
|
-
|
|
127
|
-
`examples/mention-runner.sh` in this package is a working reference for steps 1 and 5. It is an example, not a product.
|
|
128
|
-
|
|
129
|
-
## Threads
|
|
130
|
-
|
|
131
|
-
A thread is a root message and its replies, on a task or on a project. Its id — the `threadId` an event carries — is the root message's id.
|
|
132
|
-
|
|
133
|
-
Two event kinds reach you, and they mean different things:
|
|
134
|
-
|
|
135
|
-
- **`mention`** is a request addressed to you. Somebody typed your name. Read it and act.
|
|
136
|
-
- **`thread_message`** is a later message in a thread you are already in — you were mentioned in it once, or you have spoken in it, so Tasq keeps sending you the conversation without anybody re-typing `@`. Read it, and reply only if it actually needs you. Most of the time it is context, not a request; a thread does not need you to answer every turn. Check `mentionedBy.type`: on an open team it may be another agent's message (see **Working with other agents**).
|
|
137
|
-
|
|
138
|
-
Start from the context bundle rather than guessing which entity the thread is on:
|
|
139
|
-
|
|
140
|
-
```
|
|
141
|
-
tasq thread context <threadId>
|
|
142
|
-
```
|
|
143
|
-
|
|
144
|
-
That prints a Markdown prompt with four sections in a fixed order — **Entity**, **Thread**, **Recent activity**, **Participants** — covering the task or project the thread hangs off, the transcript so far, what else happened on that entity, and who is in the conversation. `--json` gives the same bundle raw if you would rather branch on the fields. The lists are capped (last 50 messages, last 20 activity rows, description cut at 8k chars); anything cut says so, so a `_(showing last 50 of 130 messages)_` line means there is more you are not seeing.
|
|
145
|
-
|
|
146
|
-
`tasq thread view <threadId>` is the short form: the entity line and the transcript with each message's id, when all you need is an id to reply to.
|
|
147
|
-
|
|
148
|
-
Reply into the thread with the id the event gave you, whichever entity it is on:
|
|
149
|
-
|
|
150
|
-
```
|
|
151
|
-
tasq comment add <taskKey> "…" --thread <threadId>
|
|
152
|
-
tasq comment add --project <projectName> "…" --thread <threadId>
|
|
153
|
-
```
|
|
154
|
-
|
|
155
|
-
Acknowledge both kinds the same way, with `tasq events ack <eventId>`, and only after you are done — including when you decide a `thread_message` needed nothing from you. An unacked event comes back in ten minutes.
|
|
156
|
-
|
|
157
|
-
On an isolated team — the default — another agent's messages do not reach you and yours do not wake another agent, so a thread that needs work you cannot do is a thread to escalate to a person. See **Working with other agents** below.
|
|
158
|
-
|
|
159
|
-
## Release narratives
|
|
160
|
-
|
|
161
|
-
When a cycle closes, Tasq writes a **release**: the number, the dates, and every task in the cycle classified as shipped, carried over or dropped, with the ones that arrived mid-cycle marked. It writes that row itself, from the close snapshot, whether or not any agent is connected. The **narrative** is the Markdown body attached to it afterwards, and that is the part you write.
|
|
162
|
-
|
|
163
|
-
If you are set as a team's release narrator, each close sends you one `cycle_closed` event. It is the only event kind that carries a `releaseId`, and it carries nothing else: `taskId`, `taskKey`, `projectId`, `threadId`, `commentId` and `mentionedBy` are all null, because a cycle close is not somebody talking to you. The `releaseId` is the whole payload.
|
|
164
|
-
|
|
165
|
-
The loop is:
|
|
166
|
-
|
|
167
|
-
1. **Listen.** `tasq events listen --wait 20`, the same listener as for mentions. Filter on `kind == "cycle_closed"` and read `.releaseId`.
|
|
168
|
-
2. **Read the release.** `tasq release context <releaseId>` prints a Markdown prompt: the cycle and its dates, the shipped / carried over / dropped lists, the change against the previous release, and the previous narrative. `--json` gives the same bundle raw. Each task list is capped at 100; a cut list says so.
|
|
169
|
-
3. **Write it.** Prose about what the cycle did, for the people who were not in it. The diff and the counts are already on the page — do not just restate them.
|
|
170
|
-
4. **Save it.** `tasq release narrate <releaseId> --file notes.md`, or `--body "…"` for a short one, or pipe the body in with neither flag. The cap is 50,000 characters.
|
|
171
|
-
5. **Acknowledge.** `tasq events ack <eventId>`, last, as always.
|
|
172
|
-
|
|
173
|
-
Three things to know before you write:
|
|
174
|
-
|
|
175
|
-
- **The release already exists.** Nothing waits on you. If you never answer, the release stands with an empty narrative and the team still sees what shipped.
|
|
176
|
-
- **It is one field, last write wins.** There is no thread and no version history: `release narrate` replaces whatever is there. A person may have written or edited it in the web app before you ran, and a person may replace yours afterwards. Your name and the time are shown next to it either way, so read the release before overwriting a narrative that is already good.
|
|
177
|
-
- **It is not a thread event.** Isolation and the loop caps govern agents waking agents in conversations; a cycle close is Tasq waking one agent. Neither applies, and your narrative wakes nobody.
|
|
178
|
-
|
|
179
|
-
`tasq release list --team ENG` is the timeline, newest first; `tasq release view <releaseId>` shows one in full; `tasq release export <releaseId>` prints it as Markdown for a changelog. `examples/release-narrator.sh` in this package is a working reference for the loop above, minus the writing.
|
|
180
|
-
|
|
181
|
-
## Timesheet drafts
|
|
182
|
-
|
|
183
|
-
If a team picked you to draft timesheets, Tasq wakes you with a `timesheet_due` event when a member's day ends (17:30 their time) with work on tasks and no time logged on them, or when they press "Draft my day". The event's `timeDraftId` is the whole payload. You draft; the member decides: nothing becomes time until they log it.
|
|
184
|
-
|
|
185
|
-
1. **Read the day.** `tasq timesheet show <draftId> --json` gives the draft (`memberId`, `day`, the conversation). The MCP tool `time_draft_get` returns the draft with the member's day: the entries already logged and `unlogged`, each task they commented on or changed without logging time.
|
|
186
|
-
2. **Draft it.** One line per task: a duration, whether it is billable when you can tell, and a one-line reason drawn from what you read ("2 comments, moved to In review"). Leave out what you can't justify.
|
|
187
|
-
3. **Save it.** `tasq timesheet save <draftId> --line ENG-12=1h30m=yes=2 comments --line ENG-15=30m --message "Here's your Wednesday."` replaces every line. The member sees it on My week and in their Inbox.
|
|
188
|
-
4. **Acknowledge.** `tasq events ack <eventId>`.
|
|
189
|
-
|
|
190
|
-
A `timesheet_reply` event means the member answered ("the logo was more like 2h"): read the draft again, the reply is the last message, and save a revised draft. Only the member can log, dismiss or reply; your policy refuses those whatever its preset, and you can only read days of members whose draft you were asked for.
|
|
191
|
-
|
|
192
|
-
## Project updates
|
|
193
|
-
|
|
194
|
-
A project update is a health call (`on_track`, `at_risk` or `off_track`) and a Markdown body for the project's client. `<project>` is a project id or its exact name, ignoring case.
|
|
195
|
-
|
|
196
|
-
You draft; a person sends. `tasq update draft` always writes a draft, and nothing an agent drafts goes to a client until a person reviews and sends it. `tasq update send` is refused for an agent key before any request (exit 4), and no policy can grant it. Drafts can be edited or deleted by their author; a sent update is final. `tasq update list` shows drafts and sent updates, newest first, and the project's health is its latest sent update.
|
|
197
|
-
|
|
198
|
-
## Exit codes
|
|
199
|
-
|
|
200
|
-
| Code | Meaning |
|
|
201
|
-
| --- | --- |
|
|
202
|
-
| 0 | Success |
|
|
203
|
-
| 1 | Error; details on stderr |
|
|
204
|
-
| 2 | Usage error — a bad flag, or a `--mention` name matching no one or more than one member |
|
|
205
|
-
| 3 | Rate limited; the message says when to retry. `events listen` never exits here — it waits and continues |
|
|
206
|
-
| 4 | Your policy denied the action, or it is one only a person may run (`update send`). Do not retry it; say what was refused |
|
|
207
|
-
|
|
208
|
-
## Working with other agents
|
|
209
|
-
|
|
210
|
-
Isolation is the default. On an isolated team your mentions of other agents and your thread messages are recorded but never delivered, and the CLI line tells you so: `hermes: suppressed: agents are isolated on this team`. Nothing you write reaches another agent, and nothing another agent writes reaches you. When a thread needs work you cannot do, escalate to a person in the thread rather than trying to hand it to an agent.
|
|
211
|
-
|
|
212
|
-
A team admin can turn isolation off for a team in **Settings → Teams → Agents**. On an open team your messages wake the other agents on that team's tasks and projects, and theirs wake you. An event whose `mentionedBy.type` is `agent` is another agent's message, not a person's: reply only when you add something. Never reply just to acknowledge, and never re-mention an agent that mentioned you unless you actually need something from it.
|
|
213
|
-
|
|
214
|
-
Two limits stand behind an open team. After 5 agent messages in a row in one thread, Tasq stops waking agents until a person posts (`suppressed: loop stopped after 5 agent messages in a row; waiting for a person`). One message never wakes more than 10 agents (`suppressed: fan-out cap of 10 reached`). Both are reported on the line `comment add` prints and in your activity timeline; the comment itself is still saved either way, and the people in the thread are still notified.
|
|
215
|
-
|
|
216
|
-
Projects shared with a team that kept isolation stay isolated.
|