pi-azure-devops

Read Azure DevOps work items, bugs, WIQL queries and pull requests from pi, or from any terminal.

The package has three parts:

Part	What it is
Extension	Native pi tools: ado_work_item, ado_list_work_items, ado_wiql, ado_prs, ado_pr, ado_me. The model calls them directly with typed parameters instead of going through the shell.
Skill	azure-devops tells the model how to work with Azure DevOps: fetch a referenced work item before acting, read its comments, follow parent links. It falls back to the CLI when the tools aren't loaded.
CLI	ado, a Node CLI with no dependencies. The tools use it internally, and you can also run it yourself.

Everything is read-only. Nothing creates or changes work items or PRs.

Install

As a pi package

pi install npm:pi-azure-devops          # personal (~/.pi/agent/settings.json)
pi install -l npm:pi-azure-devops       # this project only (.pi/settings.json)
pi -e npm:pi-azure-devops               # try it for one session without installing

As a standalone CLI

npm install -g pi-azure-devops
ado help

Or run it without installing: npx -p pi-azure-devops ado help. You need Node.js 18 or later.

Authentication

You need a Personal Access Token (PAT). In dev.azure.com, go to User settings → Personal access tokens → New Token and give it these scopes:

Scope	Needed for
Work Items: Read	wi, wi list, bugs, wiql, the work items linked to a PR
Code: Read	prs, pr

Export it in your shell profile. The first of these variables that is set wins:

export AZURE_DEVOPS_PAT=<token>     # also accepted: AZURE_DEVOPS_EXT_PAT, DEVOPS_PAT, ADO_PAT

If none of those is set, ado asks git for the credential it already stores for dev.azure.com (for example Git Credential Manager or the macOS keychain), without showing any prompt. Those credentials usually only have Code scope, so PRs work but work items fail with a 401. Set a PAT to fix that.

The token only ever goes into the HTTP Authorization header. It is never printed.

Configuration

Each of org, project, repo and team is resolved on its own. The first match wins:

1. Flags: --org, --project, --repo, --team. The tools take the same fields as optional parameters.

2. Environment variables: ADO_ORG, ADO_PROJECT, ADO_REPO, ADO_TEAM.

3. The origin remote of the git repo in the current directory, if it points at Azure DevOps. HTTPS, SSH and legacy *.visualstudio.com URLs are supported. In pi, the current directory is the session's working directory.

4. A config file at ~/.config/ado/config.json. You can move it with $ADO_CONFIG or $XDG_CONFIG_HOME. It is only used when the current directory is not an Azure DevOps repo, so project settings never get mixed up:

   { "org": "myorg", "project": "MyProject", "repo": "MyRepo", "team": "MyProject Team" }
   

If repo isn't set, it defaults to the project name. team defaults to PROJECT Team (your project name followed by "Team") and is only used for --sprint current. Run ado me (or ask pi to call ado_me) to see what was resolved.

Using it in pi

Ask in plain language, for example:

• "What's Task 1234 about? Check the comments too."
• "List my open bugs in the current sprint."
• "Which PRs are waiting on my review?"
• "Summarise the review threads on PR 42 and the files it changes."

Tool	CLI equivalent	Key parameters
ado_work_item	ado wi ID... [--comments]	ids[], comments
ado_list_work_items	ado wi list …	type[], state[], mine, assigned, sprint, area, search, includeClosed, top
ado_wiql	ado wiql "QUERY"	query, top
ado_prs	ado prs …	status, mine, reviewerMe, target, source, top
ado_pr	ado pr ID [--threads] [--files]	id, threads, files
ado_me	ado me	none

Every tool also accepts org, project, repo, team, and raw (raw API JSON instead of formatted text). Output is capped at pi's standard limit of 2000 lines / 50 KB. If a result is longer, the full text is saved to a temp file and the tool result gives its path.

Why keep the skill?

The tools do the work. The skill adds guidance that doesn't belong in a tool schema, such as fetching a work item before guessing at it, reading its comments, following Parent links, and what to do about auth errors. It's also what makes the package usable by agents that don't run pi extensions, because it points them at the CLI. The skill is only loaded into context when a task needs it, so keeping it costs very little.

If you only want the tools:

{ "packages": [{ "source": "npm:pi-azure-devops", "skills": [] }] }

If you only want the skill and CLI, use "extensions": [] instead.

CLI usage

ado wi 1234 --comments                   # full work item, including comments and relations
ado wi 1234 1235                         # several at once
ado wi list --mine --sprint current      # my open items this sprint
ado bugs --state Active,New --area 'MyProject\Web'
ado wi list --type "User Story" --search login --all --top 20
ado wiql "SELECT [System.Id] FROM WorkItems WHERE [System.ChangedDate] >= @Today - 7"
ado prs --reviewer-me                    # active PRs where I'm a reviewer
ado prs --status completed --target main --top 10
ado pr 42 --threads --files
ado me
ado wi 1234 --json | jq '.fields["System.Tags"]'

Work item filters: --type, --state (repeat the flag or use a comma list), --mine / --assigned NAME, --sprint current or --sprint ITERATION_PATH, --area AREA_PATH, --search TITLE_TEXT, --all (include Closed/Done/Removed/Resolved), and --top N (default 50). Common options: --json, --debug (prints the generated WIQL), and --org/--project/--repo/--team. Set NO_COLOR=1 to turn off colours, and DEBUG=1 to get stack traces on errors.

Development

npm install          # dev dependencies are only needed for type-checking
npm test             # node:test, no network needed (Node ≥ 22.18 for the .ts import)
npm run typecheck
pi -e .              # load this checkout in pi

Layout:

extensions/azure-devops.ts      pi extension (tool registration, output truncation)
extensions/lib/cli-args.ts      pure tool-params → CLI argv mapping
skills/azure-devops/SKILL.md    pi / Agent Skills skill
skills/azure-devops/scripts/ado.mjs   the CLI (also the npm `bin`)
test/                           unit tests

License

MIT