inshellisense — podpowiedzi w terminalu dla 600+ narzędzi CLI

Terminal jest chyba ostatnim miejscem w pracy programisty, w którym uzupełnianie nadal działa jak w latach dziewięćdziesiątych. W edytorze dostajesz listę metod z opisami, typami i dokumentacją po dwóch znakach. W powłoce naciskasz tabulator i dostajesz nazwy plików — a jeśli ktoś napisał dla danego narzędzia skrypt uzupełniania, to może i nazwy podkomend, bez opisu, bez wyjaśnienia, co która robi.

inshellisense zamyka tę lukę: dokłada do powłoki listę podpowiedzi z opisami, pojawiającą się w trakcie pisania, dla ponad sześciuset narzędzi wiersza poleceń. Działa na Windowsie, Linuksie i macOS, w ośmiu powłokach. Zanim jednak zaczniesz, warto poznać dwie rzeczy: jak to jest zrobione pod spodem i skąd biorą się te podpowiedzi — bo druga z nich ma haczyk.

Stan projektu

Repozytorium: microsoft/inshellisense. 10 690 gwiazdek, licencja MIT, prawa po stronie Microsoft Corporation. Ostatni commit pochodzi z 7 września 2026 — trzy dni przed powstaniem tego wpisu, więc projekt jest w pełni czynny.

Numer wersji jest przy tym zaskakujący: paczka @microsoft/inshellisense na npm ma 0.0.3, opublikowaną 11 sierpnia 2026. Historia wersji przeszła przez trzydzieści kilka wydań kandydackich w linii 0.0.1-rc.*, a potem ustabilizowała się na 0.0.1, 0.0.2 i 0.0.3. To narzędzie interaktywne, nie biblioteka, więc numer nie determinuje kompatybilności API — ale jeśli u was obowiązuje reguła „tylko wydania stabilne", to jest pozycja, przy której trzeba tę regułę skonfrontować z faktem, że narzędzie stoi na dziesięciu tysiącach gwiazdek i commitach z tego tygodnia.

Instalacja i pierwsze uruchomienie

Najkrótsza droga to npm, którą autorzy rekomendują:

npm install -g @microsoft/inshellisense
is init

Na macOS i Linuksie jest też droga przez Homebrew, z własnym tapem. Po instalacji warto uruchomić is doctor — jest to osobne polecenie, którego jedynym zadaniem jest sprawdzenie kondycji instalacji. Potem is startuje sesję uzupełniania w bieżącej powłoce, a exit ją kończy. Przydatne jest jeszcze is -c: sprawdza, czy powłoka już działa wewnątrz sesji inshellisense, co za chwilę okaże się istotne.

Żeby narzędzie startowało samo przy każdym otwarciu powłoki, dopisuje się wtyczkę do pliku konfiguracyjnego. Polecenie jest inne dla każdej powłoki:

is init bash >> ~/.bashrc
is init zsh >> ~/.zshrc
is init fish >> ~/.config/fish/config.fish
is init pwsh | Add-Content $profile
is init xonsh >> ~/.xonshrc
is init nu | save $nu.env-path --append

I tu pierwsze ostrzeżenie, które dokumentacja wyróżnia osobną notatką, bo łamie się o nie wiele osób: wtyczka inshellisense musi być ostatnim poleceniem w pliku konfiguracyjnym powłoki. Cokolwiek dopisanego po niej — na przykład inicjalizacja menedżera wtyczek — może zepsuć konfigurację. Jeśli więc później dodasz do .zshrc kolejne narzędzie, dopisz je przed linią inshellisense, nie po.

Aktualizacja to nie tylko podbicie paczki. Po npm install -g albo brew upgrade trzeba jeszcze wykonać is reinit, które odświeża wygenerowane zasoby.

Jak to jest zrobione

To najciekawsza część i wyjaśnia większość zachowań narzędzia. inshellisense nie jest skryptem uzupełniania dla twojej powłoki. Zależności mówią wprost, co się dzieje: w package.json siedzą node-pty i @xterm/headless, a w katalogu źródeł jest moduł src/isterm/pty.ts o wielkości 18 kB.

Innymi słowy: inshellisense uruchamia twoją powłokę wewnątrz pseudoterminala i staje pomiędzy tobą a nią. Czyta wpisywane znaki, przekazuje je dalej przez warstwę stdioProxy, jednocześnie utrzymuje własny model tego, co jest w linii poleceń (commandManager), i dorysowuje listę podpowiedzi nad zawartością ekranu (suggestionRenderer). Do tego dochodzą skrypty integracji dla każdej powłoki osobno w katalogu shell/, wraz z dostarczonym w projekcie bash-preexec.sh.

Z tej architektury wynikają wszystkie konsekwencje praktyczne. Po pierwsze, w drzewie procesów masz dodatkową warstwę — dlatego istnieje is -c, żeby nie zagnieździć sesji w sesji. Po drugie, narzędzie musi rozumieć, kiedy nie rysować podpowiedzi: gdy program przełącza terminal w alternatywny bufor ekranu, tak jak robi to vim czy less. W repozytorium jest osobny plik testowy poświęcony właśnie temu przypadkowi. Po trzecie, obsługa znaków szerokich i emoji to nie drobiazg, a moduł src/utils/unicode.ts na blisko 12 kB.

Widać przy tym, że autorzy traktują wydajność jako cechę produktu, nie dodatek. W katalogu scripts/perf są osobne skrypty pomiarowe, a jedno z zadań npm uruchamia je z profilowaniem procesora i pamięci. Ma to sens: narzędzie, które siedzi pomiędzy klawiaturą a powłoką, nie ma prawa dokładać opóźnienia do pisania.

Podoba mi się jeszcze jeden szczegół z testów. Wśród danych testowych leży komplet konfiguracji oh-my-zsh razem z plikiem .p10k.zsh — czyli narzędzie jest sprawdzane przeciwko Powerlevel10k, jednemu z najbardziej wymagających znaków zachęty, jakie da się spotkać. To dokładnie ten przypadek, na którym takie narzędzia zwykle się wykrzaczają.

Skąd biorą się podpowiedzi — i tu jest haczyk

inshellisense nie definiuje własnych opisów poleceń. Jest, jak sam się określa, natywnym dla terminala środowiskiem uruchomieniowym dla specyfikacji z projektu withfig/autocomplete — otwartego zbioru opisów dla ponad sześciuset narzędzi wiersza poleceń, powstałego wokół narzędzia Fig.

I tu trzeba postawić sprawę wprost, bo to najważniejsza informacja w całym wpisie. Repozytorium ze specyfikacjami stoi: ostatni push pochodzi z 5 maja 2025, a ostatnie wydanie paczki @withfig/autocomplete na npm — 2.692.3 — jest z tego samego dnia. To szesnaście miesięcy bez zmian. Na dodatek inshellisense przypina wersję 2.675.0, czyli niższą nawet od tej ostatniej wydanej.

Co to znaczy w praktyce? Sam inshellisense jest utrzymywany — silnik, renderowanie, obsługa powłok i wydajność dostają poprawki co tydzień. Zamarzły natomiast dane. Narzędzia wiersza poleceń, które powstały po maju 2025, nie mają tu opisów. Nowe flagi i nowe podkomendy narzędzi, które już są w zbiorze, też się nie pojawią. Dla stabilnych, dojrzałych programów — git, docker, ssh, tar, systemctl — nie ma to większego znaczenia, bo ich interfejsy zmieniają się rzadko. Dla wszystkiego, co żyje szybko, ma znaczenie zasadnicze.

Na szczęście z kodu wynika, że nie jesteś na to skazany. Konfiguracja przyjmuje własne katalogi ze specyfikacjami:

[specs]
path = ["/sciezka/do/wlasnych/specyfikacji"]

Do listy zawsze doklejana jest na początek ścieżka ~/.fig/autocomplete/build, więc jeśli masz gdzieś zbudowane specyfikacje w formacie Fig, zostaną podchwycone automatycznie. Jest też polecenie is specs list, które pokazuje, co narzędzie faktycznie widzi. Dla zespołu z własnym narzędziem wiersza poleceń to realna droga: napisać specyfikację raz i mieć podpowiedzi dla firmowego CLI u wszystkich.

Podpowiedzi, które uruchamiają polecenia

Statyczna lista podkomend to dopiero połowa problemu. Prawdziwie użyteczna podpowiedź przy git checkout to nazwy twoich gałęzi, a przy docker exec — nazwy twoich działających kontenerów. Tego nie da się zapisać w pliku ze specyfikacją, więc format Fig przewiduje generatory: fragmenty, które produkują podpowiedzi na żądanie. I tu dochodzimy do rzeczy, którą warto rozumieć przed instalacją.

Plik src/runtime/generator.ts pokazuje to bez ogródek. Generator może mieć pole script — łańcuch znaków, tablicę albo funkcję przyjmującą aktualnie wpisane tokeny — i wynik tego pola jest uruchamiany jako polecenie powłoki w bieżącym katalogu roboczym. Domyślny limit czasu to scriptTimeout ?? 5000, czyli pięć sekund. Może też mieć pole custom: dowolną funkcję JavaScriptu, której przekazywane są funkcja wykonująca polecenia oraz kontekst zawierający wszystkie twoje zmienne środowiskowe.

Innymi słowy: żeby dać ci podpowiedzi świadome kontekstu, środowisko uruchomieniowe wykonuje w twoim imieniu polecenia w trakcie pisania. To nie jest wada — bez tego narzędzie byłoby o połowę mniej użyteczne — ale ma dwie konsekwencje, o których trzeba wiedzieć.

Pierwsza: specyfikacja nie jest danymi, jest kodem. Oficjalny zbiór z projektu Fig jest otwarty, przejrzany przez wiele osób i wydany na MIT, więc traktowanie go jako zaufanego jest uzasadnione. Ale skoro konfiguracja pozwala dorzucić własne katalogi ze specyfikacjami przez specs.path, to dorzucenie tam pliku znalezionego w losowym repozytorium jest uruchomieniem cudzego kodu z dostępem do twoich zmiennych środowiskowych. Przy firmowych specyfikacjach warto trzymać je w repozytorium przechodzącym normalny przegląd kodu, a nie kopiować z internetu.

Druga: gdyby generatory uruchamiały się przy każdym naciśnięciu klawisza, narzędzie byłoby nieużywalne. Dlatego jest osobna warstwa buforowania w src/runtime/generatorCache.ts i jest zrobiona porządnie. Klucz bufora składa się z identyfikatora generatora, tokenów kontekstu i katalogu roboczego, przy czym specyfikacja może wymusić własny klucz albo poprosić o buforowanie per katalog. Wpisów trzymanych jest maksymalnie 256, a najdawniej używane wypadają. Do tego trwające wywołania są rozpoznawane i nie dublują się, a przerwane — anulowane sygnałem AbortSignal, więc porzucone zapytanie nie kończy pracy w tle.

Na koniec drobiazg wart odnotowania, bo tłumaczy ewentualne dziwne zachowania: kontekst przekazywany generatorom ma dwa pola oznaczone w kodzie komentarzem TODO — nazwa bieżącego procesu i szukana fraza są puste. Specyfikacja, która na nich polega, nie zadziała tu tak jak w oryginalnym narzędziu Fig. Pole isDangerous jest z kolei ustawione na stałe na false.

Czego nie obsłuży

Dokumentacja wymienia to krótko i szczerze, ale skutek jest bolesny: specyfikacje dla az, gcloud i aws nie są obsługiwane z powodu swojego rozmiaru. To dokładnie te trzy narzędzia, przy których podpowiedzi w stylu IDE dawałyby najwięcej — bo nikt nie pamięta układu podkomend interfejsu chmurowego. Jeśli twój dzień to głównie aws albo az, to narzędzie nie rozwiąże twojego głównego problemu.

Konfiguracja

Konfiguracja jest w formacie TOML i szuka się jej w dwóch miejscach: ~/.inshellisenserc oraz $XDG_CONFIG_HOME/inshellisense/rc.toml (przy nieustawionej albo nieabsolutnej zmiennej — ~/.config/inshellisense/rc.toml).

Domyślne wartości, wyczytane wprost ze schematu w src/utils/config.ts: maxSuggestions to 5, kolor tła aktywnej podpowiedzi to #7D56F4, styl ramki to square, a useAliases i useNerdFont są wyłączone. Klawisze to tabulator (przyjmij), strzałki (nawiguj) i escape (odrzuć), a nazwy klawiszy dopasowywane są do zdarzeń klawiatury Node.js.

useAliases = true
useNerdFont = true
maxSuggestions = 10
activeSuggestionBackgroundColor = "#2E7D32"
boxBorderStyle = "rounded"

[bindings.acceptSuggestion]
key = "tab"
control = false

Dwie rzeczy w obsłudze konfiguracji zasługują na uznanie. Schemat jest walidowany biblioteką Ajv z ustawieniem additionalProperties: false, więc literówka w nazwie opcji jest błędem, a nie cichym pominięciem — narzędzie powie ci, co jest nie tak. A błąd składni w pliku TOML zwraca komunikat z numerem linii i kolumny, nie samym „nie udało się sparsować".

Jedna rzecz natomiast zaskakuje i znalazłem ją tylko przez przeczytanie kodu. Funkcja ładująca przechodzi po obu ścieżkach po kolei i dla każdego istniejącego pliku zastępuje całą konfigurację, a nie scala ją z poprzednią. Jeśli masz jednocześnie ~/.inshellisenserc i plik w katalogu XDG, wygra ten drugi, a ustawienia z pierwszego przepadną w całości — bez ostrzeżenia. Trzymaj konfigurację w jednym pliku.

Warto też wiedzieć, gdzie ląduje stan. Na nowych instalacjach uniksowych generowane zasoby idą do $XDG_DATA_HOME/inshellisense (domyślnie ~/.local/share). Istniejące instalacje dalej używają ~/.inshellisense, jeśli ten katalog istnieje, żeby nie psuć działających wtyczek — i tak samo działa Windows. Migrację na katalog XDG wykonuje wspomniane is reinit. To ładny przykład zmiany wprowadzonej bez łamania istniejących instalacji.

Powłoki i wymagania

Obsługiwane są: bash, zsh, fish, pwsh, Windows PowerShell, cmd (oznaczone jako eksperymentalne), xonsh i nushell. To nietypowo szeroka lista — obecność nushella i xonsha, powłok z własnym, nietradycyjnym modelem, mówi coś o tym, jak solidnie zrobiona jest warstwa integracji.

Jest natomiast wymaganie, o które łatwo się potknąć: pole engines deklaruje Node.js w wersji >=18.0 <23.0.0. To górna granica, nie tylko dolna. Jeśli masz zainstalowanego Node.js 23 albo nowszego jako wersję domyślną, instalacja globalna nie przejdzie albo narzędzie odmówi startu. To jeden z tych przypadków, w których przydaje się narzędzie do przełączania wersji Node.js osobno dla każdego projektu — instalacja globalna narzędzia z górną granicą wersji nie powinna wymuszać downgrade'u całego środowiska.

Pułapki w jednym miejscu

Wtyczka musi być ostatnią linią w pliku konfiguracyjnym powłoki. Cokolwiek po niej może zepsuć konfigurację.
Specyfikacje podpowiedzi zamarły w maju 2025. Silnik jest utrzymywany, dane nie — nowe narzędzia i nowe flagi się nie pojawią.
Przypięta wersja specyfikacji 2.675.0 jest niższa niż ostatnia wydana 2.692.3.
az, gcloud i aws nie są obsługiwane z powodu rozmiaru specyfikacji.
Node.js ma górną granicę <23.0.0 — na nowszym Node instalacja nie przejdzie.
Dwa pliki konfiguracyjne nie scalają się. Plik XDG nadpisuje cały ~/.inshellisenserc, bez ostrzeżenia.
Specyfikacje uruchamiają polecenia powłoki w trakcie pisania, z limitem 5 sekund. Własne specyfikacje traktuj jak kod przechodzący przegląd, nie jak dane.
Generatory custom dostają wszystkie zmienne środowiskowe. To kolejny powód, by nie dodawać specyfikacji z nieznanego źródła.
Dwa pola kontekstu generatora są niezaimplementowane (TODO w kodzie) — specyfikacje polegające na nazwie procesu lub szukanej frazie zachowają się inaczej niż w Fig.
Aktualizacja wymaga is reinit, nie tylko podbicia paczki.
Obsługa cmd jest eksperymentalna.
Twoja powłoka działa wewnątrz pseudoterminala. To dodatkowa warstwa w drzewie procesów — przy diagnozowaniu dziwnych zachowań terminala sprawdź is -c.
Wkład wymaga podpisania CLA Microsoftu, a znaki towarowe mają osobne zasady użycia.

Podsumowanie

inshellisense robi rzecz, która przy pierwszym uruchomieniu wydaje się drobna, a po tygodniu trudno się bez niej obejść: pokazuje, co można wpisać dalej, razem z opisem. Jest przy tym zrobiony solidnie — z pomiarami wydajności, testami przeciwko trudnym znakom zachęty i obsługą ośmiu powłok na trzech systemach.

Podpowiedzi z opisami dla ponad 600 narzędzi, pojawiające się w trakcie pisania, a nie po tabulatorze.
Osiem powłok na Windowsie, Linuksie i macOS — wraz z nushellem i xonshem, nie tylko z klasyczną trójką.
Konfiguracja w TOML z twardą walidacją — literówka w nazwie opcji jest błędem z komunikatem, nie cichym pominięciem.
Możliwość dodania własnych specyfikacji przez specs.path, czyli droga do podpowiedzi dla firmowego narzędzia.
Wydajność traktowana jako cecha — osobne skrypty pomiarowe z profilowaniem procesora i pamięci.
Migracja katalogów zrobiona bez psucia istniejących instalacji, z jawnym poleceniem is reinit.

Projekt jest wydany na licencji MIT z prawami Microsoft Corporation — permisywnie, bez obowiązku otwierania własnych zmian. Dwie uwagi formalne, jeśli myślisz o czymś więcej niż używanie: wkład do projektu wymaga podpisania umowy licencyjnej kontrybutora Microsoftu, a użycie znaków towarowych i logotypów w zmodyfikowanych wersjach podlega osobnym wytycznym i nie może sugerować sponsoringu Microsoftu. Przy zwykłej instalacji u siebie żadna z tych rzeczy cię nie dotyczy — a przy forku, który chciałbyś rozdawać pod własną nazwą, obie mają znaczenie.