AI integration¶

Set it up with one command, run in the project:

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

On a project with no [tool.inwards] yet, inwards init --style hexagonal --agent claude writes a preset's layers and the hooks in one run (see Install).

It writes the hooks into .claude/settings.local.json, which holds settings for this machine only (init adds it to .gitignore), and keeps any hooks and settings already there. Each hook uses exec form ("command": the absolute path of the binary, "args": ["hook", "claude-code"]), so Claude Code starts it with no shell: PATH, an activated virtualenv, spaces or $ in the path, and Git Bash versus PowerShell on Windows make no difference. With --launcher "uv run" (for Inwards as a uv dev dependency), each hook is instead the shell command cd "$CLAUDE_PROJECT_DIR" && uv run inwards hook claude-code, which holds no path, and init warns when the path it would record is in uv's or bunx's cache. init also adds .inwards/ to .gitignore, pins required-version and a default ignore list (tests, scripts, migrations, conftest) in [tool.inwards], and adds three permissions.deny rules, Edit(/.claude/settings*.json), Edit(/.inwards/**) and Edit(/**/inwards-baseline.json), so Claude Code itself refuses those edits even if a hook is gone. Running it again changes nothing. It installs every hook event Inwards implements: SessionStart, PreToolUse (the config guard and the shape guard), PostToolUse and Stop.

Claude Code runs hooks around tool calls. For PostToolUse, exit code 2 doesn't undo the edit (it already happened), but Claude sees the hook's stderr and reacts to it. For Stop, exit code 2 keeps Claude working instead of ending the turn. The hook input includes stop_hook_active, and Claude Code ends the turn anyway after several consecutive blocks, so a broken stop hook can't trap the session.

To share the setup through the committed .claude/settings.json instead, run inwards init --agent claude --shared --launcher "uv run" (guide). The hooks and deny rules then go into .claude/settings.json, an inwards server running uv run inwards mcp goes into .mcp.json, and .gitignore gets only .inwards/. Committed files can't hold a machine's path, so --shared takes a launcher, or writes the bare inwards when it is on PATH and refuses otherwise. It takes Inwards' own hooks out of .claude/settings.local.json, because Claude Code merges hook lists across settings files and they would run twice, and it never replaces a team's own hooks or an inwards MCP server that runs something else. Without a launcher, the result is:

{
  "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)"
    ]
  }
}

The Stop gate reads the user, project and local settings files, so hooks in any one of them count.

inwards hook claude-code reads the hook JSON from stdin, so it needs no jq and no POSIX shell and runs the same on Windows. After a PostToolUse, it checks the one Python file the agent just wrote, or the one diagram file the diagrams key lists:

• Violation: compact JSON diagnostics on stderr, exit code 2.
• Warnings only (INW006: the file belongs to no layer): exit 0, and the same JSON goes back to the model as additionalContext, so the edit stands but the agent hears about it.
• A violation the file already had at session start: context, not a block (exit 0, a note that lists it as already there and tells the agent to leave it unless the task needs that code). A violation the edit adds still blocks, a second copy of an old import included. How the gate knows what was there is described under the stop gate below.
• Package shape (guide): INW007 blocks when the file is new this session, and is context only for a file that existed at session start under the same path, with no symlink on that path (the start identity in ADR-028), so an alias the agent creates or a start file swapped for a link still blocks, here and at Stop. INW008 for the edited file's package (a required member still missing) is always context; the Stop gate enforces it.
• Listed diagram (guide), with INW017 or INW018 on: their findings, a warning as context and an error raised by severity as a block, like the findings in a Python file. Any other non-Python file costs the hook a look at the config, under a millisecond, and the Python check is unchanged (#348). The Stop gate's default scope doesn't check diagrams; see the guide.
• Clean file, a non-Python file the diagrams key doesn't list, or any other hook event: exit 0, no output.
• Broken [tool.inwards]: the message goes to stderr with exit code 2, so an agent that broke the config hears about it. With no [tool.inwards] at all the hook stays silent, because it may be installed for every project; the config guard stops an agent from deleting the table.
• Unreadable payload or an internal error: exit 1. Claude Code shows that to the user, not the model.
• File outside the project (CLAUDE_PROJECT_DIR, or the directory Claude Code runs the hook in; never the payload's own cwd): skipped, even when the path reaches it through .. or a symlink. The payload comes from the agent, so Inwards doesn't trust it to pick what gets checked.
• Monorepos: the nearest pyproject.toml with [tool.inwards] above the edited file applies, as long as it lies inside the project. A config above CLAUDE_PROJECT_DIR is ignored, so open the session at the directory that holds the config.
• Symlinks: a file reached through a symlinked alias is checked under every name Python could import it by, so an alias can't move it out of its layer.

The hook also keeps per-session state in .inwards/state/, always on and never sent anywhere. At SessionStart (startup or /clear) it writes <session_id>.start.json: the HEAD commit, every [tool.inwards] table in the project, a hash of every Python file, a hash of each inwards-baseline.json and the symlinks in layer packages with their real targets. Next to it goes <session_id>.content.json, copies of the Python files git can't give back as they were at start (see the Stop gate below). It writes each to a temporary file and renames it, so neither is ever half-written. After each edit it appends one line to <session_id>.jsonl: the file and a fingerprint of each reported violation (rule, module, message). Hooks run in parallel, so the log is only ever appended to. The Stop gate and escalation below read this state to tell violations the session introduced from ones that were already there. A session without its start file counts as unknown, and the Stop gate treats unknown as not clean. A resume or compact never writes a new start, so deleting .inwards/ mid-session can't be undone by the next SessionStart. The hook refuses to follow a symlinked .inwards or state, so state can't be written outside the project. Other sessions older than a week, or beyond the newest 50, are pruned when a session starts.

At Stop, the same command runs the stop gate. It checks every Python file the session changed: the edits the per-edit hook saw, plus every file whose content hash differs from the session start. The hash comparison doesn't depend on git, so a commit made mid-session, git update-index --assume-unchanged, gitignored and untracked files all count as changes. Inside a top-level package that holds a layer (shop/ for shop.domain), nothing is skipped, so a pyvenv.cfg, a node_modules directory or a symlink into one can't hide a module there (inwards check walks the same way). A layer module that disappears while a module with the same name or content appears outside every layer counts as moved out of the layer, and fails the gate. So does a symlink made in a layer during the session that points out of the config root or into another layer (INW006): the hashes can't see a link out of the project, so the start record lists the links. Other files aren't checked. An INW001 verdict depends only on module names, so an edit can't make a file that imports it newly violate. INW006 is the exception: a module created outside every layer makes an untouched file that already imported that name fail. For a new top-level package the gate handles it: the start record lists the top-level modules under each root (compiled ones and packages the walk skips included), and the gate also checks every file under root that spells a new name as a top-level name, and checks their session-start version without the package (a file the session didn't change is its own start version, so its old violations stay old even past the copy caps), so a requests/__init__.py added under an old import requests in a layer blocks (#86). That reads every file under root, but only in a session that added a top-level name. For a module created deeper down, or for a stricter gate, set stop-gate = "project" in [tool.inwards]: the gate then checks the whole project against its baseline on every Stop, so any violation the baseline doesn't accept blocks, wherever it is. It costs a whole-project check per Stop, about 0.5 s on the 2,100-file synthetic repo with every violation baselined, and without a baseline every legacy violation blocks. The mode is read from the session-start snapshot, so turning it off mid-session only fails the config comparison. If a baseline changed during the session, the gate can't trust it and falls back to the changed files, so it doesn't dump every legacy violation. A symlinked pyproject.toml is checked over the tree it sits in, not its target's.

In a changed file, only violations the file didn't have at session start block. An agent asked to add a property to a file with an old violation used to be kept working until that violation was gone, and in the 2026-09-26 eval it deleted or changed functions to get there (#134). Now the old violations go along as context when the gate blocks for something else, and a clean turn ends. To know what a file had, the gate reads the file's raw blob from git at the commit the session started on (git cat-file blob), uses it, or the same text with CRLF line endings for core.autocrlf, only if its SHA-256 matches the start manifest, and checks it. It never applies filters: a filter driver comes from .gitattributes and .git/config, which the agent can write, so running one would run the agent's command outside Claude Code's permissions. For the same reason it passes --no-lazy-fetch: in a repo the agent turned into a partial clone, a missing blob would otherwise be fetched through a remote whose ext:: URL or core.sshCommand the agent chose. Git older than 2.44 rejects that flag, so there the gate never reads a blob, and every file's start content comes from the copies described below. Old violations don't reach the run log either, so inwards stats doesn't count them as introduced. Errors match by rule, module and message, not by line, counted like the baseline: one old import, moved or not, stays old, and a second copy of it is new. The check runs only for a changed file that has errors, once per Stop and once per edit in the PostToolUse hook; on the eval's example app it adds about 20 ms to a hook run that finds an old violation. A file that was modified, untracked or outside git at session start has no blob to read, so SessionStart keeps a copy of it in .inwards/state/<session_id>.content.json (#157). It finds those files with git ls-tree on the start commit, which runs no filters either: a file whose bytes are the blob's, or the blob's with CRLF line endings, gets no copy. The gate trusts a copy the same way as a blob, only if its SHA-256 matches the start manifest, so a copy edited through Bash is ignored. Only a file that is its own start identity gets a copy, so a symlink alias can't borrow one. Copies are capped at 512 KiB per file and 4 MiB per session; a file past a cap has no provable start content, so every violation in it counts as new and blocks, and a baseline covers that case. The copies are written like the start record, atomically and without following a symlink, and pruned with it. On the 2,100-file synthetic repo they add about 30 ms to SessionStart with a clean or slightly dirty tree (the ls-tree call and hashing each file as a git blob), and about 50 ms with 500 dirty files or on git before 2.44, which copies every file up to the cap. Two alternatives were rejected: checking every file at SessionStart costs a whole-project check per session, and the first PostToolUse report of a file already includes the agent's first edit. stop-gate = "project" doesn't use this: there, every violation the baseline doesn't accept blocks, wherever it is.

It also refuses to let the turn end when it can't trust the session:

• No start record, because .inwards/ was deleted or the hooks were installed mid-session. When Claude Code sets stop_hook_active after a block, the gate lets that turn end.
• [tool.inwards] differs from the start snapshot, for example after a sed -i through Bash, or a changed file falls under a pyproject.toml that had no valid [tool.inwards] at the start (a new, permissive config nested in a layer). After a changed [tool.inwards], the gate checks the changed files with the start snapshot, so the block also lists what the change would hide: with ignore = ["INW001"] or severity = { INW001 = "warning" } added through Bash, an INW001 violation still shows up as an error (#164).
• The Inwards SessionStart, PreToolUse or PostToolUse hook is gone from every settings layer (user, project, local), including a matcher that no longer covers the tools it must see, or disableAllHooks is set. The check reads the settings, not the programs they run, so it proves the configuration, not that the real Inwards runs. Claude Code reloads hooks when settings change, so removing the Stop hook itself switches the gate off at once; the config guard (below) is what blocks those edits.

It blocks a turn at most escalate-after times (default 3). The Stop after the last block lets the turn end and shows the user what is still unresolved, and escalation (below) turns the repeated failure into a question for the user. The count starts again with each new turn. If the gate itself fails (an unreadable file, say), it blocks once with the error and lets the turn end on the next try, so a broken gate can't keep a session going forever.

inwards init --agent opencode writes the project plugin .opencode/plugins/inwards.js (also added to .gitignore, since it holds the binary's absolute path). The plugin turns OpenCode's events into the payloads above and runs inwards hook claude-code, so the per-edit check, the config guard, the Stop gate and escalation are the same code. OpenCode can't refuse the end of a turn: when the session goes idle, a blocking Stop gate sends its reasons back as a new message, which starts another turn. apply_patch can't be read by the guard, so the plugin refuses patches that touch pyproject.toml or Inwards' files. The OpenCode guide lists every difference, and ADR-033 the design.

Aider lints the files it edits and, when the linter fails, shows the output to the model and asks it to fix the problems. Inwards plugs in as the Python lint command. inwards init --agent aider prints the exact line, with the absolute binary path, for .aider.conf.yml:

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

Aider runs the command from the git root, once per edited file, with that file's path appended. Text output is enough here, because Aider forwards it to the model as is. Aider has no Stop hook or config guard; the Aider guide covers what to do instead.

Copilot has no hook Inwards can use. In VS Code, the extension puts every violation in the Problems panel, and the agent sees them when it reads that panel (the #read/problems tool) or runs the check that AGENTS.md asks for. inwards mcp gives it the MCP tools.

The Copilot cloud agent, which works on GitHub and opens pull requests, reads the same AGENTS.md, gets Inwards from .github/workflows/copilot-setup-steps.yml, and is held to the layers by the CI check on its pull request. The GitHub Copilot guide has the setup for both.

Every agent that reads AGENTS.md can be told to run the check. inwards init --agent agents-md adds (or updates) this section between <!-- inwards:begin --> and <!-- inwards:end --> markers:

## 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.

An instruction is weaker than a hook, because the agent can skip it. Where the agent has a hook system, install the hook as well (inwards init --agent claude).

An agent with an MCP client (Codex CLI, Cursor and Claude Code among them) can also ask Inwards directly through inwards mcp: where new code belongs, whether code passes before it is written, and what a rule means. The MCP guide has the setup for each client.