Przejdź do treści

Claude Code w tmux: sesje per projekt, send-keys i granica czterech agentów

Adam Marzec
Okładka poradnika Claude Code w tmux: start wbudowany jedną flagą, skryptowanie przez send-keys, granica praktyczna około czterech agentów

Claude Code jest agentem terminalowym: żyje w linii poleceń, czyta pliki, odpala komendy i pracuje długo po tym, jak przestaniesz patrzeć na ekran. Tylko że terminal na to nie jest gotowy. Zamkniesz okno albo rozłączy się SSH i proces z agentem znika razem z połową zadania, a cztery okna z czterema agentami to już łapanie ich w przełączniku zadań. Jeśli dopiero zaczynasz, hub o ekosystemie Claude masz pod tym linkiem.

Na to jest tmux, multiplexer terminalowy z 2007 roku, który nagle znów stał się aktualny. Serwer tmux przejmuje pseudo-terminal od twojego okna, więc agent pracuje dalej po zerwaniu połączenia. Sesje dostają nazwy i listę w jednym poleceniu, a z zewnątrz, dowolnym skryptem, da się pisać do działającego agenta i czytać jego ekran. W tym poradniku składam to po kolei: sesję per projekt, wbudowaną flagę --tmux, parę poleceń send-keys oraz capture-pane do skryptowania, pasek statusu jako monitor i miejsce, w którym tmux się kończy. Piszę według dokumentacji, bez własnych testów na żywo; składnie zweryfikowałem w dwóch niezależnych źródłach, oficjalnych docs Anthropic i man tmux z OpenBSD.

Najważniejsze informacje

CelŚcieżka
Agent w izolowanym worktree z własną sesjąclaude --worktree --tmux, klasyczny tmux pod spodem z --tmux=classic
Nowa sesja per projekttmux new-session -A -s api -c ~/code/api
Wysłanie polecenia ze skryptutmux send-keys -t api:auth -l "treść", klawisz Enter osobno
Odczyt ekranu agentatmux capture-pane -p -J -S -200 -t api:auth
Ciągły log sesji do plikutmux pipe-pane -o -t api:auth 'cat >> plik.log'
Powrót do rozmowyclaude --continue albo wybór z listy przez claude --resume
Status agentów w pasku tmuxstatus-right z #(), odświeżanie status-interval 5
Granica praktycznaokoło czterech agentów, dalej orchestratory albo agent teams

Po co Claude Code tmux?

Trzy właściwości tmuxu trafiają dokładnie w kształt agenta terminalowego. Pierwsza: serwer tmux posiada pty, nie twoje okno. Zamkniesz laptopa albo zerwie się SSH, a agent liczy dalej i czeka, aż się podłączysz.

Druga: wiele nazwanych sesji w jednym miejscu. Polecenie tmux ls pokazuje kompletny stan, na przykład sesje api, web i infra z liczbą okien oraz datą utworzenia. Trzecia właściwość jest według mnie najciekawsza: tmux da się skryptować z zewnątrz, dowolna powłoka może wpisać tekst do działającej sesji albo odczytać jej ekran, bez pisania żadnego API. Producent Claude Code zauważył ten trend: flaga --tmux istnieje wbudowana, a eksperymentalny tryb agent teams ma osobny tryb wyświetlania oparty na tmuxie (docs, odczyt 21.10.2026).

Temat widać też w ruchu na Hacker News: wątek „Tmux and Claude Code: Sessions, Send-Keys, and the Ceiling” z 19 października 2026 zebrał 168 punktów, a komentujący opisują floty agentów i sufit, na który natrafiają.

Jak ustawić pierwszą sesję per projekt?

Zasada organizacyjna, która ratuje porządek: jedna sesja tmux na repozytorium, nazwana jak repozytorium. Nie na zadanie i nie na agenta, bo zadania przychodzą i odchodzą, a projekt zostaje. Instalacja to standardowy pakiet systemowy: apt install tmux na Debianie albo Ubuntu, brew install tmux na macOS (lista na wiki tmux, odczyt 21.10.2026). Instalację samego Claude Code opisywaliśmy osobno w poradniku startowym.

Sesję zakładasz jednym poleceniem. tmux new-session -d -s api -c ~/code/api tworzy sesję o nazwie api w katalogu projektu, od razu odłączoną, więc agent siedzi w tle. Do środka wchodzisz tym samym poleceniem z flagą -A, czyli tmux new-session -A -s api -c ~/code/api: man tmux opisuje, że z flagą -A polecenie zachowuje się jak dołączanie, gdy sesja o tej nazwie już istnieje, więc jedna linia jest bezpieczna do wielokrotnego uruchamiania. Pułapka: nazwa sesji nie może zawierać kropki ani dwukropka, bo tmux używa ich jako separatorów w adresowaniu celów.

W środku sesji każdemu agentowi dajesz osobne okno nazwane po zadaniu: tmux new-window -t api -n auth -c ~/code/api. Okna są lepsze od paneli dla agentów, których akurat nie oglądasz; panele zostaw sobie na te dwa albo trzy, które chcesz mieć obok siebie. Do równego kafla służy tmux select-layout tiled (wzorce pochodzą z poradnika crystl.dev, odczyt 21.10.2026; składnię poleceń sprawdziłem w man tmux, bo autor guide’a sprzedaje własny terminal, a jeden z komentujących na HN nazwał tekst reklamą).

Jak działa wbudowana flaga --worktree --tmux?

Zanim zbudujesz cokolwiek ręcznie, sprawdź ścieżkę oficjalną. Claude Code ma dwie flagi opisane w CLI reference (odczyt 21.10.2026): --worktree, w skrócie -w, uruchamia agenta w izolowanym git worktree pod /.claude/worktrees/, a --tmux tworzy dla tego worktree sesję tmux. Przykład z dokumentacji to claude -w feature-auth --tmux; sama flaga --tmux bez --worktree nie zadziała, dokumentacja wprost wymaga obu. Na iTerm2 Claude Code domyślnie używa natywnych paneli zamiast tmuxa, a --tmux=classic wymusza zwykły tmux, co przydaje się, gdy planujesz adresować sesję skryptem.

Dla jednego agenta na jednej gałęzi to cała odpowiedź i nie ma co kombinować. Ta ścieżka nie zbuduje ci jednak układu wielu agentów w jednym oknie ani nie pozwoli wpisywać do działającego agenta ze skryptu; na to zostaje klasyczny tmux z reszty poradnika. Powrót do niedokończonej rozmowy to claude --continue, ostatnia sesja z bieżącego katalogu, claude --resume, wybór z listy, a wewnątrz działającej sesji /resume (docs, odczyt 21.10.2026).

Jak skryptować agenta przez send-keys?

Polecenie tmux send-keys pisze do panelu tak, jakbyś siedział przy klawiaturze. Adresujesz cel trójką sesja:okno.pane, na przykład tmux send-keys -t api:auth "uruchom testy i napraw to, co pada" Enter. Tak wygląda sterowanie agentem z crona, z haka gita albo z drugiego agenta. Man page precyzuje: każdy argument jest nazwą klawisza, a gdy ciąg nie wygląda na klawisz, jest wysyłany jako seria znaków.

Trzy rzeczy psują tę prostotę. Po pierwsze Enter to klawisz, nie tekst, a C-c przerwie proces; flaga -l wysyła literalny tekst UTF-8, a nową linię wysyła się osobnym wywołaniem. Po drugie średnik kończy polecenie tmux, więc w treści eskapuje się go jako \;. Po trzecie tempo: niezawodny wzorzec to tekst z -l, pauza przez sleep 0.3 i osobno Enter. Przerwanie uciekającego agenta działa tym samym mechanizmem: tmux send-keys -t api:auth C-c.

Komentarz z wątku HN (frumiousirc) nazwał tę kombinację send-keys plus skrobanie terminala odpowiednikiem analog hole dla DRM, czyli obejściem oficjalnych kanałów jak tryb claude -p. Działa, ale format tego, co agent wypisze na ekran, nie jest nikomu gwarantowany.

Jak odczytać odpowiedź agenta przez capture-pane?

Drugą połowę pary stanowi tmux capture-pane, który zrzuca zawartość panelu do bufora albo na wyjście. Man tmux definiuje: z flagą -p wyjście leci na stdout zamiast do bufora, -e zachowuje sekwencje ucieczki z kolorami, a -J skleja zawinięte linie z powrotem w całość. Bez niej linia zawinięta na szerokość twojego terminala wraca jako dwie, a każdy grep po takich danych kłamie na szwach. Odczyt ostatnich dwustu linii to tmux capture-pane -p -J -S -200 -t api:auth, a cały bufor przewijania dostajesz z -S -.

Do ciągłego logu zamiast migawki służy tmux pipe-pane, który podpina polecenie powłoki do strumienia panelu: tmux pipe-pane -o -t api:auth 'cat >> ~/agent-logs/api-auth.log', wyłączenie przez ponowne wywołanie bez polecenia, bo -o działa jak przełącznik. Jedna szczerość: capture-pane daje wyrenderowaną klatkę, ze spinnerami i ramkami, a nie to, co agent „powiedział”. Parser pisany na takim wyjściu pęka, gdy producent zmieni interfejs, więc skryptujący pilnują prostych napisów, na przykład znaczników zgód.

Jak pilnować wielu agentów z paska statusu?

Każdy, kto prowadzi kilka agentów naraz, dochodzi do momentu, w którym cztery panele to za dużo oczu. Mechanizm tmuxu to interpolacja #() w pasku statusu: polecenie powłoki uruchamia się cyklicznie i jego wynik ląduje na dole ekranu. Ustawiasz set -g status-interval 5 oraz set -g status-right '#(~/bin/tmux-agent-status) | %H:%M', a skrypt iteruje po panelach poleceniem tmux list-panes -a i dla każdego robi krótki capture. Wzorzec z poradnika crystl.dev rozróżnia trzy stany: pytanie o zgodę, napis o przerwaniu albo ciszę, ale to narzędzie na kolanach, bo frazy dopasowania zależą od wersji agenta.

Lżejszą drogą są natywne mechanizmy. set-window-option -g monitor-silence 30 z set -g visual-silence on da znać, gdy panel milczy pół minuty, co jest najbliższym natywnym sygnałem „agent przestał”. Jest też droga oficjalna: od wersji v2.1.295 Claude Code raportuje stan sesji przez protokół OSC 7501, working, waiting albo done, dla terminali, które go implementują (docs, odczyt 21.10.2026). Wewnątrz tmux ten raport nie przechodzi, bo Claude Code sprawdza wtedy wsparcie tmuxa zamiast terminala. Status w pasku budujesz więc własnym skryptem, a natywny dostajesz poza tmuxem.

Jak naprawić scroll, Shift+Enter i schowek w tmux?

Trzy najczęstsze objawy wpisywane obok frazy „claude code tmux” mają oficjalne rozwiązania w dokumentacji. Zaczynam od nowej linii. W tmuxie domyślnie Shift+Enter wysyła wiadomość zamiast wstawiać znak nowej linii. Docs podają trzy linie do ~/.tmux.conf, aplikowane poleceniem tmux source-file ~/.tmux.conf. Pierwsza, set -g allow-passthrough on, przepuszcza do zewnętrznego terminala powiadomienia i pasek postępu, które tmux zjada. Dwie pozostałe uczą tmuxa rozróżniać modyfikatory: set -s extended-keys on w ustawieniach serwera oraz set -as terminal-features 'xterm*:extkeys' dla listy terminali. Jeśli nie chcesz konfigurować, Ctrl+J działa wszędzie bez ustawień.

Z przewijaniem bywa różnie zależnie od trybu renderowania. W trybie fullscreen rozmowa żyje w alternatywnym buforze ekranu, więc szukanie terminala i tryb kopiowania tmuxa nie widzą treści; docs opisują wyjście: Ctrl+O otwiera widok transkryptu, klawisz [ zapisuje całą rozmowę do natywnego bufora przewijania, po czym szukanie w terminalu i tmux copy mode działają na niej jak na zwykłym tekście. Kółko myszy wymaga set -g mouse on, a PgUp z PgDn działają zawsze. Tmux do serii 3.6 nie implementuje zsynchronizowanego wyjścia, więc migotanie przy odświeżaniu leczy aktualizacja tmuxa (docs fullscreen, odczyt 21.10.2026).

Schowek to trzeci punkt i najkrótszy: wewnątrz tmuxa Claude Code pisze zaznaczenie dodatkowo do bufora wklejania tmuxa, a poza nim korzysta z narzędzi systemowych jak wl-copy na Waylandzie. Gdy zaznaczenie łapie myszka agent zamiast terminala, docs sugerują wyłączenie przechwytywania myszy albo klawisz modyfikujący, w większości terminali Shift.

Kiedy tmux przestaje wystarczać?

Poradnik crystl.dev stawia granicę praktyczną na około czterech agentach i tłumaczy ją własnościami tmuxu, nie jego wadami. Agent czekający na zgodę wygląda identycznie jak agent myślący i jak agent, który skończył dwadzieścia minut temu: wszystkie trzy to „panel z jakimś tekstem”. Powiadomień o zakończeniu nie ma, bo tmux nie wie, czym jest agent. Dwaj agenci w dwóch sesjach nie widzą się nawzajem, a nic z tego nie przeżywa restartu maszyny.

Wątek HN pokazuje, co ludzie robią dalej. Najprostszy krok to tryb zespołowy: eksperymentalne agent teams ma tryb wyświetlania split panes wymagający tmuxa albo iTerm2, sterowany ustawieniem teammateMode w ~/.claude/settings.json albo flagą --teammate-mode z wartościami in-process albo auto, także tmux oraz iterm2 (docs, odczyt 21.10.2026); komentujący leizzo pisze, że zarządza subagentami właśnie tak. Drugi kierunek to osobny harness: symlinkk argumentuje na HN, że widok claude agents trzyma demona przeżywającego ponowne podłączenie SSH, więc w tym jednym zastosowaniu tmux „już nie jest potrzebny”. I jeden koszt przed skalowaniem: lilhawk0312 policzył około 39,6 tys. tokenów konfiguracji na każdą sesję, zanim cokolwiek napiszesz.

Co z bezpieczeństwem, gdy agent ma terminal?

Agent działający w tmuxie ma twoją powłokę, a razem z nią twoje klucze SSH. Na HN littlecranky67 opisuje wariant zabezpieczenia: trzyma klucz SSH w Secure Enclave MacBooka z potwierdzaniem odciskiem palca, więc agent nie zaloguje się na zdalne maszyny sam. Otwiera nazwaną sesję tmux, loguje się przez SSH palcem, a potem mówi agentowi, że może przejąć sesję o danej nazwie. sgarland stosuje ten sam schemat do automatyki domu: zmiany powstają offline jako infrastruktura kodu i idą na produkcję tylko po jawnej akceptacji.

Druga warstwa to separacja między agentami. petesergeant na HN pisze, że piaskownicuje agentów względem siebie oraz dysku, a sekrety partycjonuje i szyfruje osobno, pracując na zdalnym devboxie. Dokumentacja daje do tego narzędzia: worktree izoluje pliki gałęzi, a tryby uprawnień ograniczają to, co agent uruchomi bez pytania. Jeśli dwóch agentów siedzi w jednej sesji, dzielą ten sam system plików i te same poświadczenia. Osobne worktree albo osobne maszyny to nie elegancja, tylko warunek, żeby awaria jednego nie pociągnęła drugiego.

Jak pracować przez SSH i co z Windows?

Najmocniejsza strona tmuxu jest zdalna. Polecenie ssh devbox -t tmux new-session -A -s agents dołącza do sesji albo tworzy ją, z alokacją terminala, i gdy połączenie padnie w pół zadania, to samo polecenie wraca do żywej sesji. Przy słabym łączu ludzie doklejają mosh. Pułapka zagnieżdżenia: tmux lokalny i zdalny łapią ten sam prefiks; rozwiązaniem jest inny prefiks na zdalnej maszynie albo dwukrotne wciśnięcie, które wysyła go do wewnętrznej sesji.

Na Windows natywnego tmuxu nie ma. Wiki projektu wymienia pakiety dla Linuksa i macOS oraz budowanie ze źródeł z libevent i ncurses, bez wersji okienkowej (odczyt 21.10.2026). Realna ścieżka to WSL: tam instalujesz tmux jak na Debianie albo Ubuntu i wszystko z tego poradnika działa w obrębie dystrybucji, a dokumentacja Claude Code wymienia WSL jako wspieraną platformę. Granicę wyznacza tryb zespołowy: split panes agent teams nie działa w Windows Terminal, ani w zintegrowanym terminalu VS Code, ani w Ghostty, dokumentacja wymienia je z nazwy.

Co jeśli nie działa?

Najpierw klasyka adresowania. Kropki i dwukropki w nazwach sesji rozbijają składnię celów typu sesja:okno.pane, objawem jest komunikat, że sesja nie istnieje, choć tmux ls ją pokazuje. Drugi klasyk: agent nadpisuje nazwy okien, bo ustawia tytuł terminala, i twoja staranna nazwa auth znika; naprawa to set -g allow-rename off. Trzeci: panel odłączonej sesji ma rozmiar ostatniego klienta albo 80 kolumn na 24 wiersze, więc interfejs agenta po powrocie wygląda skrzywione, dopóki się nie przerysuje; pomaga set-window-option -g aggressive-resize on.

Błędy potwierdzone w dokumentacji mają własne strony. Flaga --tmux bez --worktree kończy się błędem, bo tak zaprojektowano tę parę. W trybie agent teams dokumentacja opisuje osierocone sesje tmux po zakończeniu Claude Code: listujesz przez tmux ls, zamykasz tmux kill-session -t nazwa. Brak paneli zespołu przy jawnie żądanym split panes oznacza zwykle brak tmuxa w PATH. Wewnątrz tmuxa nie działa raport statusu OSC 7501 i nie da się tego włączyć. Prefiks tmuxa C-b to ten sam klawisz co Ctrl+B w Claude Code, więc żeby przeszedł do aplikacji, użytkownicy tmuxa wciskają go dwukrotnie.

Najczęstsze pytania

Czy Claude Code ma wbudowaną integrację z tmux?

Tak, w dwóch miejscach. Flaga --tmux tworzy sesję tmux dla worktree, wymaga --worktree, a --tmux=classic wymusza zwykły tmux. Osobno eksperymentalne agent teams mają tryb split panes oparty na tmuxie, sterowany ustawieniem teammateMode.

Ile agentów da się prowadzić w tmuxie?

Poradnik crystl.dev mówi o granicy praktycznej przy czterech, głównie przez brak widoczności, kto na co czeka. Narzut konfiguracji, około 39,6 tys. tokenów na sesję według wątku HN, rośnie z liczbą sesji. Powyżej zostają agent teams, widok claude agents albo orchestratory.

Czy sesja agenta przeżyje zamknięcie terminala albo zryw SSH?

Tak, bo pty należy do serwera tmux, nie do twojego okna. Nie przeżyje restartu maszyny ani tmux kill-server, a bufor przewijania ginie razem z serwerem. Transkrypt rozmowy zostaje po stronie Claude Code.

Dlaczego Shift+Enter wysyła wiadomość zamiast łamać linię w tmux?

Tak działa domyślna konfiguracja, dokumentacja opisuje to jako znany objaw. Naprawa to trzy linie w ~/.tmux.conf: pierwsza włącza allow-passthrough on, druga extended-keys on, a trzecia ustawia terminal-features 'xterm*:extkeys'. Bez konfiguracji zawsze zadziała Ctrl+J.

Czy tmux działa na Windows?

Natywnie nie, wiki projektu prowadzi pakiety tylko dla Linuksa i macOS. W praktyce ludzie używają WSL z apt install tmux, co dokumentacja Claude Code obejmuje wsparciem WSL.

Czym zastąpić tmux do pracy z agentami?

Zellij to najbliższy zamiennik, herdr i podobne to terminale projektowane wokół agentów, a wbudowany widok claude agents z demonem przeżywającym zrywy SSH pokrywa część zastosowań bez multiplexera. Każdą z tych dróg ktoś na HN chwalił i ktoś inny krytykował.

Źródła

Powiązane artykuły