tx claim
Claim a task with a lease to prevent parallel collisions
Purpose
tx claim marks a task as being actively worked on by a specific worker. This prevents multiple agents from picking the same task and duplicating work. Claims use a lease-based model with automatic expiry.
Commands
| Command | Description |
|---|---|
tx claim <task-id> <worker-id> | Claim a task with a lease |
tx claim:release <task-id> <worker-id> | Release a claim |
tx claim:renew <task-id> <worker-id> | Renew the lease on a claim |
tx claim
Claim a task for a worker, preventing other workers from claiming it.
Usage
tx claim <task-id> <worker-id> [options]Arguments
| Argument | Required | Description |
|---|---|---|
<task-id> | Yes | Task ID (e.g., tx-a1b2c3d4) |
<worker-id> | Yes | Worker ID (e.g., worker-abc12345) |
Options
| Option | Description |
|---|---|
--lease <m> | Lease duration in minutes (default: 30) |
--json | Output as JSON |
--help | Show help |
Examples
# Claim with default 30-minute lease
tx claim tx-abc123 worker-def456
# Claim with 60-minute lease
tx claim tx-abc123 worker-def456 --lease 60
# JSON output
tx claim tx-abc123 worker-def456 --jsontx claim:release
Release a worker's claim on a task, allowing other workers to claim it.
Usage
tx claim:release <task-id> <worker-id> [options]Arguments
| Argument | Required | Description |
|---|---|---|
<task-id> | Yes | Task ID |
<worker-id> | Yes | Worker ID that holds the claim |
Options
| Option | Description |
|---|---|
--json | Output as JSON |
--help | Show help |
Examples
tx claim:release tx-abc123 worker-def456tx claim:renew
Extend the lease on an existing claim. Use this for long-running tasks to prevent the claim from expiring.
Usage
tx claim:renew <task-id> <worker-id> [options]Arguments
| Argument | Required | Description |
|---|---|---|
<task-id> | Yes | Task ID |
<worker-id> | Yes | Worker ID that holds the claim |
Options
| Option | Description |
|---|---|
--json | Output as JSON |
--help | Show help |
Limits
- Maximum 10 renewals per claim
- Fails if the lease has already expired
- Fails if no active claim exists for this task and worker
Examples
tx claim:renew tx-abc123 worker-def456Use Case: Parallel Agent Execution
Without claims, parallel agents might pick the same task:
# Problem: Both agents pick the same task
Agent1: tx ready --limit 1 → tx-abc123
Agent2: tx ready --limit 1 → tx-abc123 # Same task!With claims:
# Solution: Claims prevent collision
Agent1: tx claim tx-abc123 worker-1 # Success
Agent2: tx claim tx-abc123 worker-2 # Fails - already claimedParallel Agent Loop
#!/bin/bash
WORKER_ID="worker-$$"
while true; do
TASK=$(tx ready --json --limit 1 | jq -r '.[0].id // empty')
[ -z "$TASK" ] && break
# Try to claim - skip if another worker got it
tx claim "$TASK" "$WORKER_ID" || continue
# Work on the task
claude "Your task is $TASK. Run 'tx show $TASK' for details."
# Complete and release
tx done "$TASK"
doneBehavior
- Claiming creates a lease with an expiry time
- Expired leases allow other workers to claim the task
- Completing a task (
tx done) does not require releasing the claim first - Long tasks should periodically renew with
tx claim:renew