Install Copilot Goal System into your local GitHub Copilot profiles. The installer preserves existing settings and writes backups before it changes config.

​
Requirements

RequirementVersionNotes
Node.js>= 20Required by the Copilot SDK package.
npm>= 10Used by the installer to install production dependencies.
GitHub Copilot CLIcurrentRequired for CLI strict mode. Restart it after install.
VS Code Copilot ChatcurrentRequired for VS Code Chat preview mode.
macOS or Linux shellbash-compatibleThe hook helper is a shell script.

​
Preferred setup

​
VS Code Marketplace

Install the extension: 
gabrimatic.copilot-goal-system
Then run this Command Palette command: 
Copilot Goal System: Install into Copilot CLI
For both adapters, run: 
Copilot Goal System: Install Recommended Setup
The VS Code extension uses your current OS account’s home directory by default. Set copilotGoalSystem.homeOverride when you need to install into a different local profile. Set copilotGoalSystem.vscodeMcpConfigPathOverride only if your VS Code MCP config lives outside the detected profile path.

​
Terminal

Clone with SSH: 
git clone git@github.com:gabrimatic/copilot-goal-system.git
cd copilot-goal-system
./install.sh
Clone with HTTPS: 
git clone https://github.com/gabrimatic/copilot-goal-system.git
cd copilot-goal-system
./install.sh
Install both adapters: 
./install.sh --target all
Install only the VS Code Chat adapter: 
./install.sh --target vscode-chat
Restart Copilot CLI: 
/skills reload
/env

​
What gets installed

PathPurpose
~/.copilot/extensions/goal-system/Extension package, tests, docs, hook config, and dependencies.
~/.copilot/skills/goal/SKILL.mdGoal-mode skill used by Copilot.
~/.copilot/hooks/goal-context.shCLI lifecycle hook helper.
~/.copilot/hooks/goal-system-vscode.jsonVS Code Chat lifecycle hook config.
~/.copilot/agents/goal-system.agent.mdVS Code Chat custom agent.
VS Code profile mcp.jsongoalSystem stdio MCP server config.
~/.copilot/settings.jsonHook entries are merged into existing settings.
~/.copilot/copilot-instructions.mdA short goal-system reminder is appended once.
The installer preserves existing settings. It appends missing goal hooks and leaves unrelated hooks alone. Empty JSON config files are initialized as empty objects; malformed non-empty JSON is refused so existing data is not overwritten.

​
Hook entries

The installer adds these hook events: 
sessionStart
userPromptSubmitted
preCompact
agentStop
subagentStart
subagentStop
postToolUseFailure
notification
Repository-level hook config is optional. Copy .github/hooks/goal-system.json into a repository when you want the hook setup committed with that project. The VS Code Chat adapter adds these hook events: 
SessionStart
UserPromptSubmit
PreToolUse
PostToolUse
PreCompact
SubagentStart
SubagentStop
Stop
UserPromptSubmit is required for VS Code Chat to persist a draft goal immediately when a prompt starts /goal, inject active-goal context on each prompt, and load one unambiguous same-directory goal on explicit continuation.

​
Update

From VS Code, update the extension through the Marketplace. The extension checks whether the local runtime in ~/.copilot/extensions/goal-system/ is older than the bundled version and prompts you to update stale local files. You can also run: 
Copilot Goal System: Install Recommended Setup
From a cloned repository: 
cd copilot-goal-system
git pull
npm ci
npm run verify
./install.sh
For both adapters: 
./install.sh --target all
Restart Copilot CLI after updating. Updates replace the installed runtime snapshot instead of overlaying files, so files removed from newer releases do not remain active in ~/.copilot/extensions/goal-system/.

​
Marketplace publish

GitHub Actions publishes Marketplace releases when a v* tag is pushed. The workflow requires a repository secret named VSCE_PAT. Create the token in Azure DevOps with Marketplace publish permission, then store it: 
gh secret set VSCE_PAT --repo gabrimatic/copilot-goal-system
After the secret exists, pushing a release tag packages from the repository source, runs verification, and publishes the VS Code extension: 
git tag vX.Y.Z
git push origin vX.Y.Z
For a package-only dry run, run the Publish VS Code Extension workflow manually with publish=false.

​
Uninstall

Remove the installed files: 
rm -rf ~/.copilot/extensions/goal-system
rm -rf ~/.copilot/skills/goal
rm -f ~/.copilot/agents/goal-system.agent.md
rm -f ~/.copilot/hooks/goal-context.sh
rm -f ~/.copilot/hooks/goal-system-vscode.json
Then edit ~/.copilot/settings.json and remove hook entries whose bash value is: 
$HOME/.copilot/hooks/goal-context.sh
Also remove the marked snippet in ~/.copilot/copilot-instructions.md: 
<!-- copilot-goal-system snippet start -->
...
<!-- copilot-goal-system snippet end -->
Then remove the goalSystem entry from the VS Code profile mcp.json.

​
Troubleshooting

​
/goal only says the skill loaded

Run: 
/skills reload
/env
Confirm the goal skill appears and the extension tools are visible. Restart Copilot CLI if the extension was installed while a session was already running.

​
Goal state does not resume after compaction

Check state files: 
find ~/.copilot/session-state -path '*goal*' -maxdepth 5 -type f | sort
Run goal_system_status inside Copilot before continuing. If no state exists, start a new goal and inspect before acting.

​
Tool calls get denied

The drift guard is working. Call goal_system_update with real progress, inspection evidence, verification results, remaining work, or blockers.

​
VS Code Chat tools do not appear

Run: 
MCP: Reset Cached Tools
Then reload VS Code. Confirm the goalSystem MCP server appears under MCP: List Servers.

​
A stop is blocked

An open goal still exists. Follow the continuation directive: call goal_system_status, continue the next concrete remaining item, update persisted state with evidence, or call goal_system_close as complete, blocked, or cancelled with evidence.

​
npm install fails

Run manually: 
cd ~/.copilot/extensions/goal-system
npm ci --omit=dev --ignore-scripts
If Node is too old, install Node.js >= 20 and rerun ./install.sh.