RepoBoost

RepoBoost is a Python command-line tool that audits GitHub repositories and suggests practical improvements for better open-source presentation. It helps developers make their repositories easier to understand, trust, install, fix, document, and share.

What RepoBoost Checks

RepoBoost looks for the details that make a repository more useful for visitors, recruiters, contributors, and other developers.

It checks for:

• README quality
• License file
• .gitignore
• Installation instructions
• Usage examples
• Screenshots or visual media
• Demo or live links
• README badges
• Contributing guide
• Tests
• GitHub Actions workflow
• Repository score and grade

Installation

Install RepoBoost from PyPI:

pip install repoboost

Verify the installation:

repoboost --version

Expected output:

RepoBoost 0.3.0

Quick Start

Scan the current repository:

repoboost scan .

Analyze README structure:

repoboost readme .

Show only missing README items:

repoboost readme . --missing-only

Show the most important improvement priorities:

repoboost doctor .

Get project-specific recommendations:

repoboost recommend .

Preview common repository fixes:

repoboost fix .

Apply common repository fixes:

repoboost fix . --apply

Generate a Markdown report:

repoboost report . --output REPOBOOST_REPORT.md

List built-in scoring presets:

repoboost presets

Create a configurable scoring file:

repoboost init-config . --preset portfolio-project

Example Output

RepoBoost Score: 72/100 - Grade C

MISS  Screenshots or media 0/10   No screenshots or visual media detected.
MISS  Badges               0/6    No README badges detected.
MISS  Contributing guide   0/6    No contributing guide found.
MISS  CI workflow          0/6    No GitHub Actions workflow detected.

Next best improvements:
1. Add a screenshot, GIF, or demo image to make the repository easier to understand quickly.
2. Add small badges for license, tests, or package version after the project title.
3. Add CONTRIBUTING.md if you want other developers to contribute.

Main Features

• Scores a repository from 0 to 100
• Gives a grade from A to F
• Supports configurable scoring with .repoboost.toml
• Includes built-in scoring presets
• Supports custom check weights
• Supports disabled checks
• Shows the active scoring profile in scan reports
• Detects README, license, .gitignore, tests, and CI
• Detects installation and usage sections
• Detects screenshots, badges, and demo links
• Analyzes README structure and completeness
• Detects missing README sections
• Generates README-specific recommendations
• Exports README analysis as Markdown or JSON
• Gives practical next-step suggestions
• Shows top improvement priorities with doctor mode
• Suggests useful GitHub topics
• Detects project type, languages, frameworks, and tools
• Recommends project-specific next steps
• Generates Markdown audit reports
• Generates common repository improvement files
• Supports dry-run fixes before writing files
• Generates a RepoBoost README badge
• Generates a GitHub Actions workflow for CI usage
• Saves scan reports as JSON files
• Supports JSON output for automation
• Supports score thresholds for CI usage

Commands

scan

Run a full repository audit:

repoboost scan .

Scan another local repository:

repoboost scan path/to/project

Useful options:

repoboost scan . --json
repoboost scan . --output repoboost-report.json
repoboost scan . --fail-under 90
repoboost scan . --config .repoboost.toml

doctor

Show the most important missing improvements:

repoboost doctor .

Use a custom config file:

repoboost doctor . --config .repoboost.toml

fix

Preview common repository improvement files without writing anything:

repoboost fix .

Apply the suggested files:

repoboost fix . --apply

Generate an MIT license too:

repoboost fix . --apply --license mit --author "Mohammad Azimi"

Print fix actions as JSON:

repoboost fix . --json

Overwrite existing files:

repoboost fix . --apply --force

Currently, repoboost fix can generate:

• .gitignore
• CONTRIBUTING.md
• .github/workflows/repoboost.yml
• LICENSE when --license mit is used

By default, repoboost fix runs in dry-run mode. It shows what would be created or skipped, but it does not write files until --apply is used.

readme

Analyze README structure and completeness:

repoboost readme .

The README analyzer checks for:

• project title
• project description
• installation section
• usage section
• features section
• contributing section
• license section

Show only missing README items:

repoboost readme . --missing-only

Print README analysis as JSON:

repoboost readme . --json

Save the analysis as a Markdown file:

repoboost readme . --output README_RECOMMENDATIONS.md

The analyzer recognizes common alternative section names such as Setup, Getting Started, Quick Start, and How to Use.

recommend

Show project-specific recommendations:

repoboost recommend .

Print recommendations as JSON:

repoboost recommend . --json

Use a custom config file:

repoboost recommend . --config .repoboost.toml

report

Generate a Markdown report from the repository audit:

repoboost report .

Save the report to a file:

repoboost report . --output REPOBOOST_REPORT.md

Show only missing checks in the audit table:

repoboost report . --missing-only

Use a custom config file:

repoboost report . --config .repoboost.toml

presets

List built-in scoring presets:

repoboost presets

Print presets as JSON:

repoboost presets --json

Available presets:

• default
• python-cli
• web-app
• machine-learning
• portfolio-project
• docs-only

init-config

Create a .repoboost.toml file:

repoboost init-config .

Create a config file with a built-in preset:

repoboost init-config . --preset python-cli
repoboost init-config . --preset web-app
repoboost init-config . --preset machine-learning
repoboost init-config . --preset portfolio-project
repoboost init-config . --preset docs-only

Overwrite an existing config file:

repoboost init-config . --force

Create a config file with a custom profile name:

repoboost init-config . --profile my-project-profile

topics

Suggest useful GitHub topics:

repoboost topics .

Print topic suggestions as JSON:

repoboost topics . --json

inspect

Detect project type, languages, frameworks, tools, and important files:

repoboost inspect .

Print the detected project profile as JSON:

repoboost inspect . --json

badge

Generate a Markdown badge based on the repository score:

repoboost badge .

Example badge output:

![RepoBoost](https://img.shields.io/badge/RepoBoost-A%20%7C%20100%25-brightgreen)

ci

Generate a GitHub Actions workflow for running RepoBoost in CI:

repoboost ci .

Save the workflow to a file:

repoboost ci . --output .github/workflows/repoboost.yml

Set a required score threshold:

repoboost ci . --fail-under 80

Repository Fixes

RepoBoost can help create common repository files.

Preview the fixes first:

repoboost fix .

Apply the fixes:

repoboost fix . --apply

Generate an MIT license:

repoboost fix . --apply --license mit --author "Mohammad Azimi"

The fix command is intentionally safe by default.

Without --apply, it only shows a dry run. This makes it easier to review changes before writing anything to disk.

Example dry-run output:

RepoBoost Fix
Mode: Dry run

would_create  .gitignore
would_create  CONTRIBUTING.md
would_create  .github/workflows/repoboost.yml

Example apply output:

RepoBoost Fix
Mode: Apply

created  .gitignore
created  CONTRIBUTING.md
created  .github/workflows/repoboost.yml
created  LICENSE

Built-in Scoring Presets

RepoBoost includes built-in scoring presets for different repository types.

List all presets:

repoboost presets

Print presets as JSON:

repoboost presets --json

Use a preset when creating a config file:

repoboost init-config . --preset portfolio-project

Available Presets

Preset	Best For
default	Balanced scoring for general repositories
python-cli	Python command-line tools and installable packages
web-app	Deployed web apps, dashboards, and frontend/backend projects
machine-learning	ML, computer vision, data science, and experiment-based repositories
portfolio-project	Projects that should look strong to recruiters, supervisors, or visitors
docs-only	Documentation-first repositories without code execution requirements

Presets help RepoBoost score repositories more fairly based on the type of project.

For example:

• A Python CLI package may need stronger installation, usage, tests, and CI checks.
• A web app may need stronger screenshots, demo links, and deployment-focused presentation.
• A machine learning project may need stronger examples, visual outputs, results, and reproducibility notes.
• A portfolio project may need stronger visual presentation and a clear demo.
• A docs-only project may not need tests, CI, screenshots, or a live demo.

Configurable Scoring

RepoBoost can use a .repoboost.toml file to customize scoring for different repository types.

Create a default config file:

repoboost init-config .

Create a config file using a preset:

repoboost init-config . --preset machine-learning

Example .repoboost.toml:

profile = "python-cli"
preset = "python-cli"
fail_under = 90
disabled_checks = []

[weights]
readme = 18
license = 12
gitignore = 8
installation = 12
usage = 12
screenshots = 6
demo_link = 4
badges = 6
contributing = 6
tests = 10
ci = 6

[recommendations]
focus = [
  "documentation",
  "automation",
  "distribution",
  "code-quality"
]

You can adjust the score weight of each check depending on the type of project.

You can also disable checks that do not make sense for a specific repository:

disabled_checks = ["screenshots", "demo_link"]

Markdown Reports

RepoBoost can generate a Markdown report from the repository audit.

Print a report in the terminal:

repoboost report .

Save a report to a file:

repoboost report . --output REPOBOOST_REPORT.md

Generate a report with only missing checks:

repoboost report . --missing-only

A generated report includes:

• repository summary
• score and grade
• active scoring profile
• audit results table
• recommendation table
• next-step suggestions

This is useful for:

• project reviews
• portfolio project tracking
• repository improvement plans
• sharing audit results with teammates
• documenting before-and-after improvements

JSON Output

RepoBoost supports JSON output for automation and CI workflows.

Examples:

repoboost scan . --json
repoboost readme . --json
repoboost fix . --json

Save a scan result to a file:

repoboost scan . --output repoboost-report.json

This can be useful for:

• CI checks
• dashboards
• automated repository audits
• documentation analysis
• portfolio project tracking

CI Usage

RepoBoost can fail a command if the score is below a required threshold:

repoboost scan . --fail-under 80

This is useful when you want to keep repository presentation quality above a minimum score.

You can also generate a GitHub Actions workflow:

repoboost ci . --output .github/workflows/repoboost.yml

Why RepoBoost?

Many repositories contain useful code, but visitors may leave quickly if the project is not presented clearly.

A strong repository should answer these questions quickly:

• What does this project do?
• Who is it for?
• How do I install it?
• How do I use it?
• What are its main features?
• Can I trust it?
• Is it maintained?
• Are there examples, tests, or screenshots?

RepoBoost helps developers improve these details with clear checks, README analysis, scoring presets, Markdown reports, and safe fix helpers.

Development

Clone the repository:

git clone https://github.com/mohammad-azimi/RepoBoost.git
cd RepoBoost

Create and activate a virtual environment:

python -m venv .venv
.venv\Scripts\activate

Install the project in editable mode:

pip install -e ".[dev]"

Run the test suite:

pytest

Build the package locally:

python -m build
python -m twine check dist/*

Run RepoBoost on itself:

repoboost scan . --fail-under 90

Analyze its README:

repoboost readme .

Preview fix actions:

repoboost fix .

List presets:

repoboost presets

Generate a Markdown report:

repoboost report . --output REPOBOOST_REPORT.md

Release History

0.3.0

README structure analysis.

Added:

• repoboost readme command
• README completeness analysis
• checks for project title and description
• checks for Installation, Usage, Features, Contributing, and License sections
• support for common alternative section names
• --missing-only option
• --json output
• Markdown report output with --output
• README-specific recommendations
• dedicated README analyzer tests
• CLI tests for README analysis

0.2.0

Repository fix command.

Added:

• repoboost fix command
• dry-run mode for safe fix previews
• --apply option for writing generated files
• --force option for overwriting existing files
• --license mit option for generating an MIT license
• --author option for generated license ownership
• JSON output for fix actions
• .gitignore generation
• CONTRIBUTING.md generation
• RepoBoost GitHub Actions workflow generation
• tests for repository fix actions

0.1.3

Built-in scoring presets.

Added:

• repoboost presets command
• --preset option for repoboost init-config
• built-in scoring presets for different repository types
• default preset
• python-cli preset
• web-app preset
• machine-learning preset
• portfolio-project preset
• docs-only preset
• preset-aware config generation
• tests for scoring presets

0.1.2

Markdown report generation.

Added:

• repoboost report command
• Markdown audit report generation
• --output support for saving reports
• --missing-only option for reports
• recommendation tables inside generated reports
• next-step suggestions inside generated reports
• tests for Markdown report generation

0.1.1

Configurable scoring and smarter recommendations.

Added:

• .repoboost.toml support
• repoboost init-config
• custom check weights
• disabled checks
• scoring profile display
• --config support for scan, doctor, recommend, and badge
• configuration-aware recommendations
• tests for configurable scoring

0.1.0

Initial PyPI release.

Added:

• repository scoring
• scan command
• doctor command
• topics command
• inspect command
• recommend command
• badge command
• CI workflow generator
• JSON output
• report saving
• score thresholds

Full release notes are available in:

CHANGELOG.md

Release documentation is available in:

docs/RELEASE.md
docs/TESTPYPI.md
docs/PYPI.md

Roadmap

• Add automatic README section generation
• Add more project-type specific recommendations
• Add portfolio-readiness score
• Add repository comparison mode
• Add optional auto-fix helpers for common README sections
• Add Markdown report templates
• Add richer before-and-after examples

Contributing

Contributions are welcome.

Please read CONTRIBUTING.md before opening a pull request.

License

This project is licensed under the MIT License.

You are free to use, modify, and distribute this project, as long as the original license and copyright notice are included.

See the LICENSE file for more details.