Skip to main content

ado-search

Sync and search Azure DevOps work items and wiki pages locally for AI agents.

Install

pip install ado-search

Or from source:

pip install git+https://github.com/HurleySk/ado-search.git

Quick Start

# Configure (requires az login first)
ado-search init --org https://dev.azure.com/yourorg --project YourProject

# Pull data
ado-search sync

# Search
ado-search search "login bug"
ado-search search "auth" --type Bug --state Active
ado-search search "setup guide" --format paths

How It Works

  1. Sync pulls work items and wiki pages from Azure DevOps
    • Tries OData analytics first (fetches all items in one call — fast)
    • Falls back to az devops CLI if analytics isn't available
  2. Data is stored as sorted JSONL files — git-friendly, diffable, one file per entity type
  3. A SQLite FTS5 index is derived from the JSONL and auto-rebuilt when stale
  4. Agents search the index, then use show to render full content — minimal context

Git-Friendly Storage

Sync produces two text files that are safe to commit, push, and pull:

  • work-items.jsonl — one JSON object per line, sorted by ID
  • wiki-pages.jsonl — one JSON object per line, sorted by path

The SQLite index (index.db) is .gitignored — it auto-rebuilds from JSONL on first search or show.

Synced Fields

Each work item includes: id, title, type, state, area, iteration, assigned_to, tags, priority, parent_id, created, updated, description, acceptance_criteria, dev_notes (Custom.DevelopmentNotes), notes (Custom.Notes), story_points, state_history, attachments, and inline_images.

Story points are sourced from StoryPoints or Effort fields. State history tracks every state change (e.g., New → Active → Resolved → Closed) with date and author.

Attachments & Inline Images

When include_attachments = true in config, or --include-attachments is passed on the command line, sync/fetch downloads:

  • File attachments — stored in .ado-search/attachments/{work_item_id}/
  • Inline images — images embedded in Description/Acceptance Criteria HTML, stored in .ado-search/attachments/{work_item_id}/inline/
  • Comment images -- images pasted into work item comments (screenshots, diagrams), stored alongside other inline images. fetch --include-attachments automatically enables comment fetching to capture these.

Attachment filenames are indexed and searchable. Inline images are referenced as [image: path] in text output so agents can locate them. Downloads are incremental — existing files with correct size are skipped on re-sync.

Note: attachments require the WIQL/REST sync path (OData doesn't include relations), so OData fast path is skipped when attachments are enabled.

Use --include-attachments on fetch or sync for per-invocation attachment downloads without changing config:

# Fetch specific items with their attachments (also fetches comment images)
ado-search fetch 73541 --include-attachments

# One-time full sync with attachments
ado-search sync --include-attachments

Commands

Command Description
ado-search init Configure organization, project, and auth
ado-search sync Pull latest data from Azure DevOps (--full for complete re-fetch, --project to limit)
ado-search search "query" Full-text search with filters
ado-search show <id> Display full content of an item
ado-search create Create a new work item
ado-search update <id> Update an existing work item
ado-search add-comment <id> <text> Add a comment to a work item
ado-search add-link <source> <target> Add a link between two work items
ado-search remove-link <source> <target> Remove a link between two work items
ado-search upload-attachment <id> <file> Upload a local file as an attachment to a work item
ado-search list-links <id> List links on a work item (live)
ado-search list-comments <id> List comments on a work item (live)
ado-search grep "pattern" Regex search across work item fields
ado-search children <parent_id> List children (or full tree) of a work item

Create & Update

Create and update work items directly from the CLI:

# Create a new bug
ado-search create --type Bug --title "Login button broken" --state New --priority 1

# Create with description and tags
ado-search create --type "User Story" --title "Add dark mode" \
  --description "Users want a dark theme option" \
  --tags "ui; theme" --story-points 5

# Create a child task under a parent work item
ado-search create --type Task --title "Subtask" --parent 62434

# Update a work item
ado-search update 12345 --state Active --assigned-to "user@example.com"

# Close as duplicate (--reason sets Microsoft.VSTS.Common.ResolvedReason)
ado-search update 67154 --state Closed --reason Duplicate

# Set arbitrary ADO fields (including custom fields)
ado-search create --type Task --title "Research" --field "Custom.Effort=3"
ado-search update 12345 --field "System.AreaPath=Project\Team" --field "Custom.Sprint=Sprint 5"

# Preview without writing
ado-search create --type Bug --title "Test" --dry-run

HTML Content from Files

Description, acceptance criteria, and comment text accept HTML. For multi-line content, use the @file convention to read from a file:

# Set description from an HTML file
ado-search create --type Bug --title "Rendering issue" --description @bug-details.html

# Update acceptance criteria from a file
ado-search update 12345 --acceptance-criteria @criteria.html

# Add a comment from a file
ado-search add-comment 12345 @review-notes.html

# Inline HTML still works
ado-search add-comment 12345 "<p>Looks good!</p>"

# @mentions are auto-resolved to ADO identity links
ado-search add-comment 12345 "Great work @John Smith (CTR), please review"

# Text that starts with an @mention needs @@ so it is not read as a file path
ado-search add-comment 12345 "@@Jane Doe, can you retest?"

# Refuse to post if any mention is unknown or ambiguous
ado-search add-comment 12345 "@@Jane Doe, can you retest?" --strict-mentions

# Skip mention resolution (post raw text as-is)
ado-search add-comment 12345 "@@not-a-user just a note" --no-mentions

# Escape a literal @ with @@
ado-search update 12345 --description "@@mention is not a file reference"

@Display Name and @email patterns in comment text are resolved via the ADO Identity Picker API and replaced with mention HTML so the mentioned user receives a notification. A mention takes the longest run of up to five words that names exactly one person by whole words, so @Jane Doe (CTR), please tags Jane Doe and keeps , please, and @Jan never tags Janet. A first name shared by several people is reported as ambiguous and left as text. Existing mention anchors, <code>, and <pre> are left alone; write &#64; for a literal @ in the comment. Resolved, unresolved, and ambiguous mentions are reported on stderr.

After create/update/add-comment/add-link, the item is automatically re-fetched and merged into the local JSONL store so it appears in search immediately.

# Add a parent link
ado-search add-link 12345 67890 --type parent

# Add a related link with a comment
ado-search add-link 12345 67891 --type related --comment "See also this item"

# Link types: related, parent, child, duplicate, duplicate-of, depends-on, predecessor, successor
ado-search add-link 12345 67892 --type depends-on

# Use a raw ADO relation type
ado-search add-link 12345 67893 --type "System.LinkTypes.Related"

# Preview without creating
ado-search add-link 12345 67890 --type child --dry-run

# Remove a link
ado-search remove-link 12345 67890 --type parent

# List all links on a work item (live from ADO)
ado-search list-links 12345

# List all comments on a work item (live from ADO)
ado-search list-comments 12345

Configuration

Default sync includes Bug, User Story, Epic, and Feature work item types. To include Tasks or customize:

# .ado-search/config.toml
[sync]
work_item_types = ["Bug", "User Story", "Task", "Epic", "Feature"]
include_comments = false
include_attachments = false  # set to true to download file attachments and inline images

Multiple Projects

One data dir can hold several projects from the same organization:

[organization]
url = "https://dev.azure.com/yourorg"
project = "Alpha"              # default project for create/update/comments/links and wiki
projects = ["Alpha", "Beta"]   # or ["*"] for every project you can see
ado-search sync                    # syncs every configured project
ado-search sync --project Beta     # just one
ado-search search "timeout" --project Beta
ado-search grep "retry" --project Alpha

Each project keeps its own incremental watermark under [sync.last_sync_by_project]. Wiki pages are synced for the default project only.

Project names are matched case-insensitively, as in Azure DevOps. sync.area_paths entries apply to the project they start with (Alpha\Web filters Alpha only); a project with no matching entry syncs all its areas. work_item_types and states apply to every project, so list the types of every process you sync (e.g. both User Story and Product Backlog Item).

Auth Methods

  • az-cli (default): Uses az devops commands. Requires az login.
  • az-powershell: Uses Azure PowerShell + REST. Requires Connect-AzAccount.
  • pat: Uses a Personal Access Token via REST. For cross-cloud or service account scenarios.

Set via ado-search init --auth-method <method> or in config.toml.

# PAT example (token can also be set via ADO_PAT env var)
ado-search init --org https://dev.azure.com/yourorg --project YourProject --auth-method pat --pat <token>

Search Formats

ado-search search "query"                          # compact (default)
ado-search search "query" --format detail           # with description snippets
ado-search search "query" --format json             # machine-readable
ado-search search "query" --format paths            # file paths only (for agent piping)
ado-search search "query" --type Bug --state Active # filtered

Grep — Regex Pattern Matching

Search work items with regex patterns across fields:

# Find IP addresses anywhere in title/description/comments
ado-search grep '\d+\.\d+\.\d+\.\d+'

# Find "deprecated" only in comments, case-insensitive
ado-search grep -i 'deprecated' -f comments

# Find URL patterns in active bugs, brief output
ado-search grep 'https?://\S+' --type Bug --state Active --brief

# JSON output for scripting
ado-search grep 'TODO|FIXME' --format json

Default fields searched: title, description, dev_notes, notes, comments. Use --field / -f to scope to specific fields (title, description, acceptance_criteria, dev_notes, notes, comments, tags, assigned_to, area, iteration, state_history).

Metadata pre-filters (--type, --state, --area, --assigned-to, --tag) narrow candidates via SQLite indexes before the regex scan. Exit codes follow grep convention: 0 = matches found, 1 = no matches, 2 = error.

Children — Hierarchy Queries

Query work item parent-child hierarchy from local data:

# Show direct children of an epic
ado-search children 61123

# Full recursive tree (features, stories, tasks, ...)
ado-search children 61123 --recursive

# Indented tree view
ado-search children 61123 --recursive --format tree

# Filter to user stories only
ado-search children 61123 --recursive --type "User Story"

# Include closed date from state history
ado-search children 61123 --recursive --include-closed-date

# JSON for scripting
ado-search children 61123 --recursive --format json --include-closed-date

The children command queries the local SQLite index (no API calls). Use sync or fetch first to ensure data is current. Exit codes: 0 = children found, 1 = no children, 2 = parent not found.

Prerequisites

  • Python 3.10+
  • Azure CLI with azure-devops extension (az extension add --name azure-devops)
  • az login completed

Metadata

Release files for ado-search 1.15.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for ado-search 1.15.0
File Size Uploaded Provenance Actions
ado_search-1.15.0.tar.gz 83.7 kB With provenance Details for ado_search-1.15.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for ado-search 1.15.0
File Interpreter ABI Platform Actions
ado_search-1.15.0-py3-none-any.whl Python 3 none any Details for ado_search-1.15.0-py3-none-any.whl

Total release size: 141.5 kB

Release files / ado_search-1.15.0.tar.gz

Download URL ado_search-1.15.0.tar.gz
Size 83.7 kB
Tags Source
SHA-256 checksum
How to use checksums
c20e28008f6f82b73c55e59e102e8cdc4b370eae433e37d7fe26cdf341db644f
BLAKE2b-256 checksum
How to use checksums
9b91a0213b69313a73f685af74407b4edafc427378949b513163efc4f5ca3c1f
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 7, 2026.

Transparency log

Release files / ado_search-1.15.0-py3-none-any.whl

Download URL ado_search-1.15.0-py3-none-any.whl
Size 57.7 kB
Tags Python 3
SHA-256 checksum
How to use checksums
4bdccd8b8d43c7c233555720b508d5739f07bf7c6a0de41416715894e3f7d595
BLAKE2b-256 checksum
How to use checksums
50eb5ab882426858fd2baf58bf7c0ec3ab86987b4913dbecbc3667c9d3f235fc
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 7, 2026.

Transparency log

Security for ado-search 1.15.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for ado_search-1.15.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 7, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

1.15.0 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page