Integracja z AI¶

Skonfiguruj to jednym poleceniem, uruchomionym w projekcie:

inwards init --agent claude            # --dry-run shows the diff first

W projekcie, który nie ma jeszcze [tool.inwards], inwards init --style hexagonal --agent claude zapisuje warstwy z presetu i hooki w jednym uruchomieniu (zobacz Instalacja).

Polecenie zapisuje hooki w .claude/settings.local.json, który przechowuje ustawienia tylko dla tej maszyny (init dodaje go do .gitignore), i zachowuje wszystkie hooki i ustawienia, które już tam są. Każdy hook używa formy exec ("command": bezwzględna ścieżka do pliku binarnego, "args": ["hook", "claude-code"]), więc Claude Code uruchamia go bez powłoki: PATH, aktywowany virtualenv, spacje ani $ w ścieżce, ani Git Bash kontra PowerShell na Windows nie mają znaczenia. Z --launcher "uv run" (dla Inwards jako zależności deweloperskiej uv) każdy hook jest zamiast tego poleceniem powłoki cd "$CLAUDE_PROJECT_DIR" && uv run inwards hook claude-code, które nie zawiera żadnej ścieżki, a init ostrzega, gdy ścieżka, którą by zapisał, leży w pamięci podręcznej uv albo bunx. init dodaje też .inwards/ do .gitignore, przypina required-version i domyślną listę ignore (tests, scripts, migrations, conftest) w [tool.inwards] i dodaje trzy reguły permissions.deny, Edit(/.claude/settings*.json), Edit(/.inwards/**) i Edit(/**/inwards-baseline.json), więc sam Claude Code odrzuca te edycje, nawet gdy hooka zabraknie. Ponowne uruchomienie niczego nie zmienia. Instaluje każde zdarzenie hooka, które implementuje Inwards: SessionStart, PreToolUse (config guard i shape guard), PostToolUse i Stop.

Claude Code uruchamia hooki wokół wywołań narzędzi. Dla PostToolUse kod wyjścia 2 nie cofa edycji (ona już się wydarzyła), ale Claude widzi stderr hooka i na nie reaguje. Dla Stop kod wyjścia 2 każe Claude'owi dalej pracować zamiast kończyć turę. Dane wejściowe hooka zawierają stop_hook_active, a Claude Code i tak kończy turę po kilku kolejnych blokadach, więc zepsuty hook Stop nie może uwięzić sesji.

Żeby zamiast tego udostępnić konfigurację przez commitowany .claude/settings.json, uruchom inwards init --agent claude --shared --launcher "uv run" (przewodnik). Hooki i reguły deny trafiają wtedy do .claude/settings.json, serwer inwards uruchamiający uv run inwards mcp do .mcp.json, a do .gitignore tylko .inwards/. Commitowane pliki nie mogą zawierać ścieżki z konkretnej maszyny, więc --shared przyjmuje launcher albo zapisuje samo inwards, gdy jest w PATH, a w przeciwnym razie odmawia. Usuwa własne hooki Inwards z .claude/settings.local.json, bo Claude Code łączy listy hooków z plików ustawień i uruchamiałyby się dwa razy, i nigdy nie zastępuje własnych hooków zespołu ani serwera MCP inwards, który uruchamia coś innego. Bez launchera wynik wygląda tak:

{
  "hooks": {
    "SessionStart": [
      { "hooks": [{ "type": "command", "command": "inwards hook claude-code" }] }
    ],
    "PreToolUse": [
      {
        "matcher": "Edit|Write|MultiEdit|Bash",
        "hooks": [{ "type": "command", "command": "inwards hook claude-code" }]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Edit|Write|MultiEdit",
        "hooks": [{ "type": "command", "command": "inwards hook claude-code" }]
      }
    ],
    "Stop": [
      { "hooks": [{ "type": "command", "command": "inwards hook claude-code" }] }
    ]
  },
  "permissions": {
    "deny": [
      "Edit(/.claude/settings*.json)",
      "Edit(/.inwards/**)",
      "Edit(/**/inwards-baseline.json)"
    ]
  }
}

Stop gate czyta pliki ustawień użytkownika, projektu i lokalny, więc liczą się hooki w dowolnym z nich.

inwards hook claude-code czyta JSON hooka ze stdin, więc nie potrzebuje jq ani powłoki POSIX i działa tak samo na Windows. Po PostToolUse sprawdza ten jeden plik Pythona, który agent właśnie zapisał, albo ten jeden plik diagramu wymieniony w kluczu diagrams:

• Naruszenie: zwięzłe diagnostyki JSON na stderr, kod wyjścia 2.
• Naruszenie, które plik miał już na początku sesji: kontekst, a nie blokada (kod wyjścia 0, notatka, która wymienia je jako już istniejące i każe agentowi zostawić je w spokoju, chyba że zadanie wymaga tego kodu). Naruszenie dodane przez edycję nadal blokuje, łącznie z drugą kopią starego importu. To, skąd bramka wie, co już było, opisuje niżej część o Stop gate.
• Same ostrzeżenia (INW006: plik nie należy do żadnej warstwy): kod wyjścia 0, a ten sam JSON wraca do modelu jako additionalContext, więc edycja zostaje, ale agent się o tym dowiaduje.
• Kształt pakietu (przewodnik): INW007 blokuje, gdy plik jest nowy w tej sesji, a dla pliku, który istniał na początku sesji pod tą samą ścieżką, bez dowiązania symbolicznego na tej ścieżce (tożsamość startowa z ADR-028), jest tylko kontekstem. Alias utworzony przez agenta albo plik z początku sesji podmieniony na dowiązanie nadal blokuje, tu i w Stop gate. INW008 dla pakietu edytowanego pliku (wciąż brakuje wymaganego elementu) jest zawsze kontekstem; egzekwuje go Stop gate.
• Wymieniony diagram (przewodnik), przy włączonej INW017 albo INW018: ich zgłoszenia, ostrzeżenie jako kontekst, a błąd podniesiony przez severity jako blokada, tak jak zgłoszenia w pliku Pythona. Każdy inny plik spoza Pythona kosztuje hook zajrzenie do konfiguracji, poniżej milisekundy, a sprawdzenie Pythona się nie zmienia (#348). Domyślny zakres Stop gate nie sprawdza diagramów; zobacz przewodnik.
• Czysty plik, plik spoza Pythona, którego klucz diagrams nie wymienia, albo każde inne zdarzenie hooka: kod wyjścia 0, brak wyjścia.
• Zepsute [tool.inwards]: komunikat trafia na stderr z kodem wyjścia 2, więc agent, który zepsuł konfigurację, się o tym dowiaduje. Gdy [tool.inwards] w ogóle nie ma, hook milczy, bo może być zainstalowany dla każdego projektu; config guard nie pozwala agentowi usunąć tabeli.
• Nieczytelne dane wejściowe albo błąd wewnętrzny: kod wyjścia 1. Claude Code pokazuje to użytkownikowi, a nie modelowi.
• Plik spoza projektu (CLAUDE_PROJECT_DIR albo katalog, w którym Claude Code uruchamia hook; nigdy cwd z samych danych wejściowych): pomijany, nawet gdy ścieżka sięga do niego przez .. albo dowiązanie symboliczne. Dane wejściowe pochodzą od agenta, więc Inwards nie pozwala im decydować, co zostanie sprawdzone.
• Monorepo: obowiązuje najbliższy pyproject.toml z [tool.inwards] nad edytowanym plikiem, o ile leży wewnątrz projektu. Konfiguracja powyżej CLAUDE_PROJECT_DIR jest ignorowana, więc otwieraj sesję w katalogu, który zawiera konfigurację.
• Dowiązania symboliczne: plik osiągnięty przez alias-dowiązanie jest sprawdzany pod każdą nazwą, pod którą Python mógłby go zaimportować, więc alias nie może wyprowadzić go z jego warstwy.

Hook przechowuje też stan dla każdej sesji w .inwards/state/, zawsze włączony i nigdy nigdzie niewysyłany. Przy SessionStart (start albo /clear) zapisuje <session_id>.start.json: commit HEAD, każdą tabelę [tool.inwards] w projekcie, hash każdego pliku Pythona, hash każdego inwards-baseline.json oraz dowiązania symboliczne w pakietach warstw z ich rzeczywistymi celami. Obok trafia <session_id>.content.json, kopie plików Pythona, których zawartości ze startu git nie potrafi oddać (patrz Stop gate niżej). Każdy z nich zapisuje do pliku tymczasowego i zmienia jego nazwę, więc żaden nigdy nie jest zapisany w połowie. Po każdej edycji dopisuje jedną linię do <session_id>.jsonl: plik i fingerprint każdego zgłoszonego naruszenia (reguła, moduł, komunikat). Hooki działają równolegle, więc do logu tylko się dopisuje. Stop gate i eskalacja opisane niżej czytają ten stan, żeby odróżnić naruszenia wprowadzone w sesji od tych, które już były. Sesja bez pliku startowego liczy się jako nieznana, a Stop gate traktuje nieznaną sesję jako nieczystą. Ani wznowienie, ani kompaktowanie nie zapisuje nowego startu, więc usunięcia .inwards/ w trakcie sesji nie cofnie następny SessionStart. Hook nie podąża za dowiązaniem symbolicznym .inwards ani state, więc stanu nie da się zapisać poza projektem. Inne sesje starsze niż tydzień albo spoza 50 najnowszych są usuwane przy starcie sesji.

Przy Stop to samo polecenie uruchamia Stop gate. Sprawdza każdy plik Pythona zmieniony w sesji: edycje, które widział hook edycji, oraz każdy plik, którego hash zawartości różni się od stanu z początku sesji. Porównanie hashy nie zależy od gita, więc commit zrobiony w trakcie sesji, git update-index --assume-unchanged, pliki ignorowane przez gita i nieśledzone liczą się jako zmiany. Wewnątrz pakietu najwyższego poziomu, który zawiera warstwę (shop/ dla shop.domain), nic nie jest pomijane, więc pyvenv.cfg, katalog node_modules ani dowiązanie do niego nie ukryją tam modułu (inwards check przegląda pliki tak samo). Moduł warstwy, który znika, gdy moduł o tej samej nazwie albo zawartości pojawia się poza wszystkimi warstwami, liczy się jako wyprowadzony z warstwy i oblewa bramkę. Tak samo dowiązanie symboliczne utworzone w warstwie w trakcie sesji, które wskazuje poza katalog root albo do innej warstwy (INW006): hashe nie widzą dowiązania poza projekt, więc zapis startu sesji wymienia dowiązania. Inne pliki nie są sprawdzane. Werdykt INW001 zależy tylko od nazw modułów, więc edycja pliku nie może sprawić, że plik, który go importuje, zacznie naruszać reguły. Wyjątkiem jest INW006: moduł utworzony poza wszystkimi warstwami sprawia, że nietknięty plik, który już importował tę nazwę, nie przechodzi. Nowy pakiet najwyższego poziomu bramka obsługuje sama: zapis startu sesji wymienia moduły najwyższego poziomu pod każdym root (także skompilowane i pakiety, które pomija przeszukiwanie drzewa), a bramka sprawdza też każdy plik pod root, który zapisuje nową nazwę jako nazwę najwyższego poziomu, a ich wersję ze startu sesji sprawdza bez tego pakietu (plik, którego sesja nie zmieniła, sam jest swoją wersją ze startu, więc jego stare naruszenia pozostają stare także ponad limitami kopii), więc requests/__init__.py dodany pod starym import requests w warstwie blokuje (#86). Wymaga to przeczytania każdego pliku pod root, ale tylko w sesji, która dodała nazwę najwyższego poziomu. Na moduł utworzony głębiej, albo dla ostrzejszej bramki, ustaw stop-gate = "project" w [tool.inwards]: bramka sprawdza wtedy przy każdym Stop cały projekt względem jego baseline'u, więc każde naruszenie, którego baseline nie akceptuje, blokuje, gdziekolwiek jest. Kosztuje to sprawdzenie całego projektu przy każdym Stop, około 0,5 s na syntetycznym repozytorium z 2100 plikami, w którym każde naruszenie jest w baseline'ie, a bez baseline'u blokuje każde stare naruszenie. Tryb jest odczytywany z migawki z początku sesji, więc wyłączenie go w trakcie sesji powoduje tylko niezgodność przy porównaniu konfiguracji. Jeśli baseline zmienił się w trakcie sesji, bramka nie może mu ufać i wraca do zmienionych plików, więc nie zasypuje agenta wszystkimi starymi naruszeniami. Dowiązany symbolicznie pyproject.toml jest sprawdzany dla drzewa, w którym leży, a nie dla drzewa swojego celu.

W zmienionym pliku blokują tylko naruszenia, których plik nie miał na początku sesji. Agent poproszony o dodanie właściwości do pliku ze starym naruszeniem był wcześniej trzymany przy pracy, dopóki to naruszenie nie zniknęło, i w ewaluacji z 2026-09-26 usuwał albo zmieniał funkcje, żeby do tego doprowadzić (#134). Teraz stare naruszenia trafiają do agenta jako kontekst, gdy bramka blokuje z innego powodu, a czysta tura się kończy. Żeby wiedzieć, co plik zawierał, bramka czyta surowy blob pliku z gita na commicie, od którego zaczęła się sesja (git cat-file blob), używa go (albo tego samego tekstu z końcami linii CRLF, na potrzeby core.autocrlf) tylko wtedy, gdy jego SHA-256 zgadza się z manifestem startowym, i go sprawdza. Nigdy nie stosuje filtrów: sterownik filtra pochodzi z .gitattributes i .git/config, które agent może zapisać, więc uruchomienie go oznaczałoby uruchomienie polecenia agenta poza uprawnieniami Claude Code. Z tego samego powodu przekazuje --no-lazy-fetch: w repozytorium, które agent zamienił w częściowy klon (partial clone), brakujący blob zostałby inaczej pobrany przez zdalne repozytorium, którego URL ext:: albo core.sshCommand wybrał agent. Git starszy niż 2.44 odrzuca tę flagę, więc bramka nie czyta tam żadnego bloba, a zawartość startowa każdego pliku pochodzi z kopii opisanych niżej. Stare naruszenia nie trafiają też do run logu, więc inwards stats nie liczy ich jako wprowadzonych. Błędy są dopasowywane po regule, module i komunikacie, a nie po linii, i liczone tak jak w baseline'ie: jeden stary import, przeniesiony czy nie, pozostaje stary, a jego druga kopia jest nowa. To sprawdzenie działa tylko dla zmienionego pliku z błędami, raz na Stop i raz na edycję w hooku PostToolUse; na przykładowej aplikacji z ewaluacji dodaje około 20 ms do uruchomienia hooka, które znajduje stare naruszenie. Plik, który na początku sesji był zmieniony, nieśledzony albo poza gitem, nie ma bloba do przeczytania, więc SessionStart zachowuje jego kopię w .inwards/state/<session_id>.content.json (#157). Takie pliki znajduje przez git ls-tree na commicie startowym, który też nie uruchamia filtrów: plik, którego bajty są bajtami bloba albo bloba z końcami linii CRLF, nie dostaje kopii. Bramka ufa kopii tak samo jak blobowi, tylko jeśli jej SHA-256 zgadza się z manifestem startowym, więc kopia zmieniona przez Bash jest pomijana. Kopię dostaje tylko plik, który jest swoją własną tożsamością startową, więc alias przez dowiązanie symboliczne nie może jej pożyczyć. Kopie mają limit 512 KiB na plik i 4 MiB na sesję; plik ponad limitem nie ma zawartości startowej, której da się dowieść, więc każde naruszenie w nim liczy się jako nowe i blokuje, a ten przypadek obejmuje baseline. Kopie są zapisywane jak rekord startowy, atomowo i bez podążania za dowiązaniem symbolicznym, i usuwane razem z nim. Na syntetycznym repozytorium z 2100 plikami dodają około 30 ms do SessionStart przy czystym albo lekko zmienionym drzewie (wywołanie ls-tree i hashowanie każdego pliku jako bloba gita) i około 50 ms przy 500 zmienionych plikach albo na gicie starszym niż 2.44, który kopiuje każdy plik aż do limitu. Odrzucono dwie alternatywy: sprawdzanie każdego pliku przy SessionStart kosztuje sprawdzenie całego projektu na sesję, a pierwszy raport PostToolUse dla pliku zawiera już pierwszą edycję agenta. stop-gate = "project" z tego nie korzysta: tam blokuje każde naruszenie, którego nie akceptuje baseline, gdziekolwiek jest.

Bramka nie pozwala też zakończyć tury, gdy nie może ufać sesji:

• Brak zapisu startu, bo usunięto .inwards/ albo hooki zainstalowano w trakcie sesji. Gdy Claude Code ustawi stop_hook_active po blokadzie, bramka pozwala tej turze się zakończyć.
• [tool.inwards] różni się od migawki z początku sesji, na przykład po sed -i przez Bash, albo zmieniony plik podlega pyproject.toml, który na początku nie miał poprawnego [tool.inwards] (nowa, pobłażliwa konfiguracja zagnieżdżona w warstwie). Po zmianie [tool.inwards] bramka sprawdza zmienione pliki według migawki z początku sesji, więc blokada pokazuje też to, co zmiana by ukryła: gdy przez Bash dodano ignore = ["INW001"] albo severity = { INW001 = "warning" }, naruszenie INW001 nadal pojawia się jako błąd (#164).
• Hook SessionStart, PreToolUse albo PostToolUse Inwards zniknął ze wszystkich warstw ustawień (użytkownika, projektu, lokalnej), łącznie z matcherem, który nie obejmuje już narzędzi, które musi widzieć, albo ustawiono disableAllHooks. Sprawdzenie czyta ustawienia, a nie programy, które one uruchamiają, więc dowodzi konfiguracji, a nie tego, że działa prawdziwy Inwards. Claude Code przeładowuje hooki, gdy ustawienia się zmieniają, więc usunięcie samego hooka Stop od razu wyłącza bramkę; te edycje blokuje config guard (niżej).

Bramka blokuje turę najwyżej escalate-after razy (domyślnie 3). Stop po ostatniej blokadzie pozwala zakończyć turę i pokazuje użytkownikowi, co wciąż jest nierozwiązane, a eskalacja (niżej) zamienia powtarzającą się porażkę w pytanie do użytkownika. Licznik zaczyna się od nowa z każdą nową turą. Jeśli sama bramka zawiedzie (na przykład nieczytelny plik), blokuje raz z błędem i pozwala zakończyć turę przy następnej próbie, więc zepsuta bramka nie może ciągnąć sesji w nieskończoność.

inwards init --agent opencode zapisuje plugin projektu .opencode/plugins/inwards.js (dodany też do .gitignore, bo zawiera bezwzględną ścieżkę do pliku binarnego). Plugin zamienia zdarzenia OpenCode na powyższe ładunki i uruchamia inwards hook claude-code, więc sprawdzenie po edycji, strażnik konfiguracji, bramka Stop i eskalacja to ten sam kod. OpenCode nie może odmówić zakończenia tury: gdy sesja przechodzi w bezczynność, blokująca bramka Stop odsyła swoje powody jako nową wiadomość, która zaczyna kolejną turę. Strażnik nie przeczyta apply_patch, więc plugin odmawia łatek dotykających pyproject.toml albo plików Inwards. Przewodnik po OpenCode wymienia każdą różnicę, a ADR-033 opisuje projekt.

Aider lintuje pliki, które edytuje, a gdy linter zgłasza błąd, pokazuje wyjście modelowi i prosi go o naprawienie problemów. Inwards podłącza się jako polecenie lintujące dla Pythona. inwards init --agent aider wypisuje dokładną linię, z bezwzględną ścieżką do pliku binarnego, do .aider.conf.yml:

lint-cmd: "python: '/home/you/.local/bin/inwards' check --format text"

Aider uruchamia polecenie z katalogu głównego repozytorium git, raz na każdy edytowany plik, z dopisaną ścieżką tego pliku. Wystarczy tu wyjście tekstowe, bo Aider przekazuje je modelowi bez zmian. Aider nie ma hooka Stop ani config guarda; przewodnik po Aiderze opisuje, co zrobić zamiast tego.

Copilot nie ma hooka, z którego Inwards mógłby skorzystać. W VS Code rozszerzenie umieszcza każde naruszenie w panelu Problems, a agent widzi je, gdy czyta ten panel (narzędzie #read/problems) albo uruchamia sprawdzenie, o które prosi AGENTS.md. inwards mcp daje mu narzędzia MCP.

Agent Copilota w chmurze (cloud agent), który pracuje na GitHubie i otwiera pull requesty, czyta ten sam AGENTS.md, dostaje Inwards z .github/workflows/copilot-setup-steps.yml, a warstw pilnuje sprawdzenie w CI na jego pull requeście. Poradnik GitHub Copilot opisuje konfigurację obu.

Każdemu agentowi, który czyta AGENTS.md, można kazać uruchomić sprawdzenie. inwards init --agent agents-md dodaje (albo aktualizuje) tę sekcję między znacznikami <!-- inwards:begin --> i <!-- inwards:end -->:

## Architecture check (Inwards)

The layers in `[tool.inwards]` (pyproject.toml) are enforced. Before you finish a task, run:

    inwards check --format json

Exit code 1 means an import breaks a layer: follow the numbered `fix.steps` in the output.
Don't edit `[tool.inwards]` to make the check pass; ask the user instead.

Instrukcja jest słabsza niż hook, bo agent może ją pominąć. Tam, gdzie agent ma system hooków, zainstaluj również hook (inwards init --agent claude).

Agent z klientem MCP (między innymi Codex CLI, Cursor i Claude Code) może też pytać Inwards bezpośrednio przez inwards mcp: gdzie należy nowy kod, czy kod przejdzie sprawdzenie, zanim zostanie zapisany, i co znaczy reguła. Poradnik MCP opisuje konfigurację każdego klienta.