ADO AI - Azure DevOps AI Auto-Complete Tool

A powerful tool that leverages Claude AI to automatically analyze and complete Azure DevOps work items. Available as both a CLI and Web Service with beautiful UI—fetch work items, get AI-powered analysis, and update them with intelligent solutions.

🌟 Features

Core Features

🤖 AI-Powered Analysis: Uses Claude AI (Anthropic) to analyze work items and generate solutions
🔄 Auto-Complete: Automatically update work items with AI-generated analysis
⚙️ Type-Specific Prompts: Specialized analysis for Bugs, Tasks, and User Stories
💰 Cost Tracking: Real-time token usage and cost estimation
🔒 Secure: Encrypted credential storage with Fernet (AES-256)
🛡️ Robust: Automatic retry logic and comprehensive error handling

Web Service Features

🌐 Beautiful Web UI: Modern interface built with FastAPI + Tailwind CSS
🔐 Encrypted Storage: Credentials stored securely in database
📝 Custom Prompts: Add specific instructions for each analysis
📊 Analysis History: Track all work item analyses with costs
🚀 RESTful API: Comprehensive API with auto-generated documentation
⚡ Real-time Updates: Progress tracking during AI analysis

CLI Features

📊 Beautiful Terminal: Rich output with tables, colors, and progress indicators
⌨️ Fast & Efficient: Perfect for scripting and automation
🔧 Developer-Friendly: Works with existing terminal workflows

Installation

Prerequisites

Python 3.9 or higher
Azure DevOps account with a Personal Access Token (PAT)
Anthropic API key for Claude AI

Install Package

# Clone or navigate to the project directory
cd /path/to/azure_devops

# Install in development mode (includes all dependencies)
pip install -e .

# Install with development dependencies
pip install -e ".[dev]"

Quick Start

Option 1: Web Service (Recommended for UI)

# Start the web server
python -m ado_ai_web.main

# Open browser to http://localhost:8000
# Complete the setup wizard
# Start analyzing work items!

Option 2: CLI (Recommended for automation)

# Create configuration file
cp .env.example .env

# Edit .env with your credentials
# vim .env

# Validate configuration
ado-ai config validate

# Analyze a work item
ado-ai complete 12345

Web Service

Starting the Web Service

# Development mode (with auto-reload)
python -m ado_ai_web.main

# Production mode with Uvicorn
uvicorn ado_ai_web.main:app --host 0.0.0.0 --port 8000

The service will be available at:

HTTPS: https://localhost:8000 (if SSL certificates are configured)
HTTP: http://localhost:8000 (fallback if no SSL certificates)

HTTPS Setup (Recommended)

For secure communication, the web service supports HTTPS with self-signed certificates:

# Generate self-signed SSL certificate
python scripts/generate_cert.py

# The script will create:
#   - certs/cert.pem  (SSL certificate)
#   - certs/key.pem   (Private key)

# Start the server - it will automatically use HTTPS if certificates exist
python -m ado_ai_web.main

Browser Security Warning: Self-signed certificates will trigger a browser warning. This is expected and safe for local development. Click "Advanced" → "Proceed to localhost" to continue.

Custom Certificates: You can use your own SSL certificates by setting environment variables:

export SSL_CERTFILE=/path/to/your/cert.pem
export SSL_KEYFILE=/path/to/your/key.pem
python -m ado_ai_web.main

First-Time Setup

Navigate to https://localhost:8000 (or http://localhost:8000 without SSL)
You'll be redirected to the setup wizard
Enter your Azure DevOps credentials:
- Organization URL (e.g., https://dev.azure.com/YourOrg)
- Project name
- Personal Access Token (PAT)
Enter your Anthropic API key
(Optional) Set work folder path for file operations
Click "Test Connection" buttons to validate
Complete setup

Using the Web Interface

Analyze a Work Item

Click "New Analysis" from the dashboard
Enter work item ID
(Optional) Add custom prompt for specific guidance
Click "Fetch Work Item" to see details
Click "🤖 Analyze with AI" to start analysis
Review comprehensive AI insights:
- Analysis summary
- Detailed solution
- Task breakdown
- Risk assessment
- Proposed changes
- Token usage and cost
(Coming soon) Click "Apply Changes" to update work item

Configuration Management

Access settings via the "Settings" menu
Update credentials, model selection, and preferences
Test connections at any time
All changes are saved to encrypted database

API Documentation

Interactive API documentation is available at:

Swagger UI: https://localhost:8000/docs (or http://localhost:8000/docs)
ReDoc: https://localhost:8000/redoc (or http://localhost:8000/redoc)

API Endpoints

# Authentication & Setup
POST   /api/setup                          # Initial configuration
POST   /api/test-connection                # Test credentials

# Configuration
GET    /api/config                         # Get settings (redacted)
PUT    /api/config                         # Update settings
GET    /api/config/status                  # Check if configured

# Work Items
GET    /api/work-items/{id}                # Fetch work item
POST   /api/work-items/{id}/analyze        # Analyze with AI
GET    /api/work-items/history/{id}        # Get analysis results

# Health
GET    /health                             # Health check

Docker Deployment

# Build image
docker build -t ado-ai-web .

# Run container
docker run -p 8000:8000 \
  -e ENCRYPTION_MASTER_KEY=your-key-here \
  -v ./ado_ai.db:/app/ado_ai.db \
  ado-ai-web

Environment Variables (Web Service)

# Required
ENCRYPTION_MASTER_KEY=your-base64-encoded-32-byte-key

# Optional - Database
DATABASE_URL=sqlite:///./ado_ai.db

# Optional - Security
SESSION_SECRET_KEY=your-session-secret
CSRF_SECRET_KEY=your-csrf-secret

# Optional - SSL/HTTPS
SSL_CERTFILE=./certs/cert.pem    # Path to SSL certificate
SSL_KEYFILE=./certs/key.pem      # Path to SSL private key

CLI Usage

Configuration

1. Create Environment File

cp .env.example .env

2. Configure Credentials

Edit the .env file:

# Azure DevOps Configuration
AZURE_DEVOPS_ORG_URL=https://dev.azure.com/YourOrganization
AZURE_DEVOPS_PROJECT=YourProject
AZURE_DEVOPS_PAT=your_personal_access_token_here

# Anthropic Claude Configuration
ANTHROPIC_API_KEY=your_anthropic_api_key_here
CLAUDE_MODEL=claude-opus-4-6

# Application Settings
LOG_LEVEL=INFO
AUTO_APPROVE=false
MAX_RETRIES=3
TIMEOUT_SECONDS=30

3. Validate Configuration

ado-ai config validate

Commands

Fetch a Work Item

Display work item details without making changes:

ado-ai fetch 12345

Complete a Work Item

Analyze and auto-complete a work item with AI:

# Interactive mode (prompts for confirmation)
ado-ai complete 12345

# Auto-approve mode (no confirmation)
ado-ai complete 12345 --auto-approve

# Dry-run mode (simulate without changes)
ado-ai complete 12345 --dry-run

Configuration Commands

# Validate configuration
ado-ai config validate

# Show current configuration
ado-ai config show

Global Options

# Verbose output (DEBUG level)
ado-ai --verbose complete 12345

# Quiet output (only warnings/errors)
ado-ai --quiet complete 12345

# Show help
ado-ai --help

# Show version
ado-ai version

Example Output

✓ Fetching work item 12345...
┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ Work Item Details                         ┃
┣━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┫
┃ ID:          12345                        ┃
┃ Type:        Task                         ┃
┃ Title:       Implement user auth          ┃
┃ State:       Active                       ┃
┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛

✓ Analyzing with Claude AI...

🤖 AI Analysis
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Analysis: This task requires implementing a secure user authentication system...

Solution: Implement JWT-based authentication with the following approach...

Tasks:
  1. Set up authentication middleware
  2. Create login/logout endpoints
  3. Implement token validation
  4. Add unit tests for auth flow

💡 Proposed Changes:
  • Status: Active → Resolved
  • Remaining Work: 8.0 → 0 hours
  • Add AI-generated comment

💰 Cost: $0.15 (3,000 input, 1,200 output tokens)

Apply these changes? (y/n): y

✓ Work item 12345 updated successfully!
View at: https://dev.azure.com/YourOrg/...

How It Works

Workflow

Fetch: Retrieves work item details from Azure DevOps using the REST API
Analyze: Sends work item context to Claude AI for intelligent analysis
Display: Shows AI-generated analysis, solution, tasks, and risks
Confirm: Prompts for user confirmation (Web UI or CLI)
Update: Updates work item status, adds AI-generated comment, and applies tags

Architecture

┌─────────────────────┐         ┌──────────────────────┐
│   Web UI / CLI      │────────>│  Workflow Service    │
└─────────────────────┘         └──────────────────────┘
                                         │
                        ┌────────────────┼────────────────┐
                        │                │                │
                        v                v                v
               ┌─────────────┐  ┌──────────────┐  ┌──────────────┐
               │Azure DevOps │  │  Claude AI   │  │   Database   │
               │   Client    │  │    Client    │  │  (Settings)  │
               └─────────────┘  └──────────────┘  └──────────────┘

Azure DevOps Setup

Creating a Personal Access Token (PAT)

Go to Azure DevOps: https://dev.azure.com/{YourOrganization}
Click your profile icon → Personal access tokens
Click + New Token
Configure the token:
- Name: ADO AI
- Expiration: Choose your preferred duration
- Scopes:
  - Work Items: Read & Write
  - Project and Team: Read
Click Create and copy the token immediately
Use in web setup wizard or paste in .env file

Required Permissions

Work Items: Read, Write (to fetch and update work items)
Project and Team: Read (to access project information)

Anthropic API Setup

Sign up at Anthropic Console
Go to API Keys section
Create a new API key
Copy and use in setup wizard or paste in .env file

Pricing

Claude Opus 4.6: $5 per million input tokens, $25 per million output tokens
Claude Sonnet 4.5: $1 per million input tokens, $5 per million output tokens

Typical work item analysis costs $0.10-$0.30 per work item.

Project Structure

azure_devops/
├── .env                         # Environment variables (git-ignored)
├── .env.example                 # Template for environment variables
├── .gitignore                   # Git ignore rules
├── README.md                    # This file
├── pyproject.toml               # Python project configuration
├── alembic.ini                  # Database migration config
├── ado_ai.db                    # SQLite database (auto-created)
│
├── scripts/                     # Utility scripts
│   └── generate_cert.py         # SSL certificate generator
│
├── certs/                       # SSL certificates (git-ignored)
│   ├── cert.pem                 # SSL certificate (auto-generated)
│   └── key.pem                  # Private key (auto-generated)
│
└── src/
    ├── ado_ai_cli/              # CLI Package
    │   ├── __init__.py
    │   ├── __main__.py          # CLI entry point
    │   ├── cli.py               # Typer CLI commands
    │   ├── config.py            # Configuration management
    │   │
    │   ├── core/                # Business logic
    │   │   ├── workflow.py      # Main orchestration (refactored)
    │   │   └── presenter.py     # CLI display logic
    │   │
    │   ├── azure_devops/        # Azure DevOps integration
    │   │   ├── client.py        # Azure DevOps API client
    │   │   └── models.py        # Work item data models
    │   │
    │   ├── ai/                  # AI integration
    │   │   ├── claude_client.py # Anthropic Claude client
    │   │   └── prompts.py       # Prompt templates
    │   │
    │   └── utils/               # Utilities
    │       ├── logger.py        # Logging setup
    │       └── exceptions.py    # Custom exceptions
    │
    └── ado_ai_web/              # Web Service Package
        ├── main.py              # FastAPI application
        │
        ├── api/                 # REST API endpoints
        │   ├── setup.py         # Setup wizard endpoints
        │   ├── config.py        # Configuration endpoints
        │   └── work_items.py    # Work item endpoints
        │
        ├── services/            # Business logic
        │   ├── encryption.py    # Credential encryption
        │   ├── settings_manager.py  # Database CRUD
        │   └── workflow_service.py  # Workflow wrapper
        │
        ├── models/              # Data models
        │   ├── database.py      # SQLAlchemy ORM models
        │   ├── requests.py      # API request models
        │   └── responses.py     # API response models
        │
        ├── database/            # Database layer
        │   ├── session.py       # SQLAlchemy session
        │   └── migrations/      # Alembic migrations
        │
        ├── templates/           # Jinja2 templates
        │   ├── base.html        # Base layout
        │   ├── setup.html       # Setup wizard
        │   ├── dashboard.html   # Main dashboard
        │   └── work_item_detail.html  # Analysis UI
        │
        ├── static/              # Static assets
        │   ├── css/             # Stylesheets
        │   └── js/              # JavaScript
        │
        └── middleware/          # Custom middleware
            └── security.py      # Security middleware

Security Best Practices

✅ HTTPS enabled by default - Self-signed certificates for secure communication
✅ Credentials encrypted at rest with AES-256 (Fernet)
✅ Master encryption key stored in environment variable
✅ Never commit .env, database, or SSL certificates to version control
✅ Use minimal PAT permissions (principle of least privilege)
✅ Set PAT expiration dates and rotate regularly
✅ CSRF protection ready for production
✅ Comprehensive audit logging of all operations
✅ Path traversal protection for file operations
✅ Secure session management with encrypted cookies

Troubleshooting

Web Service Issues

Error: "ENCRYPTION_MASTER_KEY not set"

Solution: Set the environment variable with a secure key
Generate one with: python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"

Error: "Database not found"

Solution: Run the server once to auto-create the database
Or run: alembic upgrade head

Configuration Errors

Error: "Failed to load configuration"

Solution: Complete setup wizard in web UI, or ensure .env file exists for CLI
Run ado-ai config validate for CLI

Authentication Errors

Error: "Invalid PAT or insufficient permissions"

Solution: Check that your Azure DevOps PAT is valid and has required permissions
Use "Test Connection" in web UI to validate
Ensure the PAT hasn't expired

Error: "Claude API error"

Solution: Verify your Anthropic API key is valid
Check available credits in your Anthropic account
Use "Test Connection" to validate

Work Item Not Found

Error: "Work item {id} not found"

Solution: Verify the work item ID exists in your project
Ensure you have permission to view the work item
Check that the project name matches

Development

Running from Source

# CLI
python -m ado_ai_cli complete 12345

# Web Service
python -m ado_ai_web.main

Running Tests

# Install dev dependencies
pip install -e ".[dev]"

# Run tests
pytest

# Run with coverage
pytest --cov=ado_ai_cli --cov=ado_ai_web --cov-report=term-missing

Database Migrations

# Create a new migration
alembic revision --autogenerate -m "Description"

# Apply migrations
alembic upgrade head

# Rollback one migration
alembic downgrade -1

Contributing

Contributions are welcome! Please:

Fork the repository
Create a feature branch
Make your changes
Add tests if applicable
Submit a pull request

License

MIT License

Support

For issues, questions, or feedback:

Create an issue on GitHub
Check the troubleshooting section above
Review Azure DevOps and Anthropic API documentation

Acknowledgments

Built with FastAPI for web service
Built with Typer for CLI
Uses Rich for beautiful terminal output
Powered by Claude AI from Anthropic
Integrates with Azure DevOps REST API
UI built with Tailwind CSS and Alpine.js
Database management with SQLAlchemy and Alembic

Made with ❤️ and 🤖 AI

Name		Name	Last commit message	Last commit date
Latest commit History 2 Commits
.claude		.claude
scripts		scripts
src		src
.env.example		.env.example
.gitignore		.gitignore
README.md		README.md
ado_ai.db		ado_ai.db
ado_ai.db.backup		ado_ai.db.backup
alembic.ini		alembic.ini
pyproject.toml		pyproject.toml
requirements.txt		requirements.txt
reset_database.py		reset_database.py
server_config.example.json		server_config.example.json

spinezhang/ado_ai

Folders and files

Latest commit

History

Repository files navigation