tasqmate 0.0.0-stage → 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/.tasqmate-skill.md +237 -0
- package/LICENSE +21 -0
- package/README.md +164 -2
- package/dist/tasqmate.js +26504 -0
- package/examples/mention-runner.sh +151 -0
- package/examples/release-narrator.sh +147 -0
- package/package.json +58 -5
|
@@ -0,0 +1,237 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: tasqmate
|
|
3
|
+
description: Read and write Tasqmate tasks, projects, threads, comments and mentions from the shell with the `tasqmate` CLI (also installed as `tasq`). Use when you are working in a repository whose issues live in Tasqmate, 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 Tasqmate 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
|
+
# Tasqmate
|
|
7
|
+
|
|
8
|
+
Tasqmate 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 `tasqmate` CLI is that surface for a shell; `tasq` is the same command, shorter. Examples below use `tasqmate`.
|
|
9
|
+
|
|
10
|
+
Tasqmate 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 Tasqmate 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
|
+
| `TASQMATE_API_KEY` | Agent key (`tq_ag_…`). This is what you hold when you run as an agent. |
|
|
27
|
+
| `TASQMATE_WORKSPACE` | Default workspace slug, so commands need no `--workspace`. |
|
|
28
|
+
| `TASQMATE_API_URL` | API origin. Defaults to `https://tasqmate.pxlabz.com`. |
|
|
29
|
+
|
|
30
|
+
A human instead runs `tasqmate auth login` once, which stores a user token. If `TASQMATE_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
|
+
tasqmate workspace list
|
|
38
|
+
tasqmate workspace use <slug>
|
|
39
|
+
|
|
40
|
+
tasqmate 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
|
+
tasqmate task view <ref>
|
|
44
|
+
tasqmate 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
|
+
tasqmate 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
|
+
tasqmate field list [--all]
|
|
55
|
+
|
|
56
|
+
tasqmate comment add <ref> <body> [--reply-to <commentRef>] [--thread <threadId>]
|
|
57
|
+
[--mention <name>]…
|
|
58
|
+
tasqmate comment add --project <id|name> <body> [--reply-to <commentRef>]
|
|
59
|
+
[--thread <threadId>] [--mention <name>]…
|
|
60
|
+
tasqmate comment add --doc <docId> <body> [--thread <threadId>] [--propose <text>]
|
|
61
|
+
|
|
62
|
+
tasqmate time log <ref> <duration> [--day <YYYY-MM-DD>] [--note <text>] [--billable <yes|no>]
|
|
63
|
+
tasqmate time list <ref>
|
|
64
|
+
tasqmate time edit <entryId> [--duration <duration>] [--day <YYYY-MM-DD>] [--note <text> | --no-note] [--billable <yes|no|unset>]
|
|
65
|
+
tasqmate time delete <entryId>
|
|
66
|
+
tasqmate clients hours <client> [--month <YYYY-MM>] [--billable]
|
|
67
|
+
tasqmate clients billing <client>
|
|
68
|
+
tasqmate week [--day <YYYY-MM-DD>]
|
|
69
|
+
tasqmate timesheet show <draftId>
|
|
70
|
+
tasqmate timesheet save <draftId> --line <task>=<duration>[=<yes|no>[=<reason>]]… [--message <text>]
|
|
71
|
+
tasqmate timesheet request [--day <YYYY-MM-DD>] | log <draftId> | dismiss <draftId> | reply <draftId> <message> # people
|
|
72
|
+
tasqmate clients close|reopen <client> --month <YYYY-MM> # admins
|
|
73
|
+
tasqmate clients invoice <client> --month <YYYY-MM> [--ref <ref>] # admins
|
|
74
|
+
|
|
75
|
+
tasqmate thread view <threadId>
|
|
76
|
+
tasqmate thread context <threadId> [--markdown]
|
|
77
|
+
|
|
78
|
+
tasqmate events listen [--wait <seconds>] [--once]
|
|
79
|
+
tasqmate events ack <id>…
|
|
80
|
+
|
|
81
|
+
tasqmate project list
|
|
82
|
+
tasqmate cycle current [--team <identifier>]
|
|
83
|
+
|
|
84
|
+
tasqmate doc list [--filter all|workspace|projects|teams|mine|archived] [--project <project>] [-q <text>]
|
|
85
|
+
tasqmate doc view <doc> # body as Markdown; doc = id, link or exact title
|
|
86
|
+
tasqmate doc create <title> [--body <markdown> | --file <path|->] [--project <project>] [--team <identifier>]
|
|
87
|
+
tasqmate doc update <doc> [--title <title>] [--body <markdown> | --file <path|->] [--base-version <n>]
|
|
88
|
+
tasqmate doc link <doc> --task <ref> | --project <project> | --team <identifier>
|
|
89
|
+
tasqmate doc archive <doc> [--restore]
|
|
90
|
+
|
|
91
|
+
tasqmate release list [--team <identifier>]
|
|
92
|
+
tasqmate release view <releaseId>
|
|
93
|
+
tasqmate release context <releaseId> [--markdown]
|
|
94
|
+
tasqmate release diff <releaseId>
|
|
95
|
+
tasqmate release export <releaseId> [--out <file>]
|
|
96
|
+
tasqmate release narrate <releaseId> (--body <markdown> | --file <path>)
|
|
97
|
+
|
|
98
|
+
tasqmate update list <project>
|
|
99
|
+
tasqmate update draft <project> --health <on_track|at_risk|off_track> (--body <markdown> | --file <path>)
|
|
100
|
+
tasqmate update send <updateId>
|
|
101
|
+
tasqmate update delete <updateId>
|
|
102
|
+
|
|
103
|
+
tasqmate auth login [--email <email>]
|
|
104
|
+
tasqmate auth logout
|
|
105
|
+
tasqmate auth whoami
|
|
106
|
+
```
|
|
107
|
+
|
|
108
|
+
`--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.
|
|
109
|
+
|
|
110
|
+
Custom fields: `tasqmate 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:`.
|
|
111
|
+
|
|
112
|
+
`--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.
|
|
113
|
+
|
|
114
|
+
`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.
|
|
115
|
+
|
|
116
|
+
`--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.
|
|
117
|
+
|
|
118
|
+
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.
|
|
119
|
+
|
|
120
|
+
## When you are mentioned
|
|
121
|
+
|
|
122
|
+
`tasqmate 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: `{ id, kind, workspace, taskId, taskKey, projectId, documentId, threadId, commentId, releaseId, timeDraftId, routine, mentionedBy, deliveryCount, createdAt }`. `kind` is `mention`, `thread_message`, `cycle_closed`, `timesheet_due`, `timesheet_reply` or `routine`; 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**. On a `routine` only `routine` is set — see **Routines**. 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.
|
|
123
|
+
|
|
124
|
+
The loop is:
|
|
125
|
+
|
|
126
|
+
1. **Listen.** `tasqmate 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.
|
|
127
|
+
2. **Read the task.** `tasqmate task view <taskKey> --json`. This is where the body of the mention, the rest of the thread, and the task's state come from.
|
|
128
|
+
3. **Gather context.** `tasqmate 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.
|
|
129
|
+
4. **Reply in the thread.** `tasqmate 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, `tasqmate comment add --project <id|name> "…" --thread <threadId>`. On a doc mention the event carries `documentId`: `tasqmate 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.
|
|
130
|
+
5. **Acknowledge.** `tasqmate events ack <eventId>`, and only after the work is done.
|
|
131
|
+
|
|
132
|
+
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.
|
|
133
|
+
|
|
134
|
+
`examples/mention-runner.sh` in this package is a working reference for steps 1 and 5. It is an example, not a product.
|
|
135
|
+
|
|
136
|
+
## Threads
|
|
137
|
+
|
|
138
|
+
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.
|
|
139
|
+
|
|
140
|
+
Two event kinds reach you, and they mean different things:
|
|
141
|
+
|
|
142
|
+
- **`mention`** is a request addressed to you. Somebody typed your name. Read it and act.
|
|
143
|
+
- **`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 Tasqmate 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**).
|
|
144
|
+
|
|
145
|
+
Start from the context bundle rather than guessing which entity the thread is on:
|
|
146
|
+
|
|
147
|
+
```
|
|
148
|
+
tasqmate thread context <threadId>
|
|
149
|
+
```
|
|
150
|
+
|
|
151
|
+
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.
|
|
152
|
+
|
|
153
|
+
`tasqmate 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.
|
|
154
|
+
|
|
155
|
+
Reply into the thread with the id the event gave you, whichever entity it is on:
|
|
156
|
+
|
|
157
|
+
```
|
|
158
|
+
tasqmate comment add <taskKey> "…" --thread <threadId>
|
|
159
|
+
tasqmate comment add --project <projectName> "…" --thread <threadId>
|
|
160
|
+
```
|
|
161
|
+
|
|
162
|
+
Acknowledge both kinds the same way, with `tasqmate 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.
|
|
163
|
+
|
|
164
|
+
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.
|
|
165
|
+
|
|
166
|
+
## Release narratives
|
|
167
|
+
|
|
168
|
+
When a cycle closes, Tasqmate 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.
|
|
169
|
+
|
|
170
|
+
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.
|
|
171
|
+
|
|
172
|
+
The loop is:
|
|
173
|
+
|
|
174
|
+
1. **Listen.** `tasqmate events listen --wait 20`, the same listener as for mentions. Filter on `kind == "cycle_closed"` and read `.releaseId`.
|
|
175
|
+
2. **Read the release.** `tasqmate 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.
|
|
176
|
+
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.
|
|
177
|
+
4. **Save it.** `tasqmate 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.
|
|
178
|
+
5. **Acknowledge.** `tasqmate events ack <eventId>`, last, as always.
|
|
179
|
+
|
|
180
|
+
Three things to know before you write:
|
|
181
|
+
|
|
182
|
+
- **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.
|
|
183
|
+
- **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.
|
|
184
|
+
- **It is not a thread event.** Isolation and the loop caps govern agents waking agents in conversations; a cycle close is Tasqmate waking one agent. Neither applies, and your narrative wakes nobody.
|
|
185
|
+
|
|
186
|
+
`tasqmate release list --team ENG` is the timeline, newest first; `tasqmate release view <releaseId>` shows one in full; `tasqmate 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.
|
|
187
|
+
|
|
188
|
+
## Timesheet drafts
|
|
189
|
+
|
|
190
|
+
If a team picked you to draft timesheets, Tasqmate 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.
|
|
191
|
+
|
|
192
|
+
1. **Read the day.** `tasqmate 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.
|
|
193
|
+
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.
|
|
194
|
+
3. **Save it.** `tasqmate 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.
|
|
195
|
+
4. **Acknowledge.** `tasqmate events ack <eventId>`.
|
|
196
|
+
|
|
197
|
+
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.
|
|
198
|
+
|
|
199
|
+
## Routines
|
|
200
|
+
|
|
201
|
+
A person can give you routines: "every weekday at 09:00, triage what's new in ENG". At that time Tasqmate wakes you with one `routine` event whose `routine` is `{ id, name, prompt, teamId }`; everything else is null. Tasqmate never runs a model and does nothing else: the prompt is the work, and you do it with your own key, so your policy decides what you can change. Nothing fires while you are paused, and a server that was down fires a missed routine once, not once per missed day.
|
|
202
|
+
|
|
203
|
+
1. **Listen.** `tasqmate events listen --wait 20` and filter on `kind == "routine"`.
|
|
204
|
+
2. **Do the prompt.** Read `.routine.prompt`. `teamId`, when set, is the team the person meant; scope your reads to it.
|
|
205
|
+
3. **Acknowledge.** `tasqmate events ack <eventId>`.
|
|
206
|
+
|
|
207
|
+
Only owners and admins create, change, pause or run routines (Agent console › Routines); no policy can grant an agent `routine.*`, so you cannot schedule yourself.
|
|
208
|
+
|
|
209
|
+
## Docs
|
|
210
|
+
|
|
211
|
+
Doc bodies and task descriptions are Markdown. Mentions are links: `[ENG-12](tasq:task/<id>)` for a task, `[Title](tasq:doc/<id>)` for a doc; you can also write a bare `@ENG-12`. To edit a doc, `tasqmate doc view <doc>`, change the Markdown, and send the whole body back with `tasqmate doc update <doc> --file - --base-version <n>`: mentions survive the round trip, and a save after someone else's is refused rather than overwriting it. Writing docs needs `doc.*` in your policy (Full has it; Triage does not).
|
|
212
|
+
|
|
213
|
+
## Project updates
|
|
214
|
+
|
|
215
|
+
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.
|
|
216
|
+
|
|
217
|
+
You draft; a person sends. `tasqmate update draft` always writes a draft, and nothing an agent drafts goes to a client until a person reviews and sends it. `tasqmate 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. `tasqmate update list` shows drafts and sent updates, newest first, and the project's health is its latest sent update.
|
|
218
|
+
|
|
219
|
+
## Exit codes
|
|
220
|
+
|
|
221
|
+
| Code | Meaning |
|
|
222
|
+
| --- | --- |
|
|
223
|
+
| 0 | Success |
|
|
224
|
+
| 1 | Error; details on stderr |
|
|
225
|
+
| 2 | Usage error — a bad flag, or a `--mention` name matching no one or more than one member |
|
|
226
|
+
| 3 | Rate limited; the message says when to retry. `events listen` never exits here — it waits and continues |
|
|
227
|
+
| 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 |
|
|
228
|
+
|
|
229
|
+
## Working with other agents
|
|
230
|
+
|
|
231
|
+
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.
|
|
232
|
+
|
|
233
|
+
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.
|
|
234
|
+
|
|
235
|
+
Two limits stand behind an open team. After 5 agent messages in a row in one thread, Tasqmate 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.
|
|
236
|
+
|
|
237
|
+
Projects shared with a team that kept isolation stay isolated.
|
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Paul Cedrick Artigo
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
CHANGED
|
@@ -1,3 +1,165 @@
|
|
|
1
|
-
#
|
|
1
|
+
# tasqmate
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
Command-line client for [Tasqmate](https://github.com/pxlabz/tasq). Any agent that can run a shell command can use it; so can you.
|
|
4
|
+
|
|
5
|
+
```sh
|
|
6
|
+
npx tasqmate --help
|
|
7
|
+
# or
|
|
8
|
+
npm install -g tasqmate
|
|
9
|
+
tasqmate --help
|
|
10
|
+
```
|
|
11
|
+
|
|
12
|
+
The package installs two commands that do the same thing: `tasqmate`, and `tasq` for short.
|
|
13
|
+
|
|
14
|
+
### Coming from `@pxlabz/tasq-cli`
|
|
15
|
+
|
|
16
|
+
The CLI used to be published as `@pxlabz/tasq-cli`. Remove that first, because both packages provide the `tasq` command and npm refuses to install one over the other:
|
|
17
|
+
|
|
18
|
+
```sh
|
|
19
|
+
npm rm -g @pxlabz/tasq-cli && npm i -g tasqmate
|
|
20
|
+
```
|
|
21
|
+
|
|
22
|
+
Environment variables are now `TASQMATE_*` (`TASQMATE_API_KEY`, `TASQMATE_USER_TOKEN`, `TASQMATE_WORKSPACE`, `TASQMATE_API_URL`, `TASQMATE_CONFIG_DIR`). The old `TASQ_*` names still work when the new one is unset. The config moved from `~/.config/tasq` to `~/.config/tasqmate`, and the first run copies your sign-in across.
|
|
23
|
+
|
|
24
|
+
## Sign in
|
|
25
|
+
|
|
26
|
+
```sh
|
|
27
|
+
tasqmate auth login # magic-link code flow, stores a user token
|
|
28
|
+
tasqmate workspace use acme # default workspace
|
|
29
|
+
```
|
|
30
|
+
|
|
31
|
+
Agents skip the login and pass their key through the environment:
|
|
32
|
+
|
|
33
|
+
```sh
|
|
34
|
+
TASQMATE_API_KEY=tq_ag_… TASQMATE_WORKSPACE=acme tasqmate task list
|
|
35
|
+
```
|
|
36
|
+
|
|
37
|
+
## Commands
|
|
38
|
+
|
|
39
|
+
```
|
|
40
|
+
tasqmate workspace list | use <slug>
|
|
41
|
+
tasqmate task list | view <ref> | create | update <ref>
|
|
42
|
+
tasqmate task create|update … [--field <key=value>]…
|
|
43
|
+
tasqmate field list [--all]
|
|
44
|
+
tasqmate doc list [--filter <filter>] [--project <project>] [-q <text>] | view <doc>
|
|
45
|
+
tasqmate doc create <title> [--body <markdown> | --file <path|->] [--project <project>] [--team <identifier>]
|
|
46
|
+
tasqmate doc update <doc> [--title <title>] [--body <markdown> | --file <path|->] [--base-version <n>]
|
|
47
|
+
tasqmate doc link <doc> --task <ref> | --project <project> | --team <identifier>
|
|
48
|
+
tasqmate doc archive <doc> [--restore]
|
|
49
|
+
tasqmate comment add <ref> <body> [--reply-to <commentRef>] [--mention <name>]…
|
|
50
|
+
tasqmate comment add --doc <docId> <body> [--thread <threadId>] [--propose <text>]
|
|
51
|
+
tasqmate comment add <ref> <body> --attach <path>…
|
|
52
|
+
tasqmate file add <ref> <path>… [--inline] | list <ref> | remove <id>
|
|
53
|
+
tasqmate file add --doc <doc> <path>… [--inline] # --inline prints the Markdown line that shows it in the body
|
|
54
|
+
tasqmate file get <id> [--out <path>] [--force] [--link]
|
|
55
|
+
tasqmate time log <ref> <duration> [--day YYYY-MM-DD] [--note <text>] [--billable yes|no]
|
|
56
|
+
tasqmate time list <ref> | edit <entryId> [--duration] [--day] [--note | --no-note] [--billable] | delete <entryId>
|
|
57
|
+
tasqmate clients hours <client> [--month YYYY-MM] [--billable]
|
|
58
|
+
tasqmate clients billing <client>
|
|
59
|
+
tasqmate week [--day YYYY-MM-DD]
|
|
60
|
+
tasqmate timesheet request [--day YYYY-MM-DD] | show <draft> | log <draft> | dismiss <draft> | reply <draft> <message>
|
|
61
|
+
tasqmate timesheet save <draft> --line TASK=DURATION[=BILLABLE[=REASON]]… [--message <text>]
|
|
62
|
+
tasqmate clients close <client> --month YYYY-MM
|
|
63
|
+
tasqmate clients invoice <client> --month YYYY-MM [--ref <reference>]
|
|
64
|
+
tasqmate clients reopen <client> --month YYYY-MM
|
|
65
|
+
tasqmate events listen [--wait <seconds>] [--once]
|
|
66
|
+
tasqmate events ack <id>…
|
|
67
|
+
tasqmate project list | star <project> | unstar <project>
|
|
68
|
+
tasqmate project share <project> <guest> [--access view|comment] | access <project> <guest> <view|comment> | unshare <project> <guest>
|
|
69
|
+
tasqmate initiative list | create <name> | rename <initiative> <name> | archive <initiative>
|
|
70
|
+
tasqmate initiative link <initiative> <project> | unlink <initiative> <project>
|
|
71
|
+
tasqmate cycle current
|
|
72
|
+
tasqmate auth login | logout
|
|
73
|
+
```
|
|
74
|
+
|
|
75
|
+
`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.
|
|
76
|
+
|
|
77
|
+
`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:`.
|
|
78
|
+
|
|
79
|
+
`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; tasqmate 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.
|
|
80
|
+
|
|
81
|
+
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.
|
|
82
|
+
|
|
83
|
+
### Docs
|
|
84
|
+
|
|
85
|
+
A doc ref is its id, a link to it, or its exact title. `doc view` prints the body as Markdown, where mentions are links: `[ENG-12](tasq:task/<id>)` and `[Launch plan](tasq:doc/<id>)`. Send the whole body back with `doc update --file` and they survive; a bare `@ENG-12` in what you write also becomes a mention when it names a task you can see. The same holds for `task create|update --description`. `doc update` saves over the latest version unless `--base-version` names the one you read, in which case a save after someone else's is refused (exit 1, conflict).
|
|
86
|
+
|
|
87
|
+
### Mentions and replies
|
|
88
|
+
|
|
89
|
+
`--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.
|
|
90
|
+
|
|
91
|
+
`--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.
|
|
92
|
+
|
|
93
|
+
### Listening for mentions
|
|
94
|
+
|
|
95
|
+
`tasqmate 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:
|
|
96
|
+
|
|
97
|
+
```sh
|
|
98
|
+
TASQMATE_API_KEY=tq_ag_… TASQMATE_WORKSPACE=acme tasqmate events listen --wait 20 |
|
|
99
|
+
while read -r event; do handle "$event"; done
|
|
100
|
+
```
|
|
101
|
+
|
|
102
|
+
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.
|
|
103
|
+
|
|
104
|
+
Events stay deliverable until acknowledged: `tasqmate 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.
|
|
105
|
+
|
|
106
|
+
## For agents
|
|
107
|
+
|
|
108
|
+
Two files ship with the package for the agent side of this.
|
|
109
|
+
|
|
110
|
+
- **`.tasqmate-skill.md`** — a skill file written for a coding agent: what Tasqmate 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.
|
|
111
|
+
- **`examples/mention-runner.sh`** — a reference loop over `tasqmate events listen`. It exports `TASQMATE_EVENT_ID`, `TASQMATE_EVENT_KIND`, `TASQMATE_EVENT_TASK_KEY`, `TASQMATE_EVENT_TASK_ID`, `TASQMATE_EVENT_COMMENT_ID` and `TASQMATE_EVENT_MENTIONED_BY`, runs `$TASQMATE_AGENT_CMD` once per event, and acks only when that command exits 0 so a failure is redelivered rather than lost.
|
|
112
|
+
|
|
113
|
+
```sh
|
|
114
|
+
TASQMATE_API_KEY=tq_ag_… TASQMATE_WORKSPACE=acme \
|
|
115
|
+
TASQMATE_AGENT_CMD='claude -p "handle $TASQMATE_EVENT_TASK_KEY"' \
|
|
116
|
+
./node_modules/tasqmate/examples/mention-runner.sh --wait 20
|
|
117
|
+
```
|
|
118
|
+
|
|
119
|
+
Both are examples. Tasqmate stores and delivers the event; it never runs your agent.
|
|
120
|
+
|
|
121
|
+
## Keep an agent running on your machine (`tasqmate bridge`)
|
|
122
|
+
|
|
123
|
+
The bridge runs Claude, Codex or Hermes on your own computer as one Tasqmate agent, on your own sign-in. It long-polls the agent's wakes (mentions, replies, assignments), starts your harness in the project's folder for each one, and the agent answers in Tasqmate through the Tasqmate MCP server. Tasqmate never runs a model and never sees your Claude, ChatGPT or model-provider credentials.
|
|
124
|
+
|
|
125
|
+
```sh
|
|
126
|
+
claude auth login # or: codex login, or hermes setup (you sign in; the bridge never does)
|
|
127
|
+
tasqmate bridge setup --map "Homepage=~/code/homepage"
|
|
128
|
+
```
|
|
129
|
+
|
|
130
|
+
`setup` finds `claude`, `codex` and `hermes`, checks their sign-in with `claude auth status` / `codex login status` / Hermes's ACP handshake only, prints a code to approve on the pair page (an admin or the agent's owner picks the agent), keeps the agent key in the OS keychain (macOS Keychain, libsecret, Windows Credential Manager; a 0600 file when there is none), maps project folders and installs a background service (launchd, a systemd user unit, or a logon task). Claude runs through the Claude Agent SDK, which `setup` installs for the bridge alone on first use.
|
|
131
|
+
|
|
132
|
+
Hermes runs as `hermes acp` (the Agent Client Protocol) with your own Hermes setup: its tools are the ones your Hermes config gives ACP. The bridge answers what Hermes asks about: a file edit is allowed only inside the mapped folder, and a command Hermes flags as needing approval is refused, because nobody is there to approve it. What Hermes does not ask about (reading files, ordinary commands, web tools you enabled) runs as it would in your editor, so pick that setup with care, or give Hermes a profile with fewer tools.
|
|
133
|
+
|
|
134
|
+
| Command | What |
|
|
135
|
+
| --- | --- |
|
|
136
|
+
| `bridge setup` | Pair, map folders, install the service. `--harness claude\|codex\|hermes`, `--map project=folder` (repeat), `--no-service`, `--runs-per-hour`, `--timeout`, `--max-turns` |
|
|
137
|
+
| `bridge start` | Run in the foreground (what the service runs) |
|
|
138
|
+
| `bridge status` | Agent, harness sign-in, server presence, service, folders, limits |
|
|
139
|
+
| `bridge logs [-n 50] [-f]` | The bridge's log |
|
|
140
|
+
| `bridge map <project> [folder]` | Map a project to a folder (`--remove` to drop it); read on the next wake |
|
|
141
|
+
| `bridge unpair` | Revoke the key on the server, remove the service, key and config |
|
|
142
|
+
|
|
143
|
+
What a run may do: read and edit files inside the mapped folder, and use its Tasqmate tools. Shell commands, web access, files outside the folder, and `.git/`, `.claude/` and `.codex/` inside it are refused. A wake on a project with no folder runs in an empty scratch folder, so the agent can still answer but cannot touch code. One run at a time, at most `--runs-per-hour` (default 6) in any hour, each stopped after `--timeout` minutes (30) and `--max-turns` (40). A wake is acknowledged only after its run succeeds; a failed or interrupted run is offered again ten minutes later, up to three times.
|
|
144
|
+
|
|
145
|
+
## Configuration
|
|
146
|
+
|
|
147
|
+
| Source | Purpose |
|
|
148
|
+
| --- | --- |
|
|
149
|
+
| `TASQMATE_API_KEY` | Agent key (`tq_ag_…`); wins over a stored user token |
|
|
150
|
+
| `TASQMATE_USER_TOKEN` | User token (`tq_us_…`) without running `auth login` |
|
|
151
|
+
| `TASQMATE_WORKSPACE` | Default workspace slug |
|
|
152
|
+
| `TASQMATE_API_URL` | API origin; defaults to `https://tasqmate.pxlabz.com` |
|
|
153
|
+
| `TASQMATE_CONFIG_DIR` | Where the stored token lives; defaults to `$XDG_CONFIG_HOME/tasqmate` |
|
|
154
|
+
|
|
155
|
+
## Exit codes
|
|
156
|
+
|
|
157
|
+
| Code | Meaning |
|
|
158
|
+
| --- | --- |
|
|
159
|
+
| 0 | Success |
|
|
160
|
+
| 1 | Error (details on stderr) |
|
|
161
|
+
| 2 | Usage error — including an `--mention` name that matches no one or more than one member |
|
|
162
|
+
| 3 | Rate limited; the message includes when to retry. `events listen` does not exit here: it sleeps for `Retry-After` and carries on |
|
|
163
|
+
| 4 | The agent's policy denied the action |
|
|
164
|
+
|
|
165
|
+
Built as a single file on top of [`@tasqmate/sdk`](https://www.npmjs.com/package/@tasqmate/sdk). Node 20.3 or newer (for `AbortSignal.any`).
|