Claude Code¶

With the hooks installed, Inwards checks every Python file Claude writes, and every architecture diagram the config lists. It won't let the turn end while the session's changes break a layer, and it refuses edits to the rules themselves. Chapter 4 explains the design.

Set it up¶

1. Install Inwards and add [tool.inwards] to pyproject.toml.

2. In the project, run:

   inwards init --agent claude --dry-run   # shows what will change
   inwards init --agent claude
   

   This writes four hooks (SessionStart, PreToolUse, PostToolUse, Stop) and three permissions.deny rules into .claude/settings.local.json. That file holds this machine's path to the binary, so init adds it to .gitignore, together with .inwards/. It also pins required-version and a default ignore list in [tool.inwards]. Running it again changes nothing.

   If Inwards is a uv dev dependency, record the launcher instead of a path:

   uv run inwards init --agent claude --launcher "uv run"
   

   Each hook then runs cd "$CLAUDE_PROJECT_DIR" && uv run inwards hook claude-code in the shell, from the project root, so it uses the project's own environment in every worktree and on every machine. --launcher takes a tool runner (uv, uvx, poetry, pdm, hatch, pipx, rye, pixi, bunx, npx or python) with its subcommand and options, in plain words only (letters, digits and _ . : @ = + / -), because it goes into a shell command unquoted. The Stop gate counts only such hooks as Inwards' own, so echo inwards hook claude-code can't stand in for one.

   To share the hooks with the team instead, see Share it with the team.

3. Start a new Claude Code session in the project (or run /clear). Hooks installed mid-session still work, but the Stop gate needs the session start it records.

Share it with the team¶

--shared writes the setup into files you commit, so everyone who clones the project gets the hooks and the MCP server without running init:

uv run inwards init --agent claude --shared --launcher "uv run"

• The four hooks and the permissions.deny rules go into .claude/settings.json, the project settings Claude Code reads for everyone in the repository (Claude Code settings).
• An inwards server goes into .mcp.json under mcpServers, as {"command": "uv", "args": ["run", "inwards", "mcp"]}. Claude Code asks each user to approve a project's servers the first time (Claude Code MCP).
• .gitignore gets only .inwards/; commit .claude/settings.json and .mcp.json.
• If .claude/settings.local.json holds Inwards hooks from an earlier init, --shared takes them out and keeps the rest of that file. Claude Code merges hook lists from every settings file, so they would otherwise run twice. A later init --agent claude without --shared warns about the same thing.

Committed files can't hold your machine's path to the binary, so --shared needs --launcher, or inwards on PATH: without a launcher it writes the bare command inwards hook claude-code and {"command": "inwards", "args": ["mcp"]}, and refuses with exit 2 when inwards isn't on PATH. Every teammate then needs it on theirs too, which is why a launcher with Inwards as a dev dependency is the safer choice.

Running it again changes nothing. Your team's own hooks and MCP servers stay as they are; an inwards server in .mcp.json that runs something other than inwards mcp stops init with exit 2 instead of being replaced. The Stop gate looks for its hooks in the user, project and local settings files, so hooks that live only in .claude/settings.json count.

Check it works¶

• In Claude Code, run /hooks. inwards is listed under SessionStart, PreToolUse, PostToolUse and Stop.
• Ask Claude: "Add import shop.infrastructure.db at the top of shop/domain/order.py." The edit goes through, then Claude gets an INW001 report and removes the import or introduces a port.
• Ask Claude: "Move shop.infrastructure into the domain layer in pyproject.toml." The edit is refused with a message telling Claude to ask you.

The hook daemon¶

PostToolUse, the hook that checks each file Claude writes, runs more often than the others. To keep it fast, a PostToolUse in a project with an Inwards session starts inwards daemon in the background: one process per project that keeps the parser and the files it has read in memory and answers the next PostToolUse hooks through a local socket (a named pipe on Windows). On an arm64 laptop running macOS, PostToolUse on a 13-line file took 38 ms p50 without it and 15 ms with it (chapter 6).

• It changes speed, never results. It runs the same hook code, and it reads the config, the baseline and the session record again for every edit. When it isn't running, comes from another Inwards build or doesn't answer, the hook runs in its own process as before, then starts a new one.
• SessionStart, PreToolUse and the Stop gate never use it. The Stop gate checks everything the session changed in its own process.
• It exits after 10 minutes without an edit, so there is nothing to set up or clean up.
• It only starts in a project that has Inwards session state (.inwards/state). A hook installed for every project leaves no process behind in the others.

inwards daemon status   # is one running for this project, and how many hook runs it served
inwards daemon stop     # stop it; the next edit starts a new one
inwards daemon          # run it in the foreground (--idle SECONDS sets the idle limit)

INWARDS_DAEMON=0 in the environment Claude Code runs in turns it off, and every hook runs in its own process. It is off when CI is set, unless INWARDS_DAEMON=1. Its record is in $XDG_STATE_HOME/inwards/daemons/ (~/.local/state/inwards/daemons/ by default) and its socket in $XDG_RUNTIME_DIR/inwards/, else $TMPDIR/inwards-<uid>/, both readable only by you. When no socket directory is usable, the daemon exits at once; hooks then start no other one for 5 minutes, and inwards daemon status says why the last start failed. Inside the daemon, the git calls of one PostToolUse share a 5-second limit, so a git that hangs costs that hook its session-start comparison instead of blocking every later edit; the Stop gate runs git without a limit. ADR-039 has the design.

Troubleshooting¶

To share the setup with the team through the committed .claude/settings.json, see Share it with the team.