Azure DevOps Work Item Tool

Fetch, manage, and analyze Azure DevOps work items using

tools azure-devops

CLI Reference

tools azure-devops workitem <id|ids>             # Fetch work item(s)
tools azure-devops query <id|url|name>           # Fetch query results (supports name matching)
tools azure-devops query <id> --download-workitems  # Download all to files
tools azure-devops dashboard <id|url>            # Get dashboard queries
tools azure-devops list                          # List cached items
tools azure-devops workitem-create               # Create work item
tools azure-devops timelog configure             # Interactive: setup API key, user, allowed types
tools azure-devops timelog types                 # List available time types
tools azure-devops timelog list -w <id>          # List time logs for work item
tools azure-devops timelog add -w <id> -h <hrs>  # Log time entry (with precheck)
tools azure-devops timelog prepare-import add    # Stage entries for review before import
tools azure-devops timelog prepare-import list   # Review staged entries
tools azure-devops timelog prepare-import remove # Remove staged entry
tools azure-devops timelog prepare-import clear  # Clear all staged entries
tools azure-devops timelog import <file>         # Bulk import time logs (with precheck)

Options

--format ai|md|json

--force

--refresh

--state <states>

--severity <sev>

--download-workitems

--category <name>

--task-folders

--attachments-from <datetime>

--attachments-to <datetime>

--attachments-prefix <prefix>

--attachments-suffix <suffix>

--output-dir <path>

--images

Output Paths

• Tasks:

  .claude/azure/tasks/

  →

  <id>-<Slug-Title>.md

• With

  --category react19

  :

  .claude/azure/tasks/react19/<id>-<Slug>.md

• With

  --task-folders

  :

  .claude/azure/tasks/<id>/<id>-<Slug>.md

Attachment Output Paths

Attachments are downloaded when any

--attachments-*

• Default: Same folder as task file:

  .claude/azure/tasks/<taskid>-<attachment-name>

• With

  --task-folders

  :

  .claude/azure/tasks/<id>/<taskid>-<attachment-name>

• With

  --output-dir /custom/path

  :

  /custom/path/<taskid>-<attachment-name>

Inline Image Output Paths

Inline images (screenshots embedded in description/comments HTML) are downloaded when

--images

• Default: Same folder as task file:

  .claude/azure/tasks/<taskid>-<imagename>.png

• With

  --task-folders

  :

  .claude/azure/tasks/<id>/<taskid>-<imagename>.png

• Images are referenced in the

  .md

  file with relative paths

Recommended: Use

--task-folders --images

Operations

Fetch Work Items

tools azure-devops workitem 261575
tools azure-devops workitem 261575,261576,261577
tools azure-devops workitem 261575 --category react19
tools azure-devops workitem 261575 --force

Fetch Query

The

--query

1. Query ID (GUID):

   d6e14134-9d22-4cbb-b897-b1514f888667

2. Full URL:

   https://dev.azure.com/org/project/_queries/query/abc123

3. Query Name:

   "Otevřené bugy"

   (fuzzy matching supported)

# By ID
tools azure-devops query d6e14134-9d22-4cbb-b897-b1514f888667

# By name (uses fuzzy matching to find the query)
tools azure-devops query "Open Bugs"
tools azure-devops query "Otevřené bugy"

# With filters
tools azure-devops query <id> --state Active,Development
tools azure-devops query "Active Tasks" --download-workitems --category react19

Query Name Matching:

• Exact matches are used immediately
• Fuzzy matching finds the closest query name if no exact match
• Shows alternatives if multiple similar queries exist
• Query list is cached for 1 day for fast lookups

Analyze Work Items

When user says "analyze workitem/task X" or "analyze tasks from query Y":

1. Fetch work item(s) with images:

   tools azure-devops workitem <ids> --category <cat> --task-folders --images
   

2. Read the generated

   .md

   file for each work item

3. Read inline images - Check for image files next to the work item's

   .md

   file:

   ls $(dirname <path-to-workitem.md>)/<id>-*.{png,jpg,gif,jpeg} 2>/dev/null
   

   If images exist, use the Read tool to view each image file. This gives visual context for:

   • Bug screenshots showing the issue
   • Design mockups showing expected behavior
   • UI comparisons (current vs expected)

4. Spawn Explore agent (Task tool with

   subagent_type: "Explore"

   ) for each:

   Analyze codebase for Azure DevOps work item:
   
   **#{id}: {title}**
   State: {state} | Severity: {severity}
   
   **Description:** {description}
   **Visual Context:** {describe what the inline images show, if any}
   **Comments:** {comments}
   
   Find:
   1. Relevant code files/components for this issue
   2. Current implementation and data flow
   3. Required changes
   4. Dependencies and related systems
   5. Complexity assessment
   
   Return: files found, current implementation, recommended approach, considerations, complexity (Low/Medium/High)
   

5. Write

   .analysis.md

   next to the work item file:
   • Work item:

     .claude/azure/tasks/261575-Title.md

   • Analysis:

     .claude/azure/tasks/261575-Title.analysis.md

Analysis Document Format

# Analysis: #{id} - {title}

**Analyzed**: {timestamp}
**Work Item**: {path to .md file}

## Summary
{1-2 sentence findings summary}

## Relevant Code
- `path/file.ts` - {purpose}

## Current Implementation
{How current code works}

## Recommended Approach
{Step-by-step plan}

## Considerations
- {Risks/considerations}

## Complexity: {Low|Medium|High}
{Reasoning}

Examples

tools azure-devops workitem 261575

tools azure-devops query X

tools azure-devops query "Open Bugs"

tools azure-devops query "Otevřené bugy"

tools azure-devops query "React19 Bugs" --download-workitems --category react19

tools azure-devops workitem 12345 --attachments-suffix .har

tools azure-devops workitem 12345 --attachments-from "2026-02-12T10:00:00"

tools azure-devops workitem 12345 --attachments-from 2000-01-01

tools azure-devops workitem 261575 --task-folders --images

--images

Creating Work Items

The

--create

CLI Reference

tools azure-devops workitem-create -i                     # Interactive mode
tools azure-devops workitem-create --from-file <path>     # From template file
tools azure-devops workitem-create <query-url> --type Bug # Generate template from query
tools azure-devops workitem-create <workitem-url>         # Generate template from work item
tools azure-devops workitem-create --type Task --title X  # Quick creation

Create Options

-i, --interactive

--from-file <path>

--type <type>

--title <text>

--severity <sev>

--tags <tags>

--assignee <email>

Creation Modes

1. Interactive Mode (

-i

)

Best for: Manual creation with full control over all fields.

tools azure-devops workitem-create -i

Prompts for: type, title, description (via editor), severity, state, tags, assignee, parent link.

2. Template from Query

Best for: Creating work items that match patterns from existing items.

tools azure-devops workitem-create "https://dev.azure.com/.../_queries/query/abc" --type Bug

This:

1. Analyzes work items from the query
2. Extracts common patterns (area paths, tags, severities used)
3. Generates a template with hints from analyzed items
4. Saves to

   .claude/azure/tasks/created/template-<timestamp>.json

3. Template from Work Item

Best for: Cloning or creating similar work items.

tools azure-devops workitem-create "https://dev.azure.com/.../_workitems/edit/12345"

This:

1. Fetches the source work item
2. Generates a template pre-filled with matching values
3. Keeps parent reference if source had one
4. Saves to

   .claude/azure/tasks/created/template-<timestamp>.json

4. From Template File

Best for: LLM workflows where templates are prepared programmatically.

tools azure-devops workitem-create --from-file ".claude/azure/tasks/created/template.json"

Template format:

{
  "$schema": "azure-devops-workitem-v1",
  "type": "Bug",
  "fields": {
    "title": "Error in checkout flow",
    "description": "<p>Description here</p>",
    "severity": "A - critical",
    "tags": ["frontend", "checkout"],
    "assignedTo": "user@example.com",
    "areaPath": "Project\\Area",
    "iterationPath": "Project\\Sprint1"
  },
  "relations": {
    "parent": 12345
  }
}

5. Quick Non-Interactive

Best for: Simple work items created from command line.

tools azure-devops workitem-create --type Task --title "Fix login bug"
tools azure-devops workitem-create --type Bug --title "Error" --severity "A - critical" --tags "frontend,urgent"

LLM Workflow

When user asks to "create a work item" or "file a bug":

1. Gather information - Ask for: type, title, description, severity (if bug)

2. Choose mode based on context:

   • Have a template file? Use

     --from-file

   • Want to match existing patterns? Generate template from query first
   • Simple request? Use quick mode

     --type X --title "Y"

   • Complex with many fields? Use interactive mode

3. Create the work item:

   # Quick creation
   tools azure-devops workitem-create --type Bug --title "Error in checkout" --severity "B - high"
   
   # Or from template
   tools azure-devops workitem-create --from-file template.json
   

4. Report the result - Include the work item ID and URL in your response.

Examples

--create --type Bug --title "Login issue" --severity "B - high"

--create --type Task --title "Update documentation"

--create <workitem-url>

--from-file template.json

--create -i

History Commands

Track work item history: who changed what, when, and how long items spent in each state.

CLI Reference

tools azure-devops history show <id>                    # Summary view (assignment/state periods, time-in-state)
tools azure-devops history show <id> -f timeline        # Chronological events
tools azure-devops history show <id> -f json            # JSON output
tools azure-devops history show <id> --force            # Force refresh from API
tools azure-devops history show <id> --assigned-to "X"  # Filter by assignee
tools azure-devops history show <id> --state Active     # Filter by state

tools azure-devops history search --assigned-to-me --wiql          # Currently assigned to me (WIQL @Me)
tools azure-devops history search --assigned-to "Martin" --wiql    # Ever assigned to user (server-side)
tools azure-devops history search --assigned-to "Martin" --wiql --current  # Currently assigned
tools azure-devops history search --assigned-to "Martin"           # Local cached history search
tools azure-devops history search --assigned-to "Martin" --min-time 2h     # Min time filter
tools azure-devops history search --state Active --since 2024-12-01 --wiql # State + date range (--since/--until aliases for --from/--to)

tools azure-devops history sync                   # Bulk sync history for cached work items (per-item mode)
tools azure-devops history sync --force           # Force re-sync all
tools azure-devops history sync --dry-run         # Show what would be synced
tools azure-devops history sync --batch           # Use batch reporting API instead

NL Query Translation

history search --assigned-to-me --wiql

history search --assigned-to "Martin" --wiql

history show 123 --state Active

history show 456 --assigned-to Martin

history search --assigned-to "Martin" --from 2024-12-01 --wiql

Features

• @me support:

  --assigned-to @me

  or

  --assigned-to-me

  uses WIQL

  @Me

  macro (auto-enables WIQL)
• --current flag: Uses

  =

  instead of

  EVER

  for current assignment
• Fuzzy user matching: "Martin" matches "Martin Novak (QK)", diacritics normalized
• Cache stats: Local search shows data date range and last sync time
• Per-item sync (default): Targeted API calls per work item, faster for <200 items
• Batch sync (

  --batch

  ): Uses reporting API, better for 500+ items

TimeLog Operations

Time logging for Azure DevOps work items using the third-party TimeLog extension.

Setup

# Interactive configuration (recommended)
tools azure-devops timelog configure

This launches an interactive prompt (using clack) that configures:

• functionsKey

  : TimeLog API key (auto-fetched from Azure DevOps)

• defaultUser

  : Your user email/name for time logging

• allowedWorkItemTypes

  : Work item types that can be logged to (e.g., "Bug,Task")

• allowedStatesPerType

  : Required states per type (e.g., "Task:In Progress")

The configuration is saved to

.claude/azure/config.json

Note for LLM agents: Since

configure

AskUserQuestion

# Non-interactive mode (for scripting)
tools azure-devops timelog configure --allowed-work-item-types "Bug,Task" --allowed-states-for-type "Task:In Progress"

List Time Types

tools azure-devops timelog types              # AI-friendly list
tools azure-devops timelog types --format json  # JSON output

List Time Logs

tools azure-devops timelog list -w <workItemId>
tools azure-devops timelog list -w 268935 --format md
tools azure-devops timelog list --from 2026-02-01 --to 2026-02-08 --format json
tools azure-devops timelog list --from 2026-02-01 --to 2026-02-08 --user @me --format json

The

--user @me

--from

--to

--since

--upto

Add Time Log Entry

# Quick mode (all options on CLI)
tools azure-devops timelog add -w <id> -h <hours> -t <type>
tools azure-devops timelog add -w 268935 -h 2 -t "Development"
tools azure-devops timelog add -w 268935 -h 1 -m 30 -t "Code Review" -c "PR review"

# Interactive mode
tools azure-devops timelog add -i
tools azure-devops timelog add -w 268935 -i

Before creating the entry, the command runs a workitem type precheck (see Workitem Type Validation below).

Prepare Entries for Import (Recommended for Batch Operations)

The

prepare-import

# Stage entries for review
tools azure-devops timelog prepare-import add --from 2026-02-01 --to 2026-02-08 --entry '{
  "workItemId": 268935,
  "date": "2026-02-04",
  "hours": 2,
  "timeType": "Development",
  "comment": "Implemented feature X"
}'

# Add another entry (same date range)
tools azure-devops timelog prepare-import add --from 2026-02-01 --to 2026-02-08 --entry '{
  "workItemId": 262042,
  "date": "2026-02-04",
  "hours": 0.5,
  "timeType": "Ceremonie",
  "comment": "Daily standup"
}'

# Review all staged entries
tools azure-devops timelog prepare-import list --name 2026-02-01.2026-02-08 --format table

# Remove a specific entry if needed
tools azure-devops timelog prepare-import remove --name 2026-02-01.2026-02-08 --id <uuid>

# Clear all entries for this date range
tools azure-devops timelog prepare-import clear --name 2026-02-01.2026-02-08

The name is auto-generated from

--from

--to

<from>.<to>

2026-02-01.2026-02-08

Import Time Logs

# Import from prepare-import staging file
tools azure-devops timelog import .genesis-tools/azure-devops/cache/prepare-import/2026-02-01.2026-02-08.json

# Or import from custom JSON file
tools azure-devops timelog import entries.json

# Dry run to validate without creating entries
tools azure-devops timelog import entries.json --dry-run

The import command runs workitem type precheck for each entry before creating it. After import, the command shows a precheck summary with counts of passed/redirected/failed entries. The cache is automatically evicted after successful imports.

Workitem Type Validation

Before creating time log entries, the tool validates that the workitem type is configured as allowed in

allowedWorkItemTypes

Automatic Redirect for User Stories:

• If a workitem is a User Story (not typically allowed for time logging), the tool looks for child Tasks/Bugs
• Exactly 1 child of allowed type: Auto-redirect with warning
• 0 children of allowed type: Error
• Multiple children: Error with list for user to choose from

Configuration:

• Run

  tools azure-devops timelog configure

  to set

  allowedWorkItemTypes

• Common configuration:

  "Bug,Task"

  (excludes User Stories, Features, etc.)
• Can also configure

  allowedStatesPerType

  for additional validation

Where Precheck Applies:

• timelog add

  - Before creating single entry

• timelog import

  - Before importing each entry

• prepare-import add

  - When staging entry for review

TimeLog Examples

tools azure-devops timelog add -w 268935 -h 2 -t "Development"

tools azure-devops timelog types

tools azure-devops timelog list -w 268935

tools azure-devops timelog add -i

tools azure-devops timelog prepare-import add --from ... --to ... --entry '{...}'

tools azure-devops timelog prepare-import list --name 2026-02-01.2026-02-08

tools azure-devops timelog import entries.json

tools azure-devops timelog import entries.json --dry-run

Natural Language Time Logging

When user asks to log time in natural language, parse their request and construct the CLI command:

1. Parse Duration Formats:

• "1 hour", "1h", "1hr" →

  -h 1

• "30 minutes", "30min", "30m" →

  -h 0 -m 30

• "1.5 hours", "1h30m", "90 minutes" →

  -h 1 -m 30

• "2 hours 15 minutes" →

  -h 2 -m 15

2. Extract Work Item IDs:

• From explicit mention: "on task 268935", "workitem #268935", "WI 268935"
• From git branch:

  feature/268935-fix-login

  → work item 268935
• From recent commits:

  feat(#268935): fix login bug

  → work item 268935

To extract from git context:

# Get current branch
git branch --show-current

# Get recent commit messages (look for #NNNNNN patterns)
git log --oneline -5

3. Infer Time Type from Context:

Default to "Development" if no context clues.

4. Use Git Commit Messages as Notes:

When user says "use commit message" or doesn't provide a note:

# Get last commit message
git log -1 --pretty=%B

Use the commit subject line as the time log comment.

Natural Language Examples

timelog add -w 268935 -h 1 -t "Development"

timelog add -w 789 -h 0 -m 30 -t "Code Review"

timelog add -w <from-branch> -h 1 -m 30 -t "Development"

Workflow: Log Time from Git Context

When user says "log time for my work" without explicit details:

1. Get work item ID:

   git branch --show-current  # e.g., feature/268935-fix-login
   

   Extract number: 268935

2. Get commit messages for note:

   git log -1 --pretty=%B
   

3. Infer time type from commit message keywords

4. Ask user for duration if not specified (use AskUserQuestion)

5. Execute:

   tools azure-devops timelog add -w 268935 -h <hours> -t "<inferred-type>" -c "<commit-message>"
   

Integration with

tools git

For gathering commit data to correlate with time entries, use the

tools git commits

# Get commits for a date range with automatic workitem ID extraction
tools git commits --from 2026-02-01 --to 2026-02-08 --format json 2>/dev/null | tools json

This command:

• Extracts workitem IDs from commit messages and branch names via configured patterns
• Returns commit metadata (hash, message, author, date)
• Includes stats (files changed, insertions, deletions)
• Filters by configured authors (see

  tools git configure authors

  )

The extracted workitem IDs can be used to match commits to Azure DevOps work items for time logging purposes.

HAR File Analysis from Work Items

When user explicitly asks to download and analyze HAR attachments from a work item:

# 1. Download HAR attachment
tools azure-devops workitem <id> --attachments-suffix .har --output-dir /tmp/har

# 2. Load and analyze with har-analyzer
tools har-analyzer load /tmp/har/<taskid>-capture.har

Do NOT download or analyze HAR files automatically -- only when the user requests it.

Documentation Resources

For deeper API research beyond this skill:

• Local docs:

  src/azure-devops/docs/

  contains 14 reference files (work items, iterations, PRs, REST API, WIQL syntax, timelog history)
• Context7: Use library ID

  /websites/learn_microsoft_en-us_rest_api_azure_devops

  for detailed REST API specs
• CLAUDE.md: Contains context7 library IDs and batch endpoint quick reference