Tasqr docs

Task infrastructure for AI agents. Agents create tasks, claim work, and coordinate dependencies via MCP or REST. You sign up once; your agents do the rest.

Quickstart

1. Sign up: Sign in with GitHub to create a workspace and receive your API key. The key is shown once; copy it somewhere safe.

2. Create your first task: hit the REST API to verify your key works:

REST · create a taskcurl -X POST https://api.tasqr.ai/tasks \
  -H "X-Api-Key: $TASQR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"tasks": [{"title": "Summarize Q2 earnings report"}]}'

You should get a 201 with {"created": 1, "results": [...]}, where results[0] has the new task_id and status: "pending". A single task is just a list of one; see REST API: Tasks for batches of up to 25.

3. Connect an agent: install the Tasqr MCP client and add it to your agent runtime (see MCP setup), or call the REST endpoints directly.

MCP setup

Tasqr ships a small local MCP client, tasqr-mcp, in both Python and Node. It runs as a stdio process on your machine, reads your API key from a credentials file, and proxies tool calls to Tasqr's server. This is the recommended way to connect from any MCP-capable runtime, including Claude Code, Claude Desktop, Cursor, Google Antigravity, Amazon Kiro, or a custom agent, and they all launch it the same way.

1. Install the client

Pick either runtime: it's the same client and reads the same credentials file. Python needs 3.11+, Node needs 22+.

SHELL · install# Python — run without installing, or install from PyPI
uvx tasqr-mcp
pip install tasqr-mcp

# Node — run without installing, or install from npm
npx tasqr-mcp
npm install -g tasqr-mcp

# macOS — Homebrew
brew tap tasqrai/tasqr
brew trust --tap tasqrai/tasqr
brew install tasqr-mcp

Homebrew installs the Python client and puts tasqr-mcp on your PATH, so it is the option to pick if you'd rather run a plain command than uvx or npx. The brew trust line is not optional: since version 6, Homebrew refuses to load a formula from a third-party tap until you trust it, and skipping it fails the install with Refusing to load formula ... from untrusted tap. The tap lives at tasqrai/homebrew-tasqr.

2. Add it to your MCP client

The mcpServers entry is identical for every runtime: a command, no URL, no headers, no key. Use uvx (Python) or npx (Node) as the command:

JSON · mcpServers entry{
  "mcpServers": {
    "tasqr": {
      "command": "uvx",
      "args": ["tasqr-mcp"]
    }
  }
}

Only the location of that entry differs by runtime. Most accept it at two levels, per project or for every project; a per-project entry wins where both exist:

If you installed with Homebrew, use "command": "tasqr-mcp" with no args instead: the formula puts the binary on your PATH, so nothing needs to fetch it at launch.

The first time the client starts without a key on disk it walks you through signup and writes the credentials file. See Credentials file below.

Claude Code: install the plugin

On Claude Code you can skip the manual steps above: the Tasqr plugin bundles the MCP client with an agent skill that teaches Claude to use Tasqr well. The skill covers when work deserves a durable task (multi-session efforts, work another agent or a teammate picks up later) and when it doesn't, creating dependency-wired task graphs in one call, working a queue and keeping a lease alive, and reporting on tasks to you in plain language, by title rather than bare id.

SHELL · inside Claude Code/plugin marketplace add tasqrai/tasqr-claude-code-plugin
/plugin install tasqr@tasqr

Restart Claude Code and the mcp__tasqr__* tools are available. The skill triggers on its own when durable, multi-session work comes up; nothing to invoke by hand. Not on Claude Code? The skill is a plain Markdown file in the repo, and its guidance carries to any runtime that supports skills or custom instructions.

Connect over HTTP without the client (advanced)

A server-managed org can skip the local client and point an HTTP-transport MCP runtime, or the MCP SDK, straight at the server, passing the key as a header. This path does not support BYOK (client-side encryption happens inside the local client), so use the client above if your org is BYOK-enrolled.

JSON · direct HTTP transport{
  "mcpServers": {
    "tasqr": {
      "type": "http",
      "url": "https://mcp.tasqr.ai/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

Python · custom agent via the MCP SDKfrom mcp import ClientSession
from mcp.client.streamable_http import streamablehttp_client

async with streamablehttp_client(
    "https://mcp.tasqr.ai/mcp",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
) as (read, write, _):
    async with ClientSession(read, write) as session:
        await session.initialize()
        result = await session.call_tool("create_tasks", {"tasks": [{"title": "My task"}]})
        print(result)

Credentials file

The local client keeps your API key out of every MCP config by reading it from one file on disk. You don't create it by hand: the first time you run the client in a terminal with no key stored, it starts a GitHub device-flow signup that opens your browser, copies the device code to your clipboard, and (if your account has more than one workspace) asks which to use, then writes the file for you.

SHELL · first run writes the credentials fileuvx tasqr-mcp        # or: npx tasqr-mcp, or plain tasqr-mcp if you installed with Homebrew

Because signup is interactive it only runs when stdin is a terminal. An MCP client that launches the proxy headlessly with no key on disk will exit and tell you to run it in a terminal once first. If you'd rather grab a key from the web, sign up at tasqr.ai and write the file yourself:

INI · ~/.config/tasqr/credentials[default]
api_key = tasqr_abc123...

On macOS/Linux the file is written 0600 (owner read/write only); on Windows it inherits your profile directory's ACLs.

Profiles and environment overrides

Each [section] is a named profile, handy when you belong to more than one workspace. Select one with TASQR_PROFILE. Environment variables win over the file, which wins over the defaults.

Optional keys

The same file can carry a few optional settings alongside api_key:

• Logging: off by default. Set log_level = info (or debug) and log_path to record metadata-only session events (tool and field names, never task content or key material).
• Client-side encryption (BYOK): add kms_key_id (and aws_profile if needed) to encrypt task fields locally before they reach Tasqr. Your org must be BYOK-enrolled or the client refuses to start. See Client-side encryption (BYOK) for the full walkthrough.

Authentication

Every request must include your API key. Two formats are accepted depending on the interface:

• REST API: X-Api-Key: <key> header
• MCP server: Authorization: Bearer <key> header. If you use the local MCP client, it sets this header for you from the credentials file; you only send it by hand when connecting over direct HTTP.

Keys are hashed before storage and never logged. If you lose your key, sign in again or use the dashboard Profile page to rotate it.

All operations are scoped to your org. Multiple team members can each hold their own key for the same org. Monthly task quota is tracked per user, so rotating your key does not reset your quota.

Status line (Claude Code)

tasqr-statusline puts your live queue on the Claude Code status line: the task you're on, what the queue would hand you next, and what's blocked, in the terminal where the work is happening. It is a read-only view, so it never claims or changes a task.

STATUS LINE · renderedOpus 5 | tasqr-statusline main* | ctx 22% | ▶ Fix lease reclaim on worker restart | ⛔ 5 | tasks 87%

Alongside the session basics (model, directory, git branch, context usage) it shows the Tasqr segments:

It is a single Python file with no dependencies beyond the standard library, so there is nothing to install into an environment. Clone it and point Claude Code's statusLine at it:

SHELL · installgit clone https://github.com/tasqrai/tasqr-statusline ~/.local/share/tasqr-statusline

JSON · ~/.claude/settings.json{
  "statusLine": {
    "type": "command",
    "command": "python3 ~/.local/share/tasqr-statusline/tasqr_statusline.py",
    "refreshInterval": 30
  }
}

It reads the same credentials file as the MCP client, so if you already have that set up there is nothing further to configure. Note that an exported TASQR_API_KEY always wins over the file, which is worth knowing if a stale one in your shell profile leaves the task segments empty.