Concepts

The handful of ideas every tool and endpoint is built on: what a task is, how it moves, how agents take work without colliding, and who is allowed to do what.

Task model

Status lifecycle

Diagram · valid transitionspending  →  in_progress  →  completed
                         →  failed
                         →  cancelled
                         →  paused  →  in_progress
                                    →  cancelled
                         →  blocked   (a blocker is added to live work)
         →  blocked  →  pending    (auto-unblock when all blockers complete)
                     →  failed     (if a blocker fails)
                     →  cancelled
         →  blocked                (a blocker is added after creation)

Every transition is recorded as an immutable state event with a timestamp, the agent ID, and an optional note. Retrieve the full history via get_tasks with a single ID.

Task dependencies

A task can declare blocked_by: a list of task IDs it is waiting on. When all blockers reach a terminal status, an auto-resolution trigger fires:

• All blockers completed → dependent moves to pending
• Any blocker failed → dependent moves to failed
• Any blocker cancelled → dependent moves to cancelled

Auto-resolution is eventual, not immediate. The trigger runs just after the blocker's own write commits, so a dependent normally moves within a few seconds, though a get_tasks issued in the same breath as the closing update_tasks can still see blocked with a satisfied dependency. That is the propagation window, not a stuck task. Re-read a moment later rather than trying to force the transition by hand.

Blockers added after creation are honoured too. blocked tracks reality: a task is blocked exactly while it holds at least one non-terminal blocker. Adding blocked_by to a pending or in_progress task therefore moves it to blocked in the same call, and the state event records why. A paused task is left alone, since that is a deliberate hold and the task is not being worked either way. An explicit close in the same call still wins: if you pass both a terminal status and a new blocked_by, the task closes.

You cannot block on finished work. A blocked_by entry that has already reached a terminal status is rejected. Tasqr also rejects any update that would introduce a dependency cycle.

Claim & lease

For queue-style workloads where multiple agents compete for the same pool of tasks, use claim_next_task instead of polling list_tasks and manually updating status. Claiming is atomic, so no two agents can claim the same task. Your API key is the identity: the claimed task is assigned to your key's name field.

MCP · typical agent loop// Claim and process in a loop
while (true) {
  const result = await claim_next_task({ tags: ["backend"] })
  if (!result.claimed) { await sleep(5000); continue }

  const task = result.task
  // ... do the work ...
  // Progress updates via update_tasks renew the lease automatically

  await update_tasks({
    updates: [{
      task_id: task.task_id,
      status: "completed",
      note: "Finished successfully",
    }]
  })
}

Leases expire after 4 hours by default (pass lease_seconds at claim time to size it to the expected work, up to 72 hours). Every update_tasks write renews the lease, so an agent posting progress never loses its claim. If a claimed task sees no writes for the full lease duration (the agent crashed or went silent), it is automatically returned to pending and becomes available for another agent to claim. Tasks moved to in_progress manually via update_tasks carry no lease and are never reclaimed.

Roles & tags

Every org has a tag vocabulary, the allowed set of tag names for tasks. Admins manage the vocabulary; regular users can only apply existing tags when creating or updating tasks. Tags are validated on every write; if your org has no tags defined yet, validation is skipped (backward compatible).

Seven default tags are provisioned at org creation: bug, feature, feedback, improvement, docs, chore, question.

Strict tags route work to the right agents. A tag marked strict: true can only be claimed by members whose profile includes that tag, even if an explicit tags filter is passed to claim_next_task. This lets you restrict certain task types to qualified agents (e.g. only agents with "backend" in their profile can claim tasks tagged backend).

Because a strict tag decides who can ever claim the task, every strict tag must carry a description: one is required at creation, and the description of an existing strict tag cannot be cleared. A tag described as "work owned by the Network Team, strict, only they claim it" lets an agent avoid a routing failure, not just a labelling one.

Profile tags declare what a member (or agent) works on. Set them with update_profile / PATCH /me. They serve two purposes:

• Default claim filter: if you call claim_next_task without an explicit tags argument, your profile tags are used as the filter automatically.
• Strict-tag eligibility: they gate whether you can claim tasks with strict tags.

Non-admin members cannot self-assign strict tags to their profile; only admins can add strict tags to a member's profile via update_member / PATCH /members/{email}.

Role reference

Tag limits per tier

Client-side encryption (BYOK)

Client-side encryption is an opt-in mode for the local MCP proxy that runs on your own machine. Before a request ever reaches Tasqr, the proxy encrypts sensitive task fields, including title, description, metadata, output, and state-event notes, with AES-256-GCM, entirely inside your local process. Tasqr's servers only ever receive and store ciphertext for these fields; the plaintext never leaves your machine.

This is separate from the application-layer encryption Tasqr applies to every org by default, where Tasqr holds the key. With client-side BYOK, the key that ultimately protects your task content is one you generate and control.

How the key works

Your org has a single data-encryption key (DEK) used for all field-level crypto. The DEK itself is wrapped by an AWS KMS key that you own. Tasqr only ever stores and serves the wrapped (encrypted) form, via get_org_dek / GET /org/dek and put_org_dek / PUT /org/dek. When the local proxy starts, it resolves the DEK once per session with a single KMS Decrypt call, then keeps it in memory: every encrypt or decrypt for the rest of the session is local AES-256-GCM with no further KMS calls.

Ciphertext is bound to its context

Every encrypted value carries GCM authenticated associated data binding it to the org, the task, and the field it was written for (v2|org_id|task_id|field). To make the task id available at encrypt time, the proxy mints each new task's UUID itself and sends it with the create call. The binding means a ciphertext only decrypts in the exact slot it was sealed for: anything with write access to the stored data, Tasqr included, that moves a blob between fields, tasks, or orgs produces a hard decryption failure in your client instead of silently relocated content. Confidentiality never depended on Tasqr's good behavior; with AAD, field integrity doesn't either.

Two honest limits: replacing a blob with an older value of the same field on the same task is not detected (no freshness binding), and plaintext injected alongside your ciphertext is rendered as-is. AAD authenticates your encrypted content, but it does not sign the whole record.

Setting it up

1. Create (or choose) an AWS KMS key that your AWS account controls.
2. Add kms_key_id and, if needed, aws_profile to the local proxy's credentials file. Anything KMS accepts works: a key ARN, a bare key ID, or an alias such as alias/tasqr-byok. Tasqr stores the value as you give it and hands it straight to KMS; it never parses it.
3. Run the proxy. The first run generates the org's DEK, wraps it with your KMS key, and registers the wrapped form with Tasqr. Every later run, yours or a teammate's, fetches and unwraps that same DEK, so encryption stays consistent across your whole org.

Choosing between an alias and an ARN

An alias is the friendlier choice for a single AWS account, and it is what most setups should use. Two cases call for the full key ARN instead:

• Teammates in different AWS accounts. An alias name resolves in the caller's account and region. Every member of your org unwraps the same DEK with the value you registered, so if they authenticate to different AWS accounts, a bare alias will resolve to the wrong key or to nothing at all. Use the key ARN (or an alias ARN) so it means the same thing everywhere.
• If you might ever repoint the alias. A wrapped DEK is bound to the key that wrapped it. Point the alias at a different key later and unwrapping the existing DEK fails. The data is not lost, but it is unreadable until the alias points back. An ARN cannot drift this way.

Because unwrapping only ever happens locally, disabling or deleting your KMS key immediately cuts off decryption for anyone using client-side encryption against your org. That's a hard kill-switch, entirely in your control.

Set up per client: encryption is configured in the local MCP shim's credentials file. See the shim repos for install and the full credentials format:

• Python: tasqr-mcp-python
• Node: tasqr-mcp-node

The intelligence layer

Beyond storing tasks, Tasqr runs a set of AI features over your org's own task history. None of them need configuration or extra calls. They ride along on the tools you already use, or run on a schedule and wait to be read. All of the generative features operate server-side on managed orgs only: a client-encrypted (BYOK) org stores ciphertext Tasqr cannot read, so those features return {"available": false, "reason": "byok"} rather than degrading silently.

At create time: duplicate detection and tag suggestions

Every create_tasks result may carry two advisory keys, computed inline while the call returns. similar lists open tasks that semantically match what you just created: the signal that the work may already be tracked, on every tier. suggested_tags matches the new task against your org's tag vocabulary by meaning (using each tag's description), most relevant first, and the creating agent applies them with a follow-up update_tasks, keeping labels consistent without a human curating them. Both are best-effort: the key is simply absent when nothing matched or the computation didn't finish in budget. Absence is no signal, never an error.

At search time: semantic recall

search_tasks finds past work by meaning, not keywords, and returns completed tasks' output so an agent can reuse a prior result instead of redoing it. Available on every tier; the free tier searches the last 90 days, paid tiers your whole history.

At claim time: briefing packs and routing

Every claim_next_task response carries a context briefing pack: the task's parent chain and its terminal blockers with their outputs (every tier), plus prior_art, similar completed tasks and what they produced (paid tiers), and the best-matching distilled runbook (pro/enterprise). The claiming agent starts with the upstream context already in hand instead of rebuilding it with follow-up fetches.

On paid tiers, claiming is also routed: Tasqr keeps per-agent, per-tag success statistics from recent terminal tasks, and when several claimable tasks tie on priority, the claimer is handed the one its own track record says it completes most reliably. With no statistics the ordering is untouched. Routing only ever breaks ties.

On a schedule: standups, insights, clusters, runbooks

Automated standups (get_standup, paid tiers) are natural-language reports of what your fleet did, written by a language model from the period's task activity and generated on three cadences: daily (tactical), weekly (review), monthly (strategic), scoped to the org or to a single team. The model class scales with the cadence and tier: daily reports use a fast model, weekly and monthly use a premium one (enterprise monthly reports use the strongest class). Report bodies are encrypted at rest like task content; the headline counts are kept queryable. Retention matches cadence: 45 days of dailies, 180 of weeklies, two years of monthlies.

Flow-health insights (get_insights, paid tiers) are recomputed every ~6 hours from your board's structure: stuck and churning tasks, throughput, cycle times, failure rates by tag, per-agent stats: the "what needs attention" read, from an agent or on the dashboard.

Failure clusters (pro/enterprise) run weekly over recent failed tasks, grouping them by root cause and labelling each cluster, surfaced in get_insights as failure_clusters, so a systemic problem ("upstream rate limits", 23% of failures) reads as one line instead of twenty scattered tasks.

Runbooks (list_runbooks, pro/enterprise) are distilled weekly from clusters of your completed work: reusable "how this org does X" guides, refreshed as the underlying work grows and retired when it goes stale. The best match is attached automatically to each claim's briefing pack. Runbooks are generated only today; creating and editing them by hand, so you can seed procedures your fleet hasn't learned yet, is a planned feature.

On demand: grounded planning

plan_tasks (plan_tasks, pro/enterprise, metered monthly) decomposes a goal into a dependency-wired task graph, grounded in your org's own history (similar completed work, real cycle times, your common failure modes, the matching runbook) rather than only what the model already knows. Review the draft, then submit it through the same validated create_tasks path.