Devscope

Universal Codebase Intelligence for CI & Teams

Analyze any repository in seconds. Get a maintainability grade, risk level, onboarding difficulty, and a CI-ready quality gate — zero configuration.

Read the engineering article: Parsing Unfamiliar Repositories into an Evidence-Based Report.

🚀 Install in 10 Seconds

pipx install devscope
devscope scan .

On macOS:

brew install devscope
devscope scan .

Or install from source:

git clone https://github.com/EhsanAzish80/Devscope.git
cd Devscope
uv sync
uv run devscope scan .

That's it. No config files. No setup. Just intelligence.

Try it now:

devscope summary --compact

Devscope: B · Low risk · Easy onboarding · 1.00 tests · 0.06s ⚡

🎯 Why devscope?

Feature	devscope	cloc	tokei
Maintainability grade	✅ A-F scoring	❌	❌
CI quality gate	✅ Exit codes	❌	❌
Multi-language repo intelligence	✅ Full context	⚠️ Basic	⚠️ Basic
Shareable PR summaries	✅ Markdown + badges	❌	❌
Intelligent caching	✅ 10-20x speedup	❌	❌
Risk & onboarding metrics	✅ Built-in	❌	❌
Test coverage detection	✅ Automatic	❌	❌

🌍 Real-World Examples

See devscope analyzing popular open-source projects:

fastapi

Devscope: A · Low risk · Moderate onboarding · 1.48 tests · 0.84s ⚡

django

Devscope: B · Low risk · Hard onboarding · 2.81 tests · 1.46s ⚡

typer

Devscope: A · Low risk · Moderate onboarding · 0.98 tests · 0.12s ⚡

requests

Devscope: B · Low risk · Easy onboarding · 1.82 tests · 0.06s ⚡

Benchmarks run on GitHub Actions (2-core Linux VM).

📊 Want more examples? See the /research directory for detailed analysis reports of popular repositories, including full markdown summaries and scan metadata.

⚡ Blazing Fast

First scan:

$ devscope scan .
✓ Analysis complete in 2.45s

Cached scan (same repo):

$ devscope scan .
✓ Analysis complete in 0.15s (cache: 100% hit rate, ~2.3s saved)

10-20x faster on large repos. Automatic cache invalidation when files change.

🧪 Devscope Analyzing Itself

This repository is continuously analyzed by devscope.

🔍 Devscope Report

Repo: Devscope
Files: 53
Lines: 10,640
Languages: Python (53%) · Markdown (21%) · Shell (11%)

Health: B (85.5)
Risk: Low
Onboarding: Easy

Tests: 0.87 ratio
Last commit: today

Top hotspot: README.md (856 LOC, Very large file (856 LOC), No nearby tests)

⚡ Scan time: 0.07s

This report is automatically updated on every push.

💡 Use Cases

CI quality gate — Fail builds on grade drops (--fail-under B)
PR health comment — One-line summary in every PR (devscope summary --compact)
Client code audit — Instant maintainability report for stakeholders
Monorepo onboarding — Estimate ramp-up time for new engineers

📝 Shareable Summaries (The Viral Feature)

Embed in Your README

devscope summary --badges > HEALTH.md

Output:

## 🔍 Devscope Report

![Maintainability](https://img.shields.io/badge/maintainability-B-green)
![Risk](https://img.shields.io/badge/risk-Low-green)
![Onboarding](https://img.shields.io/badge/onboarding-Easy-blue)

**Health:** B (82.1) · **Risk:** Low · **Onboarding:** Easy  
**Files:** 1,247 · **Lines:** 45,892 · **Tests:** 0.78 ratio

⚡ Scan time: 0.82s (cache: 100% hit rate)

PR Comment (GitHub Actions)

- name: Add health check to PR
  run: |
    devscope summary --compact >> $GITHUB_STEP_SUMMARY

Output:
Devscope: B · Low risk · Easy onboarding · 0.78 tests · 0.82s ⚡

JSON for Bots

devscope summary --json | jq '.health'

Perfect for Slack notifications, status pages, or custom integrations.

📊 Output Examples

Terminal (Default)

╔═══════════════════════════════════════╗
║     devscope v0.1.0                   ║
║  Code Intelligence at a glance        ║
╚═══════════════════════════════════════╝

📊 my-project

Repository          my-project
Health Grade        B (82.5)
Risk Level          Low
Onboarding          Easy

Total Files         1,247
Total Lines         45,892

Languages
  Python            45.2%
  TypeScript        32.8%
  JavaScript        12.1%

Tests               0.78 ratio
Top Hotspot         src/analyzer.py (321 LOC)

✓ Analysis complete in 0.82s

Compact (for PRs)

Devscope: B · Low risk · Easy onboarding · 0.78 tests · 0.82s ⚡

JSON (for automation)

{
  "health_score": {
    "maintainability_grade": "B",
    "risk_level": "Low",
    "onboarding_difficulty": "Easy",
    "score_breakdown": {
      "overall": 82.5,
      "complexity": 80.2,
      "tests": 78.0,
      "git_activity": 90.0
    }
  },
  "total_files": 1247,
  "total_lines": 45892,
  "test_ratio": 0.78,
  "scan_time": 0.82
}

📋 Full JSON Schema

{
  "analysis": {
    "complexity": {
      "avg_file_size": 368.5,
      "deep_nesting_warning": false,
      "largest_files": [
        {"file_path": "src/analyzer.py", "size_bytes": 9856}
      ],
      "max_directory_depth": 3
    },
    "dependencies": [
      {
        "ecosystem": "Python",
        "manifest_file": "pyproject.toml",
        "dependency_count": 8,
        "dependencies": ["click", "rich", "gitpython", "pathspec"]
      }
    ],
    "git_metrics": {
      "is_git_repo": true,
      "commit_count": 42,
      "contributor_count": 2,
      "days_since_last_commit": 0
    },
    "health_score": {
      "maintainability_grade": "B",
      "risk_level": "Low",
      "onboarding_difficulty": "Easy",
      "score_breakdown": {
        "overall": 82.5,
        "complexity": 80.2,
        "structure": 90.0,
        "tests": 78.0,
        "git_activity": 90.0,
        "hotspots": 85.0
      }
    },
    "hotspots": [
      {
        "file_path": "src/analyzer.py",
        "lines_of_code": 321,
        "depth": 2,
        "has_nearby_tests": true,
        "reason": "Large file with high complexity",
        "risk_score": 75.3
      }
    ],
    "languages": {
      "Python": 52.9,
      "Markdown": 17.6,
      "Shell": 11.8
    },
    "test_metrics": {
      "has_tests": true,
      "test_file_count": 8,
      "source_file_count": 12,
      "test_ratio": 0.667
    },
    "cache_stats": {
      "enabled": true,
      "hits": 55,
      "misses": 5,
      "total_files": 60,
      "hit_rate": 91.67,
      "time_saved_estimate": 0.005
    },
    "total_files": 60,
    "total_lines": 3800,
    "scan_time": 0.15
  },
  "devscope_version": "0.1.0",
  "schema_version": "1.0"
}

🤖 CI/CD Integration

Quality Gates with Exit Codes

Exit codes:

0 = Analysis passed all thresholds
1 = Runtime error (invalid path, permissions)
2 = Threshold violated (grade/risk/onboarding)

GitHub Actions

- name: Code health check
  run: |
    devscope ci . \
      --fail-under B \
      --max-risk Medium \
      --max-onboarding Moderate

If health drops below B, the job fails with exit code 2.

GitLab CI

analyze:
  script:
    - devscope ci . --fail-under B --json > analysis.json
  artifacts:
    reports:
      codequality: analysis.json

Shell Script

#!/bin/bash
devscope ci . --fail-under C

if [ $? -eq 2 ]; then
  echo "❌ Code quality below threshold"
  exit 1
fi

🎬 GitHub Action (Official)

The easiest way to integrate Devscope into your workflow — official GitHub Action with automatic PR comments and quality gates.

Quick Start

Add to .github/workflows/devscope.yml:

name: Code Health

on:
  pull_request:
  push:
    branches: [main]

permissions:
  contents: read
  pull-requests: write

jobs:
  health-check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      
      - uses: EhsanAzish80/devscope-action@v1
        with:
          fail-under: B
          max-risk: Medium

What you get:

✅ Automatic PR comments with health metrics
✅ Sticky updates (no spam)
✅ CI quality gates with configurable thresholds
✅ Fast caching (5-8s cached runs)
✅ Works on public & private repos

Advanced Usage

Use outputs in other steps:

- uses: EhsanAzish80/devscope-action@v1
  id: devscope

- name: Check critical health
  run: |
    if [ "${{ steps.devscope.outputs.grade }}" == "F" ]; then
      echo "::error::Code health is critical!"
    fi

Analyze specific directory:

- uses: EhsanAzish80/devscope-action@v1
  with:
    path: ./src
    fail-under: B

PR comment preview:

📊 Devscope Report

Maintainability: 🟢 B
Risk: 🟢 Low
Onboarding: Easy
⚡ 0.82s

Analyze your repo → pipx install devscope

Learn more: devscope-action

🤖 PR Health Bot (Drop-in)

Get instant code health in every pull request — zero setup, just copy the workflow.

Add this file to your repo: .github/workflows/devscope-pr.yml

name: Devscope PR Health Check

on:
  pull_request:
    types: [opened, synchronize, reopened]

permissions:
  contents: read
  pull-requests: write

jobs:
  devscope-health:
    name: Post Health Summary
    runs-on: ubuntu-latest
    
    steps:
      - name: Checkout code
        uses: actions/checkout@v4
        with:
          fetch-depth: 0  # Full history for git metrics

      - name: Install Python
        uses: actions/setup-python@v5
        with:
          python-version: '3.12'

      - name: Install pipx
        run: |
          python -m pip install --user pipx
          python -m pipx ensurepath
          echo "$HOME/.local/bin" >> $GITHUB_PATH

      - name: Install devscope
        run: pipx install devscope

      - name: Run Devscope analysis
        id: devscope
        run: |
          set +e  # Don't fail on non-zero exit
          OUTPUT=$(devscope summary --compact 2>&1)
          EXIT_CODE=$?
          
          # Escape output for GitHub Actions
          OUTPUT="${OUTPUT//'%'/'%25'}"
          OUTPUT="${OUTPUT//$'\n'/'%0A'}"
          OUTPUT="${OUTPUT//$'\r'/'%0D'}"
          
          echo "output=$OUTPUT" >> $GITHUB_OUTPUT
          echo "exit_code=$EXIT_CODE" >> $GITHUB_OUTPUT
          
          exit 0  # Always succeed job

      - name: Post or update PR comment
        uses: actions/github-script@v7
        with:
          script: |
            const output = `${{ steps.devscope.outputs.output }}`;
            const exitCode = `${{ steps.devscope.outputs.exit_code }}`;
            
            let commentBody;
            if (exitCode === '0') {
              commentBody = `## 🔍 Devscope Health Check\n\n\`\`\`\n${output}\n\`\`\`\n\n---\n*Updated: ${new Date().toUTCString()}*`;
            } else {
              commentBody = `## 🔍 Devscope Health Check\n\n⚠️ **Analysis failed**\n\n<details>\n<summary>Error output</summary>\n\n\`\`\`\n${output}\n\`\`\`\n</details>\n\n---\n*Updated: ${new Date().toUTCString()}*`;
            }
            
            // Find existing Devscope comment
            const { data: comments } = await github.rest.issues.listComments({
              owner: context.repo.owner,
              repo: context.repo.repo,
              issue_number: context.issue.number,
            });
            
            const existingComment = comments.find(comment => 
              comment.user.type === 'Bot' &&
              comment.body.includes('🔍 Devscope Health Check')
            );
            
            if (existingComment) {
              // Update existing comment
              await github.rest.issues.updateComment({
                owner: context.repo.owner,
                repo: context.repo.repo,
                comment_id: existingComment.id,
                body: commentBody,
              });
              console.log('Updated existing Devscope comment');
            } else {
              // Create new comment
              await github.rest.issues.createComment({
                owner: context.repo.owner,
                repo: context.repo.repo,
                issue_number: context.issue.number,
                body: commentBody,
              });
              console.log('Created new Devscope comment');
            }

What it does:

Runs on every PR (open, update, reopen)
Installs devscope and analyzes your code
Posts a sticky comment that updates automatically on new commits
Fails gracefully if analysis errors
No secrets required — works on public repos

Example PR comment:

## 🔍 Devscope Health Check

Devscope: B · Low risk · Easy onboarding · 0.78 tests · 0.82s ⚡

---
Updated: Thu, 13 Feb 2026 14:52:33 GMT

Features:

✅ Sticky comment (updates instead of spamming)
✅ Shows health trend over PR lifetime
✅ Zero configuration
✅ Works on forks (read-only)

📖 Command Reference

`devscope scan`

Analyze a codebase with beautiful terminal output.

devscope scan                    # Current directory
devscope scan /path/to/project   # Specific path
devscope scan --json             # JSON output
devscope scan --basic            # Fast scan (no intelligence)
devscope scan --no-git           # Skip git detection
devscope scan --no-cache         # Disable caching
devscope scan --clear-cache      # Clear cache before scan

`devscope ci`

CI-optimized command (always outputs JSON).

devscope ci                      # Current directory
devscope ci --fail-under B       # Fail if grade < B
devscope ci --max-risk High      # Fail if risk > High
devscope ci --max-onboarding Hard   # Fail if onboarding > Hard

`devscope summary`

Generate shareable summaries.

devscope summary                 # Markdown report
devscope summary --badges        # Include shields.io badges
devscope summary --compact       # One-line summary
devscope summary --json          # JSON with badges

`devscope inject`

Inject health metrics into README between markers. Auto-updating health blocks!

devscope inject                  # Inject into ./README.md
devscope inject docs/STATUS.md   # Inject into specific file
devscope inject --check          # Check if update needed (exit 2 if yes)
devscope inject --repo ./src     # Analyze different directory

Setup: Add markers to your README:

# My Project

<!-- DEVSCOPE_START -->
<!-- DEVSCOPE_END -->

Result: Health block auto-injected between markers:

<!-- DEVSCOPE_START -->
## 🔍 Devscope Report

![Badge](https://img.shields.io/badge/maintainability-B-green)
![Badge](https://img.shields.io/badge/risk-Low-green)

**Repo:** my-project  
**Files:** 1,247  
**Lines:** 45,892  
**Languages:** Python (45%) · TypeScript (33%)

**Health:** B (82.5)  
**Risk:** Low  
**Onboarding:** Easy  

⚡ Scan time: 0.82s
<!-- DEVSCOPE_END -->

CI integration:

- name: Update health block
  run: |
    devscope inject
    if git diff --quiet README.md; then
      echo "No changes"
    else
      git config user.name "devscope-bot"
      git config user.email "bot@devscope"
      git add README.md
      git commit -m "chore: update health metrics [skip ci]"
      git push
    fi

Features:

✅ Deterministic output (no change = no commit)
✅ Automatic badge generation
✅ Custom markers supported
✅ Check mode for CI validation

🏆 Status & Quality

Metric	Value
Tests	133 passing
Coverage	82%
Type checking	mypy strict mode
Platforms	Linux · macOS · Windows
Python	3.9+

This project follows rigorous engineering standards:

✅ Full type annotations
✅ Comprehensive test suite
✅ Zero runtime dependencies conflicts
✅ Cross-platform compatibility tested

🗺️ Roadmap

✅ Completed

Maintainability grading (A-F)
Risk & onboarding assessment
CI quality gates with exit codes
Intelligent caching (10-20x speedup)
Shareable markdown summaries
Shields.io badge generation
Test coverage detection
JSON automation API

🚀 Next

Configuration file (.devscope.yml)
Historical trend tracking
Team analytics dashboard
Security scanning (CVE detection)

🛠️ Development

Quick Start

git clone https://github.com/EhsanAzish80/Devscope.git
cd Devscope
curl -LsSf https://astral.sh/uv/install.sh | sh
uv sync --all-extras
uv run devscope scan

Running Tests

uv run pytest                    # All tests
uv run pytest --cov              # With coverage
uv run pytest tests/test_analyzer.py   # Specific file

Code Quality

uv run ruff format .             # Format
uv run ruff check .              # Lint
uv run mypy src/devscope         # Type check

Project Structure

devscope/
├── src/devscope/
│   ├── cli.py          # Command-line interface
│   ├── analyzer.py     # Core analysis engine
│   ├── models.py       # Type-safe data models
│   ├── formatters.py   # Summary & badge generation
│   ├── cache.py        # Intelligent caching layer
│   └── utils.py        # Shared utilities
├── tests/
│   ├── test_analyzer.py
│   ├── test_cli.py
│   ├── test_cache.py
│   ├── test_summary.py
│   └── test_ci_thresholds.py
└── pyproject.toml      # Dependencies & config

🏗️ Architecture

Design principles:

Separation of concerns — CLI, analysis, formatting isolated
Type safety — Full mypy strict mode compliance
Performance — Smart caching with automatic invalidation
Extensibility — Plugin-ready analyzer system
User experience — Beautiful terminal output with Rich

Core components:

Analyzer — File system traversal, language detection, metrics calculation
Cache Manager — File metadata caching with invalidation on change
Formatters — Output generation (terminal/JSON/markdown/compact)
CLI — Click-based interface with rich error handling

📄 License

MIT License - see LICENSE file.

🤝 Contributing

Contributions welcome! Please:

Fork the repo
Create a feature branch (git checkout -b feature/amazing)
Run tests (./scripts/check.sh)
Submit a PR

For major changes, open an issue first.

🙏 Acknowledgments

Built with:

uv — Fast dependency management
Rich — Beautiful terminal UI
Click — CLI framework

Inspired by tokei and cloc.

FilesExpand file tree

README.md

Latest commit

History

README.md

File metadata and controls

Devscope

🚀 Install in 10 Seconds

🎯 Why devscope?

🌍 Real-World Examples

fastapi

django

typer

requests

⚡ Blazing Fast

🧪 Devscope Analyzing Itself

🔍 Devscope Report

💡 Use Cases

📝 Shareable Summaries (The Viral Feature)

Embed in Your README

PR Comment (GitHub Actions)

JSON for Bots

📊 Output Examples

Terminal (Default)

Compact (for PRs)

JSON (for automation)

🤖 CI/CD Integration

Quality Gates with Exit Codes

GitHub Actions

GitLab CI

Shell Script

🎬 GitHub Action (Official)

Quick Start

Advanced Usage

🤖 PR Health Bot (Drop-in)

📖 Command Reference

devscope scan

devscope ci

devscope summary

devscope inject

🏆 Status & Quality

🗺️ Roadmap

✅ Completed

🚀 Next

🛠️ Development

Quick Start

Running Tests

Code Quality

Project Structure

🏗️ Architecture

📄 License

🤝 Contributing

🙏 Acknowledgments

📞 Support

`devscope scan`

`devscope ci`

`devscope summary`

`devscope inject`