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

  1. Clone the repository
git clone https://github.com/MauGx3/ai-tools.git
cd ai-tools
  1. Create and activate a virtual environment (recommended)
python -m venv .venv
source .venv/bin/activate.fish
  1. 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.