Skip to content
NatamuxNatamux

GitHub Copilot CLI

Natamux starts Copilot CLI with a hook file in the task’s worktree.

Before you start

Section titled “Before you start”

Install Copilot CLI and sign in. Follow the GitHub documentation for the CLI. Check that copilot runs in your terminal.

What Natamux runs

Section titled “What Natamux runs”
Program copilot
Command line copilot --allow-all-tools [extra args] -i '<prompt>'
Permission flag --allow-all-tools, left out with "agents": { "permissionMode": "ask" } in .natamux.json
Change the program NATAMUX_COPILOT_COMMAND
Add arguments NATAMUX_COPILOT_ARGS

For example, to pick the model:

Terminal window
export NATAMUX_COPILOT_ARGS="--model gpt-5"

Start the agent from the dashboard, or:

Terminal window
natamux agent start T-42 --agent copilot

How hooks are added

Section titled “How hooks are added”

Natamux writes .github/hooks/natamux.json in the task’s worktree and adds it to the repository’s .git/info/exclude, so git ignores it. Copilot does not say which event a hook is for, so each hook command names it, for example natamux hook copilot agentStop.

If a file of your own with that name exists, Natamux leaves it alone. The agent then runs without Natamux’s hooks, and the dashboard follows its terminal only.

Natamux also adds the worktree to trustedFolders in ~/.copilot/config.json, so Copilot does not ask whether you trust it. See Folder trust.

Events and states

Section titled “Events and states”
Hook event Meaning Task state
userPromptSubmitted A prompt was sent running
preToolUse, postToolUse, postToolUseFailure The agent works no change
notification with type permission_prompt or elicitation_dialog Copilot asks for permission, or asks you a question needs input
agentStop The turn ended needs input
errorOccurred with recoverable: false An error ended the work failed

A recoverable error is ignored. Other notifications, such as shell_completed, change nothing. Natamux does not use permissionRequest: Copilot sends it before it checks its permission rules, so also for each tool that --allow-all-tools lets run at once.

Skills

Section titled “Skills”
Where Folder Shown as
Project .github/skills, .claude/skills or .agents/skills, then <name>/SKILL.md Project
You ~/.copilot/skills or ~/.agents/skills, then <name>/SKILL.md Only on this machine
  • Natamux does not read Copilot plugin folders.
  • {skill:<name>} becomes /<name> when Copilot CLI has the skill. Otherwise it becomes the path of a SKILL.md of that name, or the <name> skill when none exists.

Source: Add skills to Copilot CLI, checked 2026-10-11.

For the rules in general, see Skills in a prompt. Agents change quickly: check the vendor docs if a skill is not found.

Tested

Section titled “Tested”

A real Copilot CLI 1.0.94 session.

Limits

Section titled “Limits”
  • Copilot runs in its own full screen, so its output does not go into the terminal history. Its scrollbar shows as a light line at the right edge. Copilot CLI (checked on 1.0.98) has no flag or setting to turn the full screen off.
  • Copilot may ring the terminal bell when it starts. Natamux ignores a bell in the first 15 seconds after launch.
  • Copilot’s hooks may be off until its folder is trusted. Without ~/.copilot/config.json (Copilot never ran), Natamux cannot trust the folder, and Copilot asks once. Until then, the terminal bell moves a running task to needs input.