GitHub Copilot CLI

Make a repository follow an instruction in GitHub Copilot CLI and the Copilot cloud agent: one command writes the hooks, and a new version arrives after the next tool call. The same setup for other tools, and how each one takes a new version, is on Other coding agents.

At a glance

How it followshooks
A new version arrivesafter the next tool call
Set upone command
Checked againstCopilot CLI 1.0.114, from its documentation
SystemsmacOS, Linux and Windows: each hook has a bash and a powershell command

What you need: Node.js 20.19 or later, the instruction.md package (npm i -g instruction.md, 0.11.0 or later) and @instruction.md/agents 0.4.1 or later, which instruction agents … runs. Every instruction agents … command also runs, without installing anything, as npx -y @instruction.md/agents …, and every instruction … command as npx -y instruction.md ….

Set up

In your project's folder, signed in (instruction login), run:

Shell
instruction agents follow instruction://acme/support-agent@stable --host copilot --write

It writes, merged into what is already there:

  • .instruction/follow.json: the instruction the project follows. Commit it.
  • .instruction/.gitignore: keeps the fetched copy (current.md), state.json and given/ out of git.
  • .github/hooks/instruction-md.json: the hooks. Commit it.
.github/hooks/instruction-md.json
{
  "version": 1,
  "hooks": {
    "sessionStart": [
      {
        "type": "command",
        "bash": "npx -y @instruction.md/agents hook copilot --event sessionStart",
        "powershell": "npx -y @instruction.md/agents hook copilot --event sessionStart",
        "timeoutSec": 10
      }
    ],
    "userPromptSubmitted": [
      {
        "type": "command",
        "bash": "npx -y @instruction.md/agents hook copilot --event userPromptSubmitted",
        "powershell": "npx -y @instruction.md/agents hook copilot --event userPromptSubmitted",
        "timeoutSec": 5
      }
    ],
    "postToolUse": [
      {
        "type": "command",
        "bash": "npx -y @instruction.md/agents hook copilot --event postToolUse",
        "powershell": "npx -y @instruction.md/agents hook copilot --event postToolUse",
        "timeoutSec": 5
      }
    ],
    "preCompact": [
      {
        "type": "command",
        "bash": "npx -y @instruction.md/agents hook copilot --event preCompact",
        "powershell": "npx -y @instruction.md/agents hook copilot --event preCompact",
        "timeoutSec": 5
      }
    ]
  }
}

Copilot CLI and the Copilot cloud agent run the repository's .github/hooks; commit it.

What happens

Copilot CLI and the Copilot cloud agent both run a repository's .github/hooks/, so commit the file. A session gets the instruction's whole text when it starts (sessionStart), and a new version after the next tool call (postToolUse). Before Copilot compacts a session (preCompact), the hook forgets what it holds, so the next event gives the whole text again.

Copilot takes at most 10 KB from all hooks together after a tool call, so the hook keeps its text there under 7,000 characters. A longer instruction is cut, with a line telling the model to read the rest in .instruction/current.md.

The MCP server

Copilot CLI reaches instruction.md through the instruction command's stdio server. instruction connect --host copilot <uri> prints:

~/.copilot/mcp-config.json
// ~/.copilot/mcp-config.json (or /mcp add in a session) — Copilot CLI reaches instruction.md through this CLI's stdio server
{
  "mcpServers": {
    "instruction-md": {
      "type": "local",
      "command": "npx",
      "args": [
        "-y",
        "instruction.md",
        "mcp",
        "--follow",
        "instruction://acme/support-agent@stable",
        "--url",
        "https://instruction.md/mcp"
      ],
      "tools": [
        "*"
      ]
    }
  }
}
// sign the bridge in once: npx -y instruction.md login
// to give every session this instruction, and a new version as it is released: npx -y @instruction.md/agents connect --host copilot instruction://acme/support-agent@stable --with-hooks --write
// (.github/hooks/instruction-md.json — the Copilot cloud agent runs it too)

The plugin instead

Copilot CLI also reads instruction.md's plugin, instruction-md/ at github.com/instruction-md/plugins. It finds the hooks at com.github.copilot/hooks/hooks.json, in Copilot's own format, and the MCP server in mcp.json. With the plugin, a project still needs its .instruction/follow.json; use the plugin or the project's hooks, not both.

Caveats and what isn't verified

  • The hook also answers at userPromptSubmitted. Copilot's hook reference says what a hook adds there is dropped, and its changelog says it reaches the model. So a new version at your next prompt is not verified; after the next tool call is.
  • Copilot CLI also runs a project's .claude/settings.json hooks. Where both are set up, a session still gets each version once.

Check it worked

Run the hook by hand, as the tool would at that event. It prints what the tool receives: the instruction's whole text the first time, and nothing when you run it again right away, because a session gets each version once.

Shell
echo '{}' | npx -y @instruction.md/agents hook copilot --event sessionStart --dir .

Then start a new session and ask which instructions it follows. Once a session has read it, .instruction/current.md holds the copy the hooks keep, and the instruction's Agents card counts the follower under this tool.

Stop following

  • Remove the entries that run @instruction.md/agents hook copilot from .github/hooks/instruction-md.json.
  • Delete .instruction/follow.json, or the whole .instruction/ folder.

If it doesn't work

What you seeWhyWhat to do
Running the hook by hand prints nothingNo .instruction/follow.json in the folder or above it, up to the repository's root; or it gave this version moments agoRun the setup in the project's folder, or pass --dir. A version the session already has isn't given again: nothing is wrong
instruction.md: couldn't read …; this session goes on without itOffline, not signed in, or the address is wrong, and there is no copy yetinstruction login, then check the address in .instruction/follow.json
instruction.md: a newer version of … is held (…)The new version's signature doesn't check out, and the follow file asks for oneNothing to do on this machine: the session keeps the version it has. See How following works
A private instruction isn't readThe command isn't signed ininstruction login (--device on a machine without a browser)
Still stuckAsk us

Last checked against the product:

Was this page helpful? Report a problem