Getting started

This tutorial helps a new contributor or user get the repository running locally and run the primary scripts (a small starred-repository scanner and recommender) so you can inspect results quickly.

Audience: new contributors and users (novice-to-intermediate developers)

What you’ll achieve

Install the project dependencies
Run the main scanner script and inspect the output

Prerequisites

macOS, Linux, or WSL on Windows
Python 3.10+ (3.11 recommended)
Git

Install steps

Clone the repository

git clone https://github.com/MauGx3/ai-tools.git
cd ai-tools

Create and activate a virtual environment (recommended)

python -m venv .venv
source .venv/bin/activate.fish

Install Python dependencies

The repository keeps Python requirements for scripts inside scripts/requirements.txt.

pip install -r scripts/requirements.txt

Run the scanner (quick smoke test)

This project contains example scripts under scripts/.

python scripts/scan_starred_repos.py --help
# or
python scripts/repo_recommender.py --help

Expectations

The --help output lists available options.
When run with defaults, scripts will write results to scripts/results/ or results/ (check script docstrings/comments).

Troubleshooting

If Python packages fail to install, upgrade pip: pip install -U pip.
If you see permission errors, ensure the virtualenv is activated and you are not using a system Python with restricted write access.
If a script references environment variables, see docs/explain/design-and-memory-bank.md for guidance about secrets and secure configuration.

Next steps

Read the How‑to guide: “Add a prompt or instruction” to learn how to contribute new prompts and instruction files.
See the Reference for a concise repo structure and important files.