Wyszukiwanie kodu dla agentów ma budżet tokenów

17 maja 2026 roku Semble przekroczył 900 gwiazdek na GitHubie, stawiając prostą tezę: agenci programistyczni marnują większość budżetu kontekstu, gdy używają grep, otwierają całe pliki i czytają znacznie więcej kodu, niż wymaga zadanie.¹

Ta teza trafia w sedno, bo pokazuje wyszukiwanie kodu jako problem budżetu. Człowiek potrafi szybko przejrzeć zaszumiony wynik rg i pominąć śmieci. Agent płaci za każdą nieistotną linię kontekstem, uwagą i czasem pętli narzędziowej.

TL;DR

Semble to biblioteka do wyszukiwania kodu dla agentów. Udostępnia serwer MCP, integrację z powłoką przez AGENTS.md albo CLAUDE.md, CLI oraz Python API.¹ Pod spodem Semble dzieli kod na fragmenty, wyszukuje za pomocą BM25 oraz statycznych embeddingów kodu Model2Vec, scala listy rankingowe metodą Reciprocal Rank Fusion, a następnie ponownie szereguje wyniki przy użyciu sygnałów świadomych kodu, takich jak ważenie symboli, wzmacnianie definicji, rdzenie identyfikatorów, spójność pliku i kary za szum.¹ Benchmark raportuje NDCG@10 na poziomie 0,854 dla około 1 250 zapytań w 63 repozytoriach i 19 językach, blisko hybrydowego wyniku CodeRankEmbed równego 0,862, przy znacznie szybszym indeksowaniu w tabeli benchmarkowej.² Najważniejsza lekcja produktowa nie brzmi „zastąpić grep”. Jest ostrzejsza: narzędzie wyszukiwania dla agenta powinno zwracać najmniejszy pakiet dowodów, który pozwala modelowi działać poprawnie.

Najważniejsze wnioski

• Dla użytkowników agentów programistycznych: warto zachować rg do dokładnych ciągów znaków, ale używać wyszukiwania z rankingiem fragmentów, gdy zadanie dotyczy zachowania, a nie dosłownego tokenu.
• Dla twórców narzędzi: należy optymalizować pobierany kontekst, a nie tylko trafność wyszukiwania. Użyteczną jednostką jest dowód na token.
• Dla użytkowników Codex i Claude Code: lepsza jest ścieżka dostępna z powłoki dla subagentów, ponieważ narzędzia MCP najwyższego poziomu mogą nie docierać do agentów delegowanych w taki sam sposób.¹
• Dla czytelników benchmarków: trzeba oddzielać deklaracje benchmarkowe dostawcy od lokalnego zachowania w środowisku wykonawczym. Mój zimny przebieg uvx trwał znacznie dłużej niż tabela benchmarkowa Semble, bo dominowały uruchomienie pakietu, modelu i indeksu.
• Dla tekstów publicznych: narzędzia wyszukiwania nie zdejmują obowiązku pracy z cytowaniami. Sprawiają tylko, że ścieżkę dowodową taniej się sprawdza.

Dlaczego grep nadal jest dobry, ale już nie wystarcza

rg pozostaje właściwym pierwszym narzędziem do dokładnych ciągów znaków. Jeśli potrzebne jest visible_label_residue, nazwa zmiennej z poświadczeniem albo nazwa funkcji, wyszukiwanie leksykalne powinno wygrywać szybkością i pewnością. W moim lokalnym teście dosłowne zapytanie rg dla terminów pozostałości tłumaczeniowych zwróciło wynik w około jedną dziesiątą sekundy.⁵

Problem zaczyna się wtedy, gdy agent nie zna dokładnego ciągu znaków.

Agenci często wyszukują według intencji: „gdzie bramka blog i18n sprawdza pozostałości w widocznych etykietach” albo „jak działa weryfikacja wydania tłumaczenia?”. Wyszukiwanie dosłowne nadal może znaleźć użyteczne linie, ale agent musi dobrać słowa, sprawdzić dziesiątki trafień, przeczytać pliki, przeformułować zapytanie i zdecydować, która linia niesie odpowiedź. Każdy krok zużywa kontekst i stwarza ryzyko zbyt wczesnego zatrzymania.

Semble atakuje właśnie ten tryb awarii. Pozwala agentowi zadawać pytania językiem naturalnym, a potem zwraca uporządkowane fragmenty kodu zamiast całych plików.¹ To nie czyni rg przestarzałym. Zmienia domyślną interakcję z „pokaż każdą linię pasującą do tego terminu” na „daj najmniejszy użyteczny wycinek kodu”.

Ta różnica ma znaczenie, bo agenci nie czytają jak ludzie. Człowiek może rzucić okiem na 80 linii wyników wyszukiwania i zatrzymać w głowie tylko trzy interesujące. Modele otrzymują cały wynik jako tokeny. Zaszumiony wynik wyszukiwania staje się częścią środowiska zadania.

Co Semble faktycznie robi

Publiczny README Semble opisuje cztery ścieżki integracji: serwer MCP, Bash / AGENTS.md, CLI oraz Python API.¹ Konfiguracja dla Codex to lokalny wpis serwera MCP w ~/.codex/config.toml, a ścieżka powłoki dodaje sekcję wyszukiwania kodu do AGENTS.md albo CLAUDE.md.¹

Ścieżka powłoki jest ważniejsza, niż na pierwszy rzut oka się wydaje. README wskazuje, że subagenci Claude Code i Codex CLI powinni używać integracji Bash zamiast MCP albo obok niego, ponieważ w tej konfiguracji subagenci nie mogą bezpośrednio wywoływać narzędzi MCP.¹ To praktyczny punkt dotyczący interfejsu agenta: narzędzie wyszukiwania musi istnieć tam, gdzie wykonywana jest praca, a nie tylko tam, gdzie zaczyna się sesja najwyższego poziomu.

Stos wyszukiwania wygląda też jak kierunek, w którym zmierza wyszukiwanie dla agentów:

Ten projekt odpowiada temu, co widziałem w lokalnych systemach wyszukiwania: czyste wyszukiwanie wektorowe gubi identyfikatory, czyste wyszukiwanie słów kluczowych gubi intencję, a ranking hybrydowy daje agentowi lepszą pierwszą lekturę.⁴

Teza benchmarku dotyczy kontekstu, nie magii

README benchmarków Semble raportuje dwie klasy wyników.

Pierwsza mierzy jakość i szybkość wyszukiwania. Tabela podaje Semble z wynikiem 0,854 NDCG@10, CodeRankEmbed Hybrid z 0,862, BM25 z 0,673 oraz ripgrep z 0,126. Benchmark obejmuje około 1 250 zapytań w 63 repozytoriach i 19 językach, w przebiegach tylko na CPU.²

Druga klasa mierzy efektywność tokenów. Benchmark modeluje typowy przepływ pracy agenta programistycznego: podzielić zapytanie na słowa kluczowe, uruchomić rg --fixed-strings --ignore-case, uszeregować pliki według liczby różnych dopasowanych słów kluczowych, a potem przeczytać dopasowane pliki w całości. Wobec tej bazy benchmark raportuje średnio 45 692 tokeny dla ripgrep plus odczyty całych plików, wobec 566 tokenów dla Semble, czyli redukcję o 98%.²

To właśnie jest interesująca teza. Nie „wyszukiwanie semantyczne zawsze bije grep”. Nie „agenci powinni przestać używać dokładnego wyszukiwania”. Teza brzmi: grep plus odczyt wysyła do modelu za dużo nieistotnego kodu, gdy zadanie wymaga tylko kilku fragmentów.

Metodologia benchmarku wyjaśnia też, gdzie ta teza powinna i nie powinna mieć zastosowania. Semble porównuje się z czytaniem dopasowanych plików w całości.² Jeśli dany przepływ pracy już używa rg -n, sed i chirurgicznie dobranych zakresów linii, punkt odniesienia może być ciaśniejszy niż model grep plus odczyt z benchmarku. Jeśli agent rutynowo otwiera całe pliki po szerokim wyszukiwaniu, benchmark jest bliższy realnemu trybowi awarii.

Mój lokalny test

Uruchomiłem Semble w repozytorium strony przez uvx --from semble semble, a potem porównałem go z dosłownymi wyszukiwaniami rg.

Zacząłem od zapytania o proces wydania:

semble search "blog translation quality gate release verifier D1" . --top-k 5 --include-text-files

Semble zwrócił pięć fragmentów. Najwyższy wynik streszczał pętlę wydawania tłumaczeń bloga w tabeli artykułu migracyjnego. Inny wynik wskazał bezpośrednio scripts/i18n-automation/README.md, gdzie znajdowały się kroki bramki jakości, release-verifier, native-review, commit, push, Railway, Cloudflare i live-smoke.⁵

Porównywalne polecenie rg wróciło szybko, ale zwróciło duży strumień dosłownych dopasowań dla zmiennych poświadczeń, blog_release_verify i powiązanych nazw w skryptach, testach i dokumentacji.⁵ Człowiek potrafi to odfiltrować. Agent musi wydać kontekst, żeby zrobić to samo.

Potem zapytałem o implementację bramki:

semble search "where does the blog i18n gate check visible label residue" . --top-k 5 --include-text-files

Najwyższy wynik Semble wskazał dokładny lokalny blok bramki, w którym visible_label_residue zostaje przypisane, zamienione na błąd i wpływa na status znaleziska. Wynik zawierał odpowiednie linie ciała funkcji zamiast całego pliku.⁵

Porównywalne zapytanie rg znów zakończyło się szybciej, ale zwróciło wiele trafień w testach, promptach tłumaczeniowych, skryptach naprawczych, README i implementacji bramki.⁵

Ten test nie dowodzi benchmarku Semble. Moje wywołanie używało uvx, pobrało pakiety i zasoby modelu, zindeksowało duże mieszane repozytorium, uwzględniło pliki Markdown i JSON, a także startowało z zimnej ścieżki. Pierwsze zapytanie Semble zajęło około 54 sekund, drugie około 31 sekund.⁵ Te liczby nie odpowiadają tabeli benchmarkowej projektu i nie cytowałbym ich jako danych o wydajności Semble.

Test potwierdza natomiast kształt produktu. Semble zwrócił mniejsze pakiety dowodów, bardziej przypominające odpowiedź. Po dwóch wyszukiwaniach semble savings --verbose zaraportował około 38 100 szacunkowo zaoszczędzonych tokenów, czyli 94%, według własnej metody liczenia oszczędności plik-kontra-fragment.⁵ Należy traktować to jako estymację narzędzia, nie niezależny pomiar, ale kierunek zgadzał się z widocznym wynikiem.

Właściwy model myślowy: pakiety dowodów

Wyszukiwanie dla agentów powinno produkować pakiety dowodów.

Pakiet dowodów ma cztery właściwości:

Surowe rg daje lokalizację i szybkość. Odczyty całych plików dają kontekst, ale w nadmiarze. Wyszukiwanie wektorowe daje intencję, lecz może pominąć dokładne nazwy. Dobry przepływ wyszukiwania dla agenta łączy te elementy:

1. Używać dokładnego wyszukiwania, gdy zadanie podaje symbol, błąd, klucz konfiguracji, plik albo dosłowny ciąg znaków.
2. Używać semantycznego lub hybrydowego wyszukiwania z rankingiem fragmentów, gdy zadanie opisuje zachowanie.
3. Otwierać cały plik dopiero wtedy, gdy fragment potwierdzi jego istotność.
4. W końcowej odpowiedzi cytować plik i zakres linii.
5. Ponowić dokładne wyszukiwanie, gdy fragment podsuwa konkretny identyfikator.

Semble koduje znaczną część tego przepływu jako narzędzie. Agent nadal potrzebuje osądu, a bramka dowodowa nadal potrzebuje śladu, który da się sprawdzić.

Jak Semble zmienia przepływy pracy Codex i Claude Code

Praktyczne pytanie nie brzmi, czy instalować każde nowe narzędzie wyszukiwania. Brzmi: gdzie wyszukiwanie kodu należy umieścić w kontrakcie operacyjnym agenta.

Dla sesji najwyższego poziomu MCP może działać dobrze, bo agent widzi schemat narzędzia i bezpośrednio wywołuje serwer. README Semble zawiera przykłady konfiguracji MCP dla Claude Code, Codex, OpenCode, Cursor i innych klientów zgodnych z MCP.¹

Przy pracy delegowanej ważniejszy może być dostęp z powłoki. README Semble wprost wskazuje integrację Bash dla subagentów Claude Code i Codex CLI.¹ Subagent, który nie ma dostępu do narzędzia MCP najwyższego poziomu, nadal może uruchomić polecenie powłoki, jeśli przepływ pracy uczy go, kiedy i jak to robić.

Najlepsza integracja może więc wyglądać niepozornie:

## Code Search

Use `semble search` when looking for behavior or related implementation.
Use `rg` when looking for an exact string, symbol, file name, or config key.
Open full files only after the search result proves relevance.
Report file path and line range when citing evidence.

Taka instrukcja jest lepsza niż niejasna reguła „używaj wyszukiwania semantycznego”, bo nazywa decyzję o wyborze ścieżki. Agent uczy się, które narzędzie pasuje do którego pytania.

Czego bym nie robił

Nie zastępowałbym rg.

Lokalny test pokazał to jasno. rg odpowiadał na dosłowne zapytania w około jedną dziesiątą sekundy. Semble zwracał lepsze pakiety dla zapytań o zachowanie, ale moje zimne wywołanie z powłoki miało realny koszt uruchomienia i indeksowania.⁵

Nie traktowałbym tezy Semble o 98% oszczędności tokenów jako uniwersalnej. Benchmark porównuje z grep plus odczytem całych plików. Teza jest uczciwa, gdy taki punkt odniesienia przypomina zachowanie agenta. Przesadza z zyskiem, gdy zdyscyplinowany przepływ już czyta wąskie zakresy linii.

Nie ukrywałbym decyzji o wyborze ścieżki w czarnej skrzynce. Agenci muszą wiedzieć, kiedy wykonują dokładne sprawdzenie, odkrywanie semantyczne, eksplorację powiązanego kodu albo potwierdzenie dowodu. Używanie narzędzi bez reguł wyboru staje się kolejnym źródłem wiarygodnie wyglądających błędów, tym samym problemem interfejsu, który stoi za pracą agentów sterowaną czatem.

Dlaczego Semble należy postawić obok pracy o grep

Niedawna praca „Is Grep All You Need?” testowała grep i wyszukiwanie wektorowe w Chronos, Claude Code, Codex CLI i Gemini CLI na konwersacyjnych zadaniach QA z długą pamięcią. W tym ustawieniu grep wstawiany bezpośrednio do kontekstu pokonał bezpośrednio wstawiane wyniki wektorowe, ale głębsza lekcja z pracy jest ważniejsza: środowisko wykonawcze zmieniało wynik równie mocno jak metoda wyszukiwania.³

Semble wskazuje tę samą warstwę operacyjną od strony kodu. Jakość wyszukiwania nie żyje wyłącznie w mechanizmie pobierania. Żyje w tym:

• jak formowane jest zapytanie;
• czy istnieją jednocześnie ścieżki dokładna i semantyczna;
• ile kontekstu zwraca narzędzie;
• czy fragmenty niosą dowody w postaci pliku i linii;
• czy agent otwiera całe pliki tylko wtedy, gdy trzeba;
• czy agenci delegowani mają dostęp do narzędzia;
• czy końcowa odpowiedź cytuje to, co wyszukiwanie naprawdę znalazło.

Opakowanie pozostaje produktem. Wyszukiwanie staje się użyteczne dopiero wtedy, gdy środowisko wykonawcze zamienia pobieranie w dowód, dlatego powierzchnia kontroli projektowania agentowego jest równie ważna jak algorytm wyszukiwania.

Standard, którego chcę

Narzędzie wyszukiwania dla agentów powinno raportować więcej niż dopasowania.

Powinno raportować:

• wykonane zapytanie;
• użyty tryb wyszukiwania;
• plik i zakres linii;
• fragment;
• szacunkową liczbę zwróconych tokenów;
• czy wynik pochodził z wyszukiwania dokładnego, semantycznego czy hybrydowego;
• kiedy agent przeszedł od fragmentu do odczytu całego pliku.

Taki wynik uczyniłby wyszukiwanie kodu audytowalnym. Recenzent widziałby, czy agent znalazł właściwy kod, przeczytał dość kontekstu i uniknął zalania się nieistotnymi plikami. Ta sama zasada napędza ślady wykonywania agentów: dowód znajduje się w ścieżce, nie tylko w odpowiedzi.

Semble już przesuwa się w tym kierunku, traktując rozmiar fragmentu i oszczędność tokenów jako pełnoprawne kwestie produktowe. Następnym krokiem dla środowisk wykonawczych agentów jest pokazanie tej ścieżki dowodowej w pakietach recenzji i końcowych odpowiedziach.

Celem nie jest ładniejsze wyszukiwanie. Celem jest mniej niepopartych twierdzeń na token.

FAQ

Czy Semble zastępuje grep?

Nie. rg należy używać do dokładnych ciągów znaków, symboli, kluczy konfiguracji, nazw plików i szybkiego potwierdzania. Wyszukiwanie fragmentów w stylu Semble warto stosować, gdy zadanie opisuje zachowanie albo powiązaną implementację, a agent nie zna dokładnego identyfikatora.

Czy lokalny test potwierdził deklaracje szybkości Semble?

Nie. Moje lokalne wywołanie uvx zajęło około 54 sekund dla pierwszego zapytania i 31 sekund dla drugiego, głównie dlatego, że uruchomienie pakietu/modelu oraz indeksowanie zdominowały doraźny przebieg. Tabela benchmarkowa Semble raportuje znacznie szybsze kontrolowane pomiary, ale mój lokalny przebieg należy traktować jako dowód dotyczący przepływu pracy, a nie benchmark wydajności.²⁵

Czy lokalny test potwierdził kierunek oszczędności tokenów?

Tak, na poziomie przepływu pracy. Semble zwrócił znacznie mniejsze fragmenty niż szeroki dosłowny wynik rg, a jego polecenie savings zaraportowało około 38 100 szacunkowo zaoszczędzonych tokenów po dwóch wyszukiwaniach. Liczba oszczędności pochodzi z własnej metody rozliczania Semble, więc należy traktować ją jako telemetrię narzędzia, nie niezależny dowód.⁵

Dlaczego wyszukiwanie kodu przez agentów ma znaczenie dla Codex i Claude Code?

Agenci tracą jakość, gdy wyszukiwanie wrzuca za dużo kontekstu albo ukrywa za dużo dowodów. Dobry przepływ pracy uczy agenta, kiedy użyć dokładnego wyszukiwania, kiedy pobierania z rankingiem fragmentów, kiedy otworzyć całe pliki i jak cytować wynik.

Czy zespoły powinny dodać Semble do AGENTS.md?

Dopiero po przetestowaniu go na własnej bazie kodu. Warto zacząć od jednej instrukcji: używać wyszukiwania z rankingiem fragmentów przy pytaniach o zachowanie, a rg przy dokładnych ciągach znaków. Następnie należy zmierzyć, czy agenci szybciej znajdują właściwe pliki i czy czytają mniej nieistotnych linii.

Źródła