Project Structure Checker

Hey everyone!

I made a small CLI tool called PSX that checks and fixes the basic structure of a project so you don't have to repeat the same boring setup every time. I built it because whenever I start a repo I end up creating the same README, LICENSE, .gitignore, changelog and the usual files. PSX detects the project type, tells you what's missing, and can even create the files for you.

What it does

PSX auto-detects project type (Node, Go, etc.) and runs a set of rules to ensure the repo has the essentials. If something’s missing you can run psx fix and it creates sensible defaults. Rules are configurable via a simple YAML and checks run in parallel so it’s fast even on bigger repos.

Features

Automatic detection of project type and basic scaffolding. Auto-fix mode that creates missing files and folders. Support for multiple languages (Node.js, Go, generic projects). Configurable rules via a simple YAML file.

Installation

Quick install

Linux / macOS

curl -sSL https://raw.githubusercontent.com/m-mdy-m/psx/main/scripts/install.sh | bash

Windows

Invoke-WebRequest -Uri "https://raw.githubusercontent.com/m-mdy-m/psx/main/scripts/install.ps1" -OutFile install.ps1; .\install.ps1 github

Download binary

Pre-built releases are available on GitHub for Linux (amd64, arm64), macOS (amd64, arm64) and Windows (amd64). Check Releases on the repo.

Build from source

git clone https://github.com/m-mdy-m/psx
cd psx
make build
sudo make install

Docker

docker pull bitsgenix/psx:latest
docker run --rm -v $(pwd):/project psx:latest check

Quick start

cd my-project
psx check

If PSX finds missing or weak items you can auto-fix:

psx fix

To confirm each change:

psx fix --interactive

Example config (psx.yml)

Drop this in the repo root. PSX will auto-detect if you leave type empty.

version: 1
project:
  type: "go"
rules:
  readme: error
  license: warning
  gitignore: warning
  changelog: info

How auto-fix works

psx fix reads your rules, figures out what’s missing, and creates sensible defaults for README, .gitignore, LICENSE, etc. LICENSE uses standard templates; README is minimal (name, short description, install/run hints). --interactive asks before applying each change.

Development notes

PSX is written in Go and needs Go 1.25+ to build. The code is modular so detectors and rules can be extended. Right now the repo doesn’t include tests (that’s intentional for v1), so if you want to help the project a lot: add tests or lint rules — that’s very welcome.

Why I made it

Every new project felt like repeating the same first 10 minutes of setup. I wanted a tiny tool that enforces a sane baseline so I can start coding faster and keep repos consistent.

Future enhancements (not in v1)

Plugin system for custom rules — let people add/share custom rule sets.
Multi-project scanning — scan multiple repositories at once.
Git pre-commit hook integration — run checks locally before commits.
Language support: Python, Rust, Java — expand detectors and templates.
Better code structure and quality improvements — refactor, cleaner modules, more tests.
Editor/CI integrations — VS Code extension, CI checks.
Other usability improvements — templates, more interactive flows.

A note about v1

This is the first public version. It’s normal for v1 to have bugs or missing features, so please try it and tell me what breaks or what feels wrong. Use it, open issues, and give feedback — that’s how it gets better.

If you want to help

If you like the idea, please star the repo. Contributions that are most useful right now: add tests, write linters, create new language detectors, improve templates, or send small fixes. Open issues or PRs and I’ll review.

Links & support

Repository: https://github.com/m-mdy-m/psx
Issues: https://github.com/m-mdy-m/psx/issues
Releases: https://github.com/m-mdy-m/psx/releases

Thanks for reading. If you try PSX, tell me what files you always add when starting a project — I’ll consider adding them to default templates. Let’s discuss.