agentready 2.20.1

Assess and bootstrap git repositories for AI-assisted development with automated remediation and continuous learning

AgentReady Repository Scorer

Assess git repositories against evidence-based attributes for AI-assisted development readiness.

📚 Research-Based Assessment: AgentReady's attributes are derived from comprehensive research analyzing 50+ authoritative sources including Anthropic, Microsoft, Google, ArXiv, and IEEE/ACM. Each attribute is backed by peer-reviewed research and industry best practices. View full research report →

Overview

AgentReady evaluates your repository across multiple dimensions of code quality, documentation, testing, and infrastructure to determine how well-suited it is for AI-assisted development workflows. The tool generates comprehensive reports with:

• Overall Score & Certification: Platinum/Gold/Silver/Bronze based on comprehensive attribute assessment
• Interactive HTML Reports: Filter, sort, and explore findings with embedded guidance
• Version-Control-Friendly Markdown: Track progress over time with git-diffable reports
• Actionable Remediation: Specific tools, commands, and examples to improve each attribute
• Schema Versioning: Backwards-compatible report format with validation and migration tools

Quick Start

Container (Recommended)

# Login to GitHub Container Registry (required for private image)
podman login ghcr.io

# Pull container
podman pull ghcr.io/ambient-code/agentready:latest

# Create output directory
mkdir -p ~/agentready-reports

# Assess AgentReady itself
git clone https://github.com/ambient-code/agentready /tmp/agentready
podman run --rm \
  -v /tmp/agentready:/repo:ro \
  -v ~/agentready-reports:/reports \
  ghcr.io/ambient-code/agentready:latest \
  assess /repo --output-dir /reports

# Assess your repository
# For large repos, add -i flag to confirm the size warning
podman run --rm \
  -v /path/to/your/repo:/repo:ro \
  -v ~/agentready-reports:/reports \
  ghcr.io/ambient-code/agentready:latest \
  assess /repo --output-dir /reports

# Open reports
open ~/agentready-reports/report-latest.html

See full container documentation →

Python Package

# Install
pip install agentready

# Assess AgentReady itself
git clone https://github.com/ambient-code/agentready /tmp/agentready
agentready assess /tmp/agentready

# Create virtual environment
python3 -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

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

Run Directly via uv (Optional, No Install Required)

If you use uv, you can run AgentReady directly from GitHub without cloning or installing:

uvx --from git+https://github.com/ambient-code/agentready agentready -- assess .

To install it as a reusable global tool:

uv tool install --from git+https://github.com/ambient-code/agentready agentready

After installing globally:

agentready assess .

Harbor CLI (for Benchmarks)

Harbor is required for running Terminal-Bench evaluations:

# AgentReady will prompt to install automatically, or install manually:
uv tool install harbor

# Alternative: Use pip if uv is not available
pip install harbor

# Verify installation
harbor --version

Skip automatic checks: If you prefer to skip the automatic Harbor check (for advanced users):

agentready benchmark --skip-preflight --subset smoketest

Assessment Only

For one-time analysis without infrastructure changes:

# Assess current repository
agentready assess .

# Assess another repository
agentready assess /path/to/your/repo

# Specify custom configuration
agentready assess /path/to/repo --config my-config.yaml

# Custom output directory
agentready assess /path/to/repo --output-dir ./reports

Example Output

Assessing repository: myproject
Repository: /Users/username/myproject
Languages detected: Python (42 files), JavaScript (18 files)

Evaluating attributes...
[████████████████████████░░░░░░░░] 23/25 (2 skipped)

Overall Score: 72.5/100 (Silver)
Attributes Assessed: 23/25
Duration: 2m 7s

Reports generated:
  HTML: .agentready/report-latest.html
  Markdown: .agentready/report-latest.md

Features

Evidence-Based Attributes

Evaluated across 13 categories:

1. Context Window Optimization: CLAUDE.md files, concise docs, file size limits
2. Documentation Standards: README structure, inline docs, ADRs
3. Code Quality: Cyclomatic complexity, file length, type annotations, code smells
4. Repository Structure: Standard layouts, separation of concerns
5. Testing & CI/CD: Coverage, test naming, pre-commit hooks
6. Dependency Management: Lock files, freshness, security
7. Git & Version Control: Conventional commits, gitignore, templates
8. Build & Development: One-command setup, dev docs, containers
9. Error Handling: Clear messages, structured logging
10. API Documentation: OpenAPI/Swagger specs
11. Modularity: DRY principle, naming conventions
12. CI/CD Integration: Pipeline visibility, branch protection
13. Security: Scanning automation, secrets management

Tier-Based Scoring

Attributes are weighted by importance:

• Tier 1 (Essential): 50% of total score - CLAUDE.md, README, types, layouts, lock files
• Tier 2 (Critical): 30% of total score - Tests, commits, build setup
• Tier 3 (Important): 15% of total score - Complexity, logging, API docs
• Tier 4 (Advanced): 5% of total score - Security scanning, performance benchmarks

Missing essential attributes (especially CLAUDE.md at 10% weight) has 10x the impact of missing advanced features.

Interactive HTML Reports

• Filter by status (Pass/Fail/Skipped)
• Sort by score, tier, or category
• Search attributes by name
• Collapsible sections with detailed evidence
• Color-coded score indicators
• Certification ladder visualization
• Works offline (no CDN dependencies)

Customization

Create .agentready-config.yaml to customize weights:

weights:
  claude_md_file: 0.15      # Increase importance (default: 0.10)
  test_coverage: 0.05       # Increase importance (default: 0.03)
  conventional_commits: 0.01  # Decrease importance (default: 0.03)
  # Other attributes use defaults, rescaled to sum to 1.0

excluded_attributes:
  - performance_benchmarks  # Skip this attribute

output_dir: ./custom-reports

CLI Reference

# Assessment commands
agentready assess PATH                   # Assess repository at PATH
agentready assess PATH --verbose         # Show detailed progress
agentready assess PATH --config FILE     # Use custom configuration
agentready assess PATH --output-dir DIR  # Custom report location

# Configuration commands
agentready --validate-config FILE        # Validate configuration
agentready --generate-config             # Create example config

# Research report management
agentready research-version              # Show bundled research version
agentready research validate FILE        # Validate research report
agentready research init                 # Generate new research report
agentready research add-attribute FILE   # Add attribute to report
agentready research bump-version FILE    # Update version
agentready research format FILE          # Format research report

# Utility commands
agentready --version                     # Show tool version
agentready --help                        # Show help message

Architecture

AgentReady follows a library-first design:

• Models: Data entities (Repository, Assessment, Finding, Attribute)
• Assessors: Independent evaluators for each attribute category
• Services: Scanner (orchestration), Scorer (calculation), LanguageDetector
• Reporters: HTML and Markdown report generators
• CLI: Thin wrapper orchestrating assessment workflow

Development

Run Tests

# Run all tests with coverage
pytest

# Run specific test suite
pytest tests/unit/
pytest tests/integration/
pytest tests/contract/

# Run with verbose output
pytest -v -s

Code Quality

# Format code
black src/ tests/

# Sort imports
isort src/ tests/

# Lint code
flake8 src/ tests/ --ignore=E501

# Run all checks
black . && isort . && flake8 .

Project Structure

src/agentready/
├── cli/              # Click-based CLI entry point
├── assessors/        # Attribute evaluators (13 categories)
├── models/           # Data entities
├── services/         # Core logic (Scanner, Scorer)
├── reporters/        # HTML and Markdown generators
├── templates/        # Jinja2 HTML template
└── data/             # Bundled research report and defaults

tests/
├── unit/             # Unit tests for individual components
├── integration/      # End-to-end workflow tests
├── contract/         # Schema validation tests
└── fixtures/         # Test repositories

Research Foundation

All attributes are derived from evidence-based research with 50+ citations from:

• Anthropic (Claude Code documentation, engineering blog)
• Microsoft (Code metrics, Azure DevOps best practices)
• Google (SRE handbook, style guides)
• ArXiv (Software engineering research papers)
• IEEE/ACM (Academic publications on code quality)

See src/agentready/data/RESEARCH_REPORT.md for complete research report.

License

MIT License - see LICENSE file for details.

Contributing

Contributions welcome! Please ensure:

• All tests pass (pytest)
• Code is formatted (black, isort)
• Linting passes (flake8)
• Test coverage >80%

Support

• Documentation: See /docs directory
• Issues: Report at GitHub Issues
• Questions: Open a discussion on GitHub

---

Quick Start: pip install -e ".[dev]" && agentready assess . - Ready in <5 minutes!