Skip to main content
Tracer automatically assigns agents to issues when they change the status to in_progress. This provides instant visibility into who’s working on what without requiring manual assignee management.

​
How Auto-Assignment Works

When an agent updates an issue status to in_progress, Tracer automatically sets the assignee: 
# Agent starts work
tracer --actor claude-1 update bd-1 --status in_progress

# Now claude-1 is automatically assigned to bd-1
tracer show bd-1
# Assignee: claude-1
Auto-assignment only happens when the issue has no existing assignee. If an issue is already assigned, the assignee won’t change automatically.

​
Auto-Assignment Logic

The assignment logic follows this flow:
1

Status changes to in_progress

An agent updates an issue with --status in_progress
2

Check current assignee

Tracer checks if the issue already has an assignee
3

Assign if empty

If assignee field is empty, set it to the current actor
4

Keep if set

If assignee is already set, don’t change it

​
Source Code Reference

From src/cli/update.rs:60-67: 
// Auto-set assignee if status changes to in_progress and no assignee specified
let assignee = if args.assignee.is_some() {
    args.assignee
} else if args.status == Some(Status::InProgress) && issue.assignee.is_empty() {
    Some(actor.to_string())
} else {
    None
};

​
Actor Identification

The actor is determined in order of precedence:
Highest priority - explicitly specified:
tracer --actor claude-1 update bd-1 --status in_progress
# Assignee: claude-1
For multi-agent environments, always set TRACE_ACTOR explicitly to avoid all agents using the same $USER value.

​
Manual Assignment

You can also manually assign issues without changing status: 
# Assign directly
tracer update bd-1 --assignee cursor-2

# Or combine with status change
tracer update bd-1 --status in_progress --assignee gpt-4
Manual assignment takes precedence over auto-assignment.

​
Viewing Assignees

Assignees are visible in multiple commands:

​
In Issue Lists

tracer list --status in_progress

bd-1 Implement auth [P1, in_progress, Assignee: claude-1]
bd-2 Write tests [P1, in_progress, Assignee: cursor-2]
bd-3 Fix bug [P0, in_progress, Assignee: gpt-4]

​
In Issue Details

tracer show bd-1

bd-1 Implement authentication API
Status: in_progress
Assignee: claude-1

Recent comments:
  claude-1 (15 min ago): "Started working on the API"

​
In JSON Output

tracer show bd-1 --json

{
  "id": "bd-1",
  "title": "Implement authentication API",
  "status": "in_progress",
  "assignee": "claude-1",
  "priority": 1,
  "issue_type": "feature",
  "created_at": "2025-10-15T10:00:00Z",
  "updated_at": "2025-10-15T10:30:00Z"
}

​
Filtering by Assignee

Find all issues assigned to a specific agent: 
# Human-readable output
tracer list --assignee claude-1

# JSON for scripting
tracer list --assignee claude-1 --json

​
Finding Unassigned Work

# Issues with no assignee
tracer list --status open --json | jq '.[] | select(.assignee == "")'

# Ready work that's unassigned
tracer ready --json | jq '.[] | select(.assignee == "")'

​
Assignment Patterns

​
Self-Assignment on Start

The most common pattern - agent claims work: 
export TRACE_ACTOR="claude-1"

# Find ready work
WORK=$(tracer ready --limit 1 --json)
ISSUE_ID=$(echo $WORK | jq -r '.[0].id')

# Claim it (auto-assigns)
tracer update $ISSUE_ID --status in_progress

# Verify assignment
tracer show $ISSUE_ID | grep Assignee
# Assignee: claude-1

​
Pre-Assignment

Assign work to an agent before they start: 
# Coordinator assigns work
tracer update bd-1 --assignee claude-1
tracer update bd-2 --assignee cursor-2
tracer comment bd-1 "@claude-1 please start on this"
tracer comment bd-2 "@cursor-2 this is ready for you"

# Agents start work
export TRACE_ACTOR="claude-1"
tracer list --assignee claude-1
tracer update bd-1 --status in_progress

​
Reassignment

Change assignee when handing off work: 
# Agent 1 hits a blocker
export TRACE_ACTOR="claude-1"
tracer update bd-1 --status blocked
tracer comment bd-1 "Blocked on OAuth, need help"

# Reassign to agent 2
tracer update bd-1 --assignee cursor-2
tracer comment bd-1 "@cursor-2 can you take over the OAuth integration?"

# Agent 2 picks it up
export TRACE_ACTOR="cursor-2"
tracer update bd-1 --status in_progress
tracer comment bd-1 "Starting on OAuth integration"

​
Multi-Agent Coordination

Assignees enable agents to see who’s working on what: 
# Initialize and create issues
tracer init
tracer create "Implement API" -p 1 -t feature
tracer create "Write tests" -p 1 -t task
tracer create "Update docs" -p 2 -t task

# Three agents check for work
export TRACE_ACTOR="claude-1"
tracer ready --limit 1
# Sees bd-1, bd-2, bd-3

export TRACE_ACTOR="cursor-2"
tracer ready --limit 1
# Sees bd-1, bd-2, bd-3

export TRACE_ACTOR="gpt-4"
tracer ready --limit 1
# Sees bd-1, bd-2, bd-3

# Agent 1 claims bd-1
export TRACE_ACTOR="claude-1"
tracer update bd-1 --status in_progress
# Auto-assigned to claude-1

# Agent 2 checks and sees bd-1 is taken
export TRACE_ACTOR="cursor-2"
tracer list --status in_progress
# bd-1 [in_progress, Assignee: claude-1]

# Agent 2 claims bd-2 instead
tracer update bd-2 --status in_progress
# Auto-assigned to cursor-2

# Agent 3 claims bd-3
export TRACE_ACTOR="gpt-4"
tracer update bd-3 --status in_progress
# Auto-assigned to gpt-4

# Check overall status
tracer list --status in_progress
# bd-1 [in_progress, Assignee: claude-1]
# bd-2 [in_progress, Assignee: cursor-2]
# bd-3 [in_progress, Assignee: gpt-4]

​
Clearing Assignees

Remove an assignee by setting to empty string: 
# Clear assignee
tracer update bd-1 --assignee ""

# Verify it's cleared
tracer show bd-1 --json | jq '.assignee'
# Output: ""
When an unassigned issue status changes to in_progress, auto-assignment will trigger again.

​
Assignment and Status Changes

Assignment behavior varies by status transition:
Status ChangeAuto-Assignment Behavior
open → in_progressAssigns to actor if no assignee
blocked → in_progressAssigns to actor if no assignee
in_progress → blockedKeeps existing assignee
in_progress → closedKeeps existing assignee
closed → in_progressAssigns to actor if no assignee
Assignees persist across status changes unless explicitly cleared or changed.

​
Scripting with Assignees

​
Check Before Starting Work

#!/bin/bash

ISSUE_ID="bd-1"
CURRENT_ASSIGNEE=$(tracer show $ISSUE_ID --json | jq -r '.assignee')

if [ "$CURRENT_ASSIGNEE" != "" ] && [ "$CURRENT_ASSIGNEE" != "$TRACE_ACTOR" ]; then
  echo "Warning: $ISSUE_ID is already assigned to $CURRENT_ASSIGNEE"
  echo "Do you want to take over? (y/n)"
  read answer
  if [ "$answer" != "y" ]; then
    exit 1
  fi
  tracer update $ISSUE_ID --assignee $TRACE_ACTOR
fi

tracer update $ISSUE_ID --status in_progress

​
Find Your Assigned Work

#!/bin/bash

export TRACE_ACTOR="claude-1"

echo "Your assigned work:"
tracer list --assignee $TRACE_ACTOR --status in_progress

echo "
Your assigned work (all statuses):"
tracer list --assignee $TRACE_ACTOR --json | jq -r '.[] | "\(.id) - \(.title) [\(.status)]"'

​
Team Overview

#!/bin/bash

echo "Work by assignee:"

for agent in claude-1 cursor-2 gpt-4; do
  count=$(tracer list --assignee $agent --status in_progress --json | jq '. | length')
  echo "$agent: $count issues in progress"
done

​
Best Practices

​
Always Set TRACE_ACTOR

# At the start of every agent session
export TRACE_ACTOR="your-agent-name"

# Verify it's set
echo $TRACE_ACTOR

​
Check Assignee Before Starting

# Before claiming work, see if someone else is on it
tracer show bd-1 | grep Assignee

# If unassigned or assigned to you, proceed
tracer update bd-1 --status in_progress

​
Use Consistent Agent Names

# Good: consistent naming
export TRACE_ACTOR="claude-sonnet-1"

# Avoid: changing names mid-project
export TRACE_ACTOR="claude"
export TRACE_ACTOR="agent-1"
export TRACE_ACTOR="my-agent"

​
Unassign When Blocked Long-Term

# If you won't be returning to this work
tracer update bd-1 --status blocked --assignee ""
tracer comment bd-1 "Blocked indefinitely, unassigning so someone else can help"

​
Next Steps

Example Scripts

See complete multi-agent scripts with auto-assignment

Continuous Integration

Use Tracer in CI/CD pipelines

Build docs developers (and LLMs) love

Get started for freeTalk to us