Taskgerts

A Taskgert is a batch of tasks of a project with a target: a final objective that is checked once every task is done. It is the unit an agent is asked to run: "run TGT-G1" means plan the batch, work its tasks in order, then prove the target.

Lifecycle

Status	Meaning
DRAFT	Tasks are being gathered. Anyone with taskgert.manage can add or remove tasks.
PLANNED	The order and the target are agreed (it needs both a target and at least one task).
RUNNING	Started: the clock runs. Phase tasks until every task is done, then phase target.
DONE	The target was carried out, with a verdict — PASSED or FAILED — and a report.
CANCELLED	Abandoned. Its tasks are left as they are.

Rules worth knowing:

• A task belongs to one Taskgert at a time. Deleting a Taskgert frees its tasks.
• A Taskgert cannot finish while any of its tasks is open: the target always comes last.
• While it runs, tasks already completed stay in it — the work delivered belongs to the run.
• Each Taskgert has a key: the project key, G and a number — TGT-G1, TGT-G2… — never confused with task keys (TGT-1).

The plan

The plan is the tasks in the order to run them, each with an optional complexity in Fibonacci points (1, 2, 3, 5, 8, 13), plus the reasoning (plan, Markdown). Agents propose it — dependencies first, then risk and value, priority breaking ties — and wait for a person to approve it before recording it with plan_taskgert. The tasks can be given one by one or as whole epics (TGT-E1). The order should follow the tasks' dependencies (link_tasks). Either way the run enforces them: a task is not handed out while what it depends on is open, and an Idea is not handed out until it has been refined into a TASK. If no target was chosen, the agent proposes one too; a target written through a bot token is marked as written by an agent.

Parallel runs

A Taskgert can let several agents work at once. Its run settings, given on create_taskgert or plan_taskgert:

Setting	Meaning
maxAgents	How many agents may hold a task at the same time (1–8). 1, the default, runs one at a time.
evidence	Proof of the target to attach at the end: NONE, SCREENSHOT (one change), VIDEO (several).
tokenBudget	Tokens the agents may use in all. Once spent, no new task can be claimed.
autoMove	Claims and DONE releases move the task across the board (default on). Off: people move cards.

Each task of the plan can name the areas of the code it touches — contract, migrations, api:files, web:board, mcp, docs… Areas decide what may run together:

• two tasks that share an area never run at once;
• contract and migrations run alone: nothing else runs beside them;
• a task with no areas also runs alone, since nobody knows what it touches.

Agents coordinate through claims:

1. claim_next_task (with the agent's label, e.g. worker-2) gives the first task of the plan that is open, held by no one, and shares no area with the work in progress. If nothing can be taken now, it says why; wait and ask again. Asking again with the same label answers the claim already held. With autoMove on, a task still in the first column moves into the first active column, so its worked time starts now.
2. A claim is a lease (10 minutes by default): heartbeat_claim extends it while the agent works. A lease that lapses frees its task for another agent, and the late heartbeat is refused.
3. release_task ends it — DONE once delivered, or ABANDONED to hand it back — with the tokens and the time used. With autoMove on, DONE moves the task into its done column, completing it; an abandoned task stays where it is for the next agent.

Claims are decided one at a time on the server, so two agents asking at the same instant never get the same task. The dashboard shows who works on what, live, and the metrics add a usage section: tokens in and out, agent time, per agent, and parallelism — agent time per elapsed time (2 means two agents busy all along).

Running a Taskgert in parallel

With an agent such as Claude Code, one agent leads and launches workers: one sub-agent per slot (maxAgents), each in its own git worktree. Every worker loops — claim the next task, work it on its branch, keep the lease alive, release it with its usage — until nothing is left. The lead merges the finished branches into the main line one at a time and runs the checks after each, so two changes never land together; a conflict becomes a fix on that task. Workers only get their task's context, which keeps tokens down; the token budget stops new claims once spent.

The taskgert-run procedure does all of this when maxAgents is above 1: ask your agent to "run TGT-G1" and approve the plan, with its waves.

Evidence

With evidence set, the target ends with proof that anyone can watch: a screenshot for a single change, a video for several. It is recorded in a real browser running in Docker (the official Playwright image), so it looks the same on every machine, and attached to the Taskgert, where the dashboard shows it.

The agent writes a scenario from the target — the steps a person would take to see it met:

{
  "signIn": { "email": "[email protected]" },
  "steps": [
    { "caption": "Two agents worked at once" },
    { "goto": "/projects" },
    { "click": { "role": "link", "name": "Taskgert launch" } },
    { "click": { "role": "link", "name": "Taskgerts" } },
    { "waitFor": "Target met" },
    { "pause": 2000 }
  ]
}

Step	Does
goto	Opens a path of the app (or a full URL).
click	Clicks visible text, or an element by role and name (button, link, tab, …).
fill	Types into the field with that label.
press	Presses a key, such as Enter.
waitFor	Waits for a text to appear (15 s at most): the proof that something happened.
pause	Lets the viewer look, up to 10 s.
caption	Shows a caption over the page — it stays across pages until changed; "" hides it.
scroll	Scrolls to the top, the bottom, or a pixel offset.

signIn uses the development login, so it works on a local stack. baseUrl points the scenario elsewhere (the local web app, http://localhost:3100, by default); viewport changes the size (1280×720 by default).

Then, from the repository:

TASKGERT_MCP_TOKEN=… pnpm evidence TGT-G1 scenario.json            # the Taskgert's own setting
TASKGERT_MCP_TOKEN=… pnpm evidence TGT-G1 scenario.json --mode video --out evidence --no-upload

It starts the browser container (bound to this machine only; pages on localhost reach the stack running here), signs in, follows the steps, records, uploads the file with attach_taskgert_evidence, and stops the container. If a step fails it stops there, says which step and why, and saves what the page looked like (failure.png). Docker must be running.

attach_taskgert_evidence also takes any screenshot or recording (PNG, JPEG, WebP, WebM, MP4) made another way.

Time metrics

Every column change of a task is recorded with the stage it entered: QUEUED (the board's first column), ACTIVE (any other column that is not done) or DONE. The stage is judged when the task moves, so reordering or renaming columns later never rewrites history. From that history:

Metric	Definition
Started	The first move out of the first column (or the creation, if created past it).
Worked	Time spent in active columns, every visit added up; the current visit counts up to now.
Lead time	Creation to completion.
Cycle time	Started to completion.
Changes	Column changes after the creation.

And for a Taskgert:

Metric	Definition
Elapsed	From its start to its finish — or to now while it runs.
Delivered	Tasks and points completed, out of the total.
Worked	The worked time of all its tasks.
Mean / median	Worked time per completed task.
Mean cycle	Cycle time per completed task.
Points per hour	Points delivered per hour elapsed.
Slowest	The completed task with the most worked time.
In progress	Tasks in an active column right now.

Because worked time comes from the board, it is only as true as the board: move a task into an active column when work starts and out of it when it stops. In a run with autoMove (the default), claims and releases do this on their own; otherwise agents move the cards as part of running a Taskgert.

Running one with an agent

Ask your agent to run it — for example "Run TGT-G1". With the taskgert-run procedure it:

1. reads the Taskgert (get_taskgert) and its tasks;
2. proposes the order, the complexities and, if missing, the target — and waits for your approval;
3. records the plan (plan_taskgert) and starts it (start_taskgert);
4. works each task in order, moving it across the board as it goes — or, in a parallel run, has each agent claim, work and release tasks until none is left;
5. once all are done, carries out the target, attaches the evidence if asked for, and closes the Taskgert (finish_taskgert) with the verdict and a report;
6. sums up the metrics.

Asking for a run from Telegram

Linked to the Taskgert Telegram bot, you can ask from your phone: /run, optionally with a note ("/run the Telegram ones first"). The request waits until an agent session picks it up (list_run_requests). The agent:

1. groups the project's open tasks into one or more Taskgerts;
2. plans them;
3. proposes them (propose_run), with a short summary of why they are grouped so.

The proposal reaches you on Telegram with Approve and Reject. When you approve, the agent starts them; when you reject, the proposed Taskgerts are cancelled.

The project's Taskgerts tab shows all of this live: progress, the plan, a timeline of every task, and the metrics as they move.