awesome-core
Advanced tools
Offline-first catalog of tools from GitHub awesome lists, exposed as a read-only MCP server (stdio). Pure stdlib core, no network, no API keys.
Ściąga wszystkie awesome listy z GitHuba do jednego katalogu na Twoim dysku i pozwala szybko znaleźć narzędzie — po nazwie, języku, systemie albo temacie — całkowicie bez internetu.
Na przykład chcesz „coś do OSINT-a działające pod Windows". Wpisujesz:
./awesome search osint --os windows
i dostajesz narzędzia z kilku różnych awesome list naraz, posortowane tak, że na górze są te, które niezależni kuratorzy wskazali w wielu listach (a nie tylko te z jednej głośnej listy).
Filtry łączy AND, więc kumulują się szybko.
--os windows --lang PowerShellzostawia z „osint" jedno narzędzie — i to nie to, czego szukałeś, tylko skrypt PowerShell, który akurat też nazywa się „Sherlock". Program wie, że filtr jest za wąski, i mówi wprost, który odpuścić:Uwaga: 2 filtry łączy AND i zostawiły 1 wynik(ów). bez lang=PowerShell → 8 wynikówZasada: dodawaj filtr tylko wtedy, gdy wyników jest więcej niż kilka.
./awesome start # 1. wszystko robi za Ciebie (pobiera, buduje, gotowe)
./awesome search nmap
./awesome web # i otwiera przeglądarkę
./awesome start mówi w każdym kroku, co robi i ile to potrwa. Nic działa się
samo w tle — zawsze widzisz postęp.
Jedna rzecz: Python 3.8 lub nowszy. To wszystko.
| Potrzebujesz | Po co | Sprawdzenie |
|---|---|---|
| Python 3.8+ | program — jedyna zależność | python3 --version |
Nie potrzebujesz jq, curl, GitHub CLI ani samodzielnego python -m venv:
core/api.py) — bez gh jest
wolniej, bo GitHub limituje wyszukiwanie do 10 zapytań na minutę, ale działa;./awesome web;./awesome doctor).Jeśli masz gh i się zalogujesz (gh auth login), wszystko idzie 30× szybciej
i enrich w ogóle się odblokuje. Ale to przyspieszenie, nie warunek.
Instalacja na Linuksie:
sudo apt install python3 # albo: sudo dnf install python3
Opcjonalnie, dla 30× szybszego pobierania i metadanych narzędzi:
gh auth login # GitHub CLI, jednorazowo
Windows działa bez basha. W katalogu jest awesome.cmd, więc w PowerShellu
albo po podwójnym kliknięciu piszesz po prostu:
awesome.cmd start
awesome.cmd web
download.sh został, ale to już tylko nakładka wywołująca Pythona — w nim nie
ma już ani jq, ani curl, ani pętli w shellu.
W PowerShellu odpowiedniki reszty komend:
gh auth login # potem reszta jak w Linuxie
.\venv\Scripts\Activate.ps1 # aktywacja venv
.\awesome web
Flask do web UI instaluje się sam, przy pierwszym ./awesome web:
Web UI potrzebuje Flaska. Przygotowuję środowisko (requirements.txt):
Tworzę venv…
Aktualizuję pip…
Instaluję z requirements.txt…
Gotowe. Od teraz web używa venv/.
Jeśli z jakiegoś powodu to się nie uda (brak sieci, proxy), program wypisze instrukcję ręczną — ale nie musisz jej pamiętać na co dzień.
Nie musisz znać SQL, programować, nic konfigurować w środku i nie musisz
nic aktualizować automatycznie. Jak coś nie działa — ./awesome status powie
Ci, co dokładnie odpalić.
./awesome startProgram sprawdza, czy masz wszystko, potem:
| Krok | Co robi | Ile trwa |
|---|---|---|
| 1 | pobiera README awesome list z GitHuba (pomija to, co już masz) | 10–25 min |
| 2 | wyciąga z nich narzędzia do bazy | ~2 min |
| 3 | dociąga gwiazdki i języki list | ~1 min |
| 4 | włącza Web UI i czeka | — |
Jeśli baza już jest zbudowana, start nie pobiera nic od nowa. Wypisuje
liczbę narzędzi i od razu włącza interfejs. Przebudowa wymaga świadomej decyzji:
./awesome start --rebuild # kasuje bazę i buduje od nowa (~2 min)
./awesome refresh # dociąga brakujące dane i przebudowuje
Dzięki temu przypadkowe ./awesome start nie kasuje Ci 2 minuty pracy.
Uwaga, uczciwie: start nie odpytuje GitHuba o repozytoria samych
narzędzi. Ranking od razu działa (na zgodzie kuratorów), ale gwiazdka przy
narzędziu to na razie szacunek z listy, nie prawdziwa liczba. Jedna komenda
to naprawia:
./awesome enrich # 30–60 min, odpytuje ~35 tys. repozytoriów
./awesome build # ~2 min, żeby gwiazdki wsiąkły do rankingu
Albo jednym poleceniem od zera:
./awesome start --full # download → build → backfill → enrich → build
Robisz to raz. Przerwać można w każdej chwili (Ctrl+C) — postęp jest zapisywany
i odpalanie komendy drugi raz jedzie dalej. Bez zalogowania do GitHuba enrich
odmawia z wyjaśnieniem zamiast udawać, że zrobił swoją robotę.
Jeśli masz mało czasu, krok 1 możesz pominąć i nadrobić później:
./awesome start --skip-download # szybka ścieżka: buduje z tego, co już jest
./awesome search "port scanner" # szukaj po ludzku
./awesome search osint --lang Python # ...tylko Python
./awesome search "active directory" --os windows # ...tylko pod Windowsa
./awesome langs # co jest w bazie (języki)
./awesome platforms # systemy: Windows, Linux, Docker...
./awesome domains # tematy: osint, security, network...
./awesome why nmap # skąd ten wynik — punkt po punkcie
./awesome mentions nmap # w ilu listach jest to narzędzie
./awesome audit # czy katalog nie jest zatruty fałszywymi listami
./awesome audit sindresorhus/awesome # audyt jednego repozytorium
./awesome lists # najlepsze listy
./awesome info nmap # dane + komenda instalacji
./awesome install nmap # zainstaluj (git clone)
Jak coś znajdziesz i działa — włóż to od razu na swoją listę, a na końcu wklej gotowy Markdown:
./awesome shortlist add nmap --note "do skanowania sieci"
./awesome shortlist # co jest na liście
./awesome shortlist emit --title "Moja lista OSINT" --group domain
./awesome shortlist emit --out moja-lista.md # zapisz do pliku
W web UI jest to samo: przycisk ☆ Do mojej listy na stronie narzędzia,
lista i Markdown pod linkiem Moja lista w menu. W TUI klawisz k.
Osobno istnieje watch — lista repozytoriów list, które chcesz śledzić
(nowe narzędzia w ulubionej liście), a nie lista narzędzi:
./awesome watch add sindresorhus/awesome
./awesome watch check # co doszło od ostatniego sprawdzenia
Obie listy są lokalne i żadna nie odpytuje się sama w tle.
/ szukaj l następny język o następna platforma
d następna domena s zmień sortowanie a wyczyść filtry
g ukryte perełki u niedoceniane Enter szczegóły
k do mojej listy i instaluj ? pomoc
q wyjście
./awesome # terminal — najszybszy do szybkiego szukania
./awesome tui # terminal, ale interaktywnie (strzałki, filtry)
./awesome web # przeglądarka (port wypisuje na ekranie)
./awesome help # wszystkie komendy
./awesome status # co jest w bazie, kiedy ostatnio odświeżone, czego brakuje
./awesome refresh # pobierz nowe listy → metadane → przebuduj bazę
./awesome status po odświeżeniu podpowiada dokładną komendę, np.
./awesome enrich. To samo w przeglądarce: strona /refresh
z czterema przyciskami. Żadnych cronów, daemonów ani procesów w tle.
Ważne przy liczbach: status nie mówi „X narzędzi bez gwiazdek", tylko ile repozytoriów zostało do odpytania. Różnica jest ogromna, bo kilka narzędzi często wskazuje na to samo repo, a linki poza GitHubem (artykuły, filmy, dokumentacja) nie mają i nigdy nie będą miały gwiazdek — nie licz ich jako brakującej pracy.
| narzędzi w bazie | zależne od pobranych list |
| źródeł (repozytoriów) | zależne od pobranych list |
Aktualne liczby zawsze sprawdzisz: ./awesome status.
Uczciwa uwaga: nie ma tu żadnego AI. Żadne modele językowe nie wybierają,
nie oceniają ani nie rankują narzędzi. To zwykły Python, który parsuje README
z list GitHuba i liczy rzeczy na surowo. Jeśli liczby w README różnią się od
bazy — ktoś zapomniał odświeżyć blok STAN. Zrób ./awesome status i popraw.
Katalog można dać do dyspozycji lokalnemu agentowi (Claude, Cursor, cokolwiek mówi „Model Context Protocol”) jako źródło narzędzi. Agent dostaje ranking oparty o zgodę niezależnych kuratorów, a nie o to, co jest najczęściej wypisane w jednym README.
./awesome mcp --demo # podgląd: zobaczysz całą wymianę JSON-RPC bez agenta
./awesome mcp # serwer czeka na stdin (tak to działa w praktyce)
Serwer daje 5 narzędzi: search_tools (szukanie z filtrami),
find_undiscovered_tools (niedoceniane i ukryte perełki), explain_tool
(uzasadnienie rankingu: z jakich list, ile punktów, co ważyło),
lists_with_tool (wszystkie listy + oznaczone kopie) i catalog_facets
(co jest w bazie: języki, platformy, domeny).
Wpisz to do konfiguracji klienta, np. claude_desktop_config.json:
{
"mcpServers": {
"awesome-core": {
"command": "/pełna/ścieżka/do/awesome-core/awesome",
"args": ["mcp"]
}
}
}
Co warto wiedzieć:
Pytanie, które powinien zadać każdy: co jeśli ktoś wrzuci złośliwą listę?
Skąd listy: download.sh pyta publiczne API GitHuba o repozytoria
oznaczone topic:awesome-list (plus topic:awesome i topic:curated-list
w trybie --wide), posortowane po gwiazdkach. Nic więcej — żadnych
„polecanych" repozytoriów, żadnych losowych adresów.
Nic z obcego repozytorium nigdy nie jest wykonywane:
eval, exec,
shell=True czy któregokolwiek wywołania systemowego.awesome install robi dokładnie git clone --depth 1. Git nie uruchamia
kodu z zdalnego repozytorium (żadnych hooków).core/md.py też —
<script> w opisie wychodzi jako tekst, nie jako tag.Jedyny realny wektor: opisy trafiające do kontekstu modelu. Serwer MCP zamienia opisy narzędzi w tekst, który czyta agent. Opis napisał ktoś nieznany, w repozytorium niesprawdzonym. Dlatego:
core/untrusted.py, które wycina instrukcje
wyglądające na polecenia, znaczniki ról (system:, assistant:), tagi
HTML, curl … | sh i rm -rf — zostawiając przy tym znacznik
[odfiltrowano: …], żeby dało się zauważyć.initialize w MCP mówi agentowi wprost: to treść trzecia, nie rozkazy../awesome untrusted
Stan na dziś: 0 wykrytych ataków w 186 861 narzędziach (3 trafienia to
fałszywe alarmy — rimraf ma w opisie „like rm -rf", a safety-net to
narzędzie, które rm -rf blokuje). Ciekawa ironia: katalog zawiera trzy
narzędzia do obrony przed dokładnie tym problemem (nvidia/skillspector,
vaporif/parry-guard, safety-net).
Czego nie obiecuję: skaner łapie znane wzorce, nie jest dowodem niezawodności. Dlatego traktuj opisy jako dane, a nie polecenia.
Właściciel projektu dopuścił MCP, ale nie chce sztucznej inteligencji wszędzie — szczególnie nie w narzędziu, które miało być lokalne. Zapisuję to, bo obietnica bez pilnowania wyparuje się przy pierwszym refaktorze:
| Warstwa | AI? | Sieć? |
|---|---|---|
| parser, baza, ranking, kopie, shortlist, TUI, web | nie | nie — czyste odczyty z data/awesome.db |
core/mcp.py (adapter dla agentów) | tak, poza procesem | nie — JSON-RPC po stdio |
download, enrich, backfill, validate, install | nie | tak, tylko na wyraźne polecenie |
Z tego wynika reszta decyzji:
flask (web UI). Rdzeń to czysty stdlib.core/scoring.py), którą da się wypisać i podważyć.test_no_ai_in_core pilnuje tego mechanicznie: rdzeń nie zaimportuje
biblioteki AI ani sieciowej modułu bez zgody, a jedynym plikiem znającym
protokół MCP jest core/mcp.py.Katalog powstaje z cudzych repozytoriów. To znaczy, że ktoś może celowo wstawić fałszywą listę, która zbiera wejścia, a jej „narzędzia" prowadzą do podszywanych domen albo do szkodliwego kodu. Czy to się zdarzyło?
./awesome audit
Stan na dziś (6 października 2026, 1 032 listy, 186 861 narzędzi): 7 list warte obejrzenia, 1 podejrzany link. Zero potwierdzonych ataków.
Co sygnał ma złapać:
| Sygnał | Dlaczego podejrzane |
|---|---|
| dużo narzędzi przy 0 gwiazdek | twórca dopiero zaczął — nie ma reputacji do stracenia |
| jeden właściciel dla wielu linków | to nie katalog, tylko linki do jednego projektu |
| dużo martwych linków | farma linków, nie treść |
| niedawno utworzone repo + dużo narzędzi | kampania, nie dorobek |
| klon innej listy | kopiowanie zamiast budowania |
link typu github.com@evil.tld, githvb.com, adres IP, punycode | podszywanie domeny |
Przykładowe trafienie z naszej bazy: laoma2053/awesome-zhuiju-free — 25 narzędzi,
0 gwiazdek, brak opisu, żaden link nie potwierdzony przez inną listę.
Czego nie robimy i dlaczego warto to wiedzieć:
awesome install to tylko git clone. Nie uruchamia skryptów, nie pyta
o hasło do Twojego GitHuba, nie wykonuje kodu zdalnego repozytorium. Ale
potem to Ty decydujesz, co z tym kodem zrobisz — i tego program nie
kontroluje.core/untrusted.py (patrz sekcja o bezpieczeństwie).Najprostsza zasada: narzędzie z jednej nowej listy, o którym nigdy nie słyszałeś, to znak sprawdzenia — nie polecenia instalacji.
| Słowo | Co to znaczy |
|---|---|
| awesome list | lista linków do narzędzi prowadzona na GitHubie (np. sindresorhus/awesome) |
| baza (SQLite) | jeden plik data/awesome.db z całym katalogiem; zwykły plik, możesz go skasować i przebudować. Kasowanie i wstawianie idą w jednej transakcji, więc przerwany build zostawia poprzednią bazę, a nie pustą |
| FTS5 | wbudowany w SQLite szybki indeks tekstowy — dzięki niemu szukanie trwa milisekundy |
| metadane listy | gwiazdki, język, opis listy z GitHuba |
| metadane narzędzia | gwiazdki, język i czy żyje repozytorium samego narzędzia |
| consensus (zgoda) | narzędzie wskazane przez ilu różnych autorów list — nasz główny ranking |
| jakość listy | 0–1: czy lista ma opisy, czy duplikaty, czy jej linki żyją, czy jest aktualna |
| score | punkty narzędzia (0–100) z tych wszystkich sygnałów |
Program niczego nie rekomenduje. Nie ma w nim „polecam", „najlepszy wybór" ani LLM, który podpowiada narzędzia. Jest za to: policzone liczby (zgoda niezależnych kuratorów, gwiazdki, jakość listy, z jakich list narzędzie pochodzi) i filtry o jawnych kryteriach. Wybór zostaje po Twojej stronie — dlatego wszystko, co program mówi, da się sprawdzić liczbą. | backfill | dociąganie brakujących metadanych list | | enrich | sprawdzanie repozytoriów narzędzi (batch po 50 na zapytanie do API) | | build | przebudowa bazy z lokalnych plików README (~2 min) | | fasetka | klikalny filtr boczny, np. „język: Python” |
MIT — LICENSE w katalogu. Kod jest mój, ale nazwy, linki i krótkie opisy
narzędzi pochodzą z cudzych awesome list i należą do ich autorów. W bazie
są tylko adresy i nazwy repozytoriów (fakty, nie czyjeś treści), a same
README nie są dołączane do repo — pobierasz je na swój dysk przez
./download.sh.
Ranking czyta to, co napisał autor — nie kod. Nazwa, opis, gwiazdki, tematy, README: wszystko to można napisać dowolnie i wszystko wchodzi do score. Program nigdy nie zagląda do kodu repozytorium, więc nie odróżnia narzędzia od kolekcji skryptów o tej samej nazwie ani oryginału od kopii.
Mierzalny skutek: awesome selfcheck sprawdza 15 znanych narzędzi
(nazwa → właściwe repozytorium) i zwykle trafia 13/15 na pozycji #1.
Dwie porażki to zawsze ten sam mechanizm — repozytorium fanowskie, które
powtarza nazwę narzędzia w opisie, wyprzedza oryginał.
./awesome selfcheck
To jest granica tego podejścia, nie do poprawienia strojeniem wag: do jej przekroczenia trzeba by patrzeć na zawartość repozytorium (importy, pliki wejściowe, tagi wydań), a to osobny projekt. Świadomie tego nie udaję.
Mniej poważne, ale też powiedziane:
--wide) i skaluje wyniki../awesome enrich. Reszta zgadywana jest z adresu i opisu — stąd ? tam,
gdzie nie wiadomo. Ranking celowo nie ufa temu zgadywaniu../awesome validate --non-github --limit 500.awesome # wygodny wrapper: ./awesome <komenda>
download.sh # pobieranie README list z GitHuba (bash + gh + jq)
extract_tools.py # budowa bazy z lokalnych README
data/awesome.db # baza SQLite (generowana, w .gitignore)
offline-db/ # pobrane README list (generowane, w .gitignore)
core/store.py # schemat bazy, migracje, zapis metadanych
core/parser.py # wyciąganie narzędzi z markdown (listy i tabele)
core/langmap.py # język / platforma / domena / czyszczenie URL-i
core/scoring.py # consensus, jakość listy, ranking
core/aliases.py # synonimy („port scanner” → nmap, masscan…)
core/md.py # własny renderer Markdown → HTML (bez CDN)
core/builder.py # orkiestracja builda
core/backfill.py # metadane list
core/enrich.py # metadane repozytoriów narzędzi
core/status.py # stan danych i plan odświeżenia
core/tools_db.py # zapytania (search, fasetki, ranking)
core/database.py # zapytania po listach/repozytoriach
core/curator.py # kolekcje + instalacja
core/validator.py # weryfikacja linków
core/trust.py # sygnały ryzyka przy repozytoriach
cli/awesome_cli.py # CLI
cli/tui.py # TUI (curses)
web/app.py # Flask UI
web/templates/ # szablony Jinja2
tests/smoke_test.py # 106 testy (CI)
score (0–100) to świadoma korekta nad „sortuj po gwiazdkach listy”:
| Składowa | Waga | Znaczenie |
|---|---|---|
consensus | 0.28 | w ilu niezależnych listach jest narzędzie × jakość tych list |
own_stars | 0.22 | gwiazdki samego narzędzia (z API), nie listy |
quality | 0.14 | jakość listy: opisy, unikalność, żywe linki, świeżość, rozmiar |
alive | 0.14 | link sprawdzony i żywy |
desc | 0.10 | ma sensowny opis |
list_stars | 0.06 | gwiazdki listy (słaby sygnał) |
known | 0.06 | mamy metadane narzędzia z API |
Dodatkowo underrated (dobra jakość, mało gwiazdek) i hidden_gem (mało list,
wysoki score). ./awesome why <nazwa> pokazuje rozkład punktów.
gh, jq, curl — tylko do pobierania i enrichmentucurses z biblioteki standardowej — tylko dla TUIMIT — używaj, zmieniaj, dziel się. Autor: Arkadiusz Słowik — @twojlogin
mcp-name: io.github.twojlogin/awesome-core
FAQs
Offline-first catalog of tools from GitHub awesome lists, exposed as a read-only MCP server (stdio). Pure stdlib core, no network, no API keys.
We found that awesome-core demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Threat Research
/Security News
Socket uncovered secret-stealing workflows that ran in LiteLLM’s GitHub repository 11 days before the supply chain attack on PyPI and Docker.
Security News
Cloudflare introduces tsrs, a Rust port of TypeScript’s compiler promising faster checks and lower memory use, with the TypeScript team’s help.
Security News
The PHP Foundation says Chainguard broke a security embargo ahead of critical RCE patches, as leaks disrupted the coordinated release.