GitHub Copilot¶

Copilot has no hook that Inwards can plug into the way the Claude Code hooks do. It meets Inwards in four places instead:

An instruction or a tool works only when the agent follows it, so CI stays the gate for both.

Copilot in VS Code¶

1. Install Inwards and add [tool.inwards] to pyproject.toml.
2. Install the VS Code extension. It runs inwards server and puts every violation in the Problems panel.

3. Add the instruction to AGENTS.md, and commit it:

   inwards init --agent agents-md
   

   Copilot in VS Code reads AGENTS.md at the root of the workspace (the chat.useAgentsMdFile setting, on by default), in the Copilot harness and in Local sessions. The AGENTS.md guide shows the section it adds; with Inwards as a uv dev dependency, add --launcher "uv run" so the section says uv run inwards check.

4. Register the MCP server in .mcp.json at the root of the project:

   .mcp.json

   {
     "mcpServers": {
       "inwards": { "type": "stdio", "command": "inwards", "args": ["mcp"] }
     }
   }
   

   VS Code starts the server in the workspace folder, so its tools see the project. This is the portable format: VS Code reads it for every session type, and Claude Code and the Copilot CLI read the same file. With uv, use "command": "uv", "args": ["run", "inwards", "mcp"]. In a trusted workspace the server starts without asking; in Restricted Mode it doesn't start. The MCP guide describes the three tools.

5. Tell the agent to read the Problems panel. VS Code's #read/problems tool gives it the diagnostics there, Inwards' included, but the agent decides when to call it. Name it in a prompt ("fix #read/problems"), or add a line to .github/copilot-instructions.md:

   .github/copilot-instructions.md

   After editing Python files, read #read/problems and fix every Inwards diagnostic (codes INW and FAPI) before you finish.
   

Check it works:

• Run MCP: List Servers from the command palette. inwards is listed as running, and Configure Tools in the chat input lists check_files, explain_rule and where_should_this_go.
• Ask the agent: "Add import shop.infrastructure.db at the top of shop/domain/order.py." The extension marks the import with INW001, and the agent, told to read the Problems panel or to run the check, removes it or introduces a port.

Hooks¶

VS Code has agent hooks in preview, but Inwards doesn't support them yet. Its hook (inwards hook claude-code) reads Claude Code's payloads and tool names. VS Code's Local harness can read hooks from Claude Code's settings files (chat.useClaudeHooks, off by default), but it ignores their matchers and names its tools differently, and the Copilot harness uses Copilot's own hook format. Don't point either at inwards hook claude-code: the config guard and the Stop gate would see tool calls they don't recognise. The Copilot CLI reads .claude/settings.json and .claude/settings.local.json too, so in a project wired with inwards init --agent claude-code it already runs that hook, and neither the guard nor the Stop gate holds there: Copilot takes the hook's exit 2 as a warning for the user, not a block. ADR-044 has what each Copilot surface offers and the planned inwards hook copilot.

Copilot cloud agent¶

The cloud agent (earlier called the coding agent) works on an issue in a GitHub Actions environment and opens a pull request. It reads AGENTS.md, .github/copilot-instructions.md and .github/instructions/*.instructions.md from the repository.

1. Add the AGENTS.md section, as in step 3 above.

2. Install Inwards in the agent's environment with .github/workflows/copilot-setup-steps.yml. Copilot runs only a job named copilot-setup-steps, and only once the file is on the default branch. This one assumes Inwards is a uv dev dependency, so AGENTS.md should say uv run inwards check (inwards init --agent agents-md --launcher "uv run"):

   .github/workflows/copilot-setup-steps.yml

   name: Copilot setup steps
   
   on:
     workflow_dispatch:
     push:
       paths: [.github/workflows/copilot-setup-steps.yml]
     pull_request:
       paths: [.github/workflows/copilot-setup-steps.yml]
   
   jobs:
     copilot-setup-steps:
       runs-on: ubuntu-latest
       permissions:
         contents: read
       steps:
         - uses: actions/checkout@v7
         - uses: astral-sh/setup-uv@v10
         - name: Install the project, Inwards included
           run: uv sync --locked
         - run: uv run inwards --version
   

   The push and pull_request triggers run the job as a normal workflow when the file changes, so a broken step shows up in the pull request that adds it. If a step fails during an agent session, Copilot skips the rest and starts anyway, without Inwards. Without uv, download the release binary as in the GitHub Actions guide and install it into a directory on the default PATH, such as /usr/local/bin (with sudo install).

3. Optionally, give the agent the MCP tools. In the repository's Settings, open Copilot, then MCP servers, and save:

   {
     "mcpServers": {
       "inwards": {
         "type": "local",
         "command": "uv",
         "args": ["run", "inwards", "mcp"],
         "tools": ["check_files", "explain_rule", "where_should_this_go"]
       }
     }
   }
   

   tools is required and lists what the agent may call without asking; all three tools only read. The server uses the Inwards that the setup steps installed. The next session's log shows them under the Start MCP Servers step. GitHub doesn't document which directory the agent starts a server in; if check_files doesn't find the project's files, ask the agent to pass absolute paths.

4. Add the GitHub Actions workflow so a violation fails the pull request. By default, workflows don't run on a pull request Copilot pushes to until someone with write access clicks Approve and run workflows; a repository admin can turn that approval off in the cloud agent's settings. When the check fails, mention @copilot in a pull request comment and ask it to fix the Inwards violations; the job log and the annotations name the rule and the fix steps.

The cloud agent also runs hooks from .github/hooks/*.json, in Copilot's own format. As in VS Code, Inwards has no adapter for them yet; ADR-044 plans one.

Limits¶

• No Stop gate. Nothing stops a Copilot turn while a violation is open. The agent runs the check because AGENTS.md asks it to, and CI fails the pull request if it didn't.
• No config guard. Copilot can edit [tool.inwards] to make a finding go away. The AGENTS.md section tells it not to; a CODEOWNERS entry for pyproject.toml makes a person review such a change.
• The Problems panel is read on request. The extension shows a violation at once, but the agent sees it only when it calls #read/problems or runs the check.

Troubleshooting¶