Install Guide - Copilot Goal System

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

Requirements

Requirement	Version	Notes
Node.js	`20.19+ or 22.12+`	Required by the Copilot SDK package.
npm	`>= 10`	Used by the installer to install production dependencies.
GitHub Copilot CLI	current	Required for CLI strict mode. Restart it after install.
Copilot CLI MCP	current	Required for MCP tool access through `~/.copilot/mcp-config.json`.
VS Code Copilot Chat	current	Required for VS Code Chat preview mode.
macOS or Linux shell	bash-compatible	The hook helper is a shell script.
jq	current	Required by the CLI hook helper to parse Copilot hook payloads.

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 CLI, MCP, and VS Code Chat support, 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.

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 CLI, MCP, and VS Code Chat support:

./install.sh --target all

Install only the MCP server config:

./install.sh --target mcp

If your Copilot CLI profile is not ~/.copilot, set COPILOT_HOME to the full profile directory before running the installer. Install only the VS Code Chat adapter:

./install.sh --target vscode-chat

After installing cli or all, restart Copilot CLI:

/skills reload
/env

Confirm the goal skill appears and the extension tools are visible. After installing only vscode-chat, reload VS Code, then select the Goal System custom agent.

What gets installed

Path	Purpose
`~/.copilot/extensions/goal-system/`	Extension package, tests, docs, hook config, and dependencies.
`~/.copilot/extensions/goal-system/bin/goalctl.mjs`	Local command fallback for goal status, open, update, and close.
`~/.copilot/extensions/goal-system/adapters/mcp/server.mjs`	Local MCP stdio server exposing goal tools.
`~/.copilot/skills/goal/SKILL.md`	Goal-mode skill used by Copilot.
`~/.copilot/hooks/goal-context.sh`	CLI lifecycle hook helper.
`~/.copilot/hooks/goal-system-vscode.json`	VS Code Chat lifecycle hook config.
`~/.copilot/agents/goal-system.agent.md`	VS Code Chat custom agent.
`~/.copilot/settings.json`	Hook entries are merged into existing settings.
`~/.copilot/mcp-config.json`	`mcpServers.goalSystem` is added or updated for Copilot CLI MCP.
`~/.copilot/copilot-instructions.md`	A short goal-system reminder is appended once.

The installer preserves existing settings. It appends missing goal hooks, leaves unrelated hooks alone, and recognizes existing goal hooks written with ~, $HOME, $COPILOT_HOME, absolute paths, or wrapper commands. If a composite user hook already runs goal-context.sh, the installer keeps that hook and does not add a duplicate direct goal hook. Empty JSON or JSONC config files are initialized as empty objects. Malformed JSON/JSONC or parseable non-object target config files are preserved as *.invalid-backup-*, replaced with a clean JSON object, and then updated so reinstall and update flows can recover from broken local config. Copilot CLI settings.json is handled as a JSONC-compatible config file. Comments and trailing commas are accepted, and comments outside the exact updated subtree are preserved while the installer updates hooks. Copilot CLI mcp-config.json is also handled as JSONC-compatible config. Existing MCP servers are preserved while mcpServers.goalSystem is added or replaced with the local stdio command. Current recommended installs use local hooks, direct tools, the MCP stdio server, and goalctl. MCP is an additional goal API surface; goalctl remains the recovery fallback when a host hides or disables tools. Config backups keep the original file permissions, and newly created config files default to owner-only permissions. Runtime updates are prepared in a temporary directory first. The installer copies the new package, runs npm ci --omit=dev --ignore-scripts, and marks runtime entrypoints executable before replacing ~/.copilot/extensions/goal-system/. If dependency installation fails, the previous runtime remains in place and config files are not changed.

Hook entries

The installer adds these hook events:

Event	Purpose
`sessionStart`	Restores active goal context at the start of a session.
`userPromptSubmitted`	Injects goal context and creates a persisted draft goal on `/goal` activation.
`preCompact`	Writes a compact goal snapshot before context compaction.
`agentStop`	Blocks a premature stop while an open goal remains active.
`subagentStart`	Gives subagents a boundary message without exposing full goal state.
`subagentStop`	Keeps subagent stop handling outside goal ownership.
`preToolUse`	Warns on stale non-goal tool drift before a tool call runs; can hard-block when `GOAL_SYSTEM_HARD_DRIFT_BLOCK=1`.
`postToolUse`	Records non-goal tool history used for drift tracking after a tool call runs.
`postToolUseFailure`	Records tool history for tool calls that fail.
`notification`	Injects compact active-goal context on agent idle or completion notifications.

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. Committed hook config files run automatically once a folder is trusted in Copilot CLI, so review any .github/hooks/*.json file in repositories you did not author before trusting them. 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. The CLI install also adds goalctl, a local command fallback:

node ~/.copilot/extensions/goal-system/bin/goalctl.mjs status --session-id "$SESSION_ID" --cwd "$PWD"

Goal tools appear as direct SDK tools in Copilot CLI. If direct tools are unavailable, hook context includes the current sessionId and cwd so goalctl can target the same persisted goal.

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

Run a local host diagnostic:

npm run doctor -- --target cli

For all local surfaces:

./install.sh --target all
npm run doctor -- --target all

For MCP only:

./install.sh --target mcp
npm run doctor -- --target mcp

Restart Copilot CLI after updating. After restarting Copilot CLI, run:

/env

Confirm the goal skill is loaded and the direct goal tools are visible. For MCP, run:

/mcp show goalSystem

Confirm Copilot CLI can start the local server and list the goal tools. 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/. Updates also clean up duplicate direct goal hook entries from older installs while preserving composite hooks that include user-managed context helpers.

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 edit ~/.copilot/mcp-config.json and remove mcpServers.goalSystem if you installed MCP support.

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.

Drift warnings keep repeating

Call goal_system_checkpoint with real progress, inspection evidence, verification results, remaining work, or blockers. If the goal tools are missing, the default guard should still allow recovery tool calls; rerun the installer to remove stale CLI preToolUse or postToolUse goal hooks from older installs. If direct goal tools are missing, use the local command fallback from the shell:

node ~/.copilot/extensions/goal-system/bin/goalctl.mjs status --session-id "<session-id-from-hook-context>" --cwd "<cwd-from-hook-context>"
node ~/.copilot/extensions/goal-system/bin/goalctl.mjs checkpoint --session-id "<session-id-from-hook-context>" --cwd "<cwd-from-hook-context>" --done "saved progress" --next "next concrete work"

Then rerun the installer, restart Copilot CLI, run npm run doctor -- --target cli, and check the goalctl self-test result.

MCP tools do not appear

Run:

/mcp show goalSystem

If the server is missing or disabled, rerun:

./install.sh --target mcp
npm run doctor -- --target mcp

The MCP config should contain mcpServers.goalSystem with type: "local", command node, and args pointing to ~/.copilot/extensions/goal-system/adapters/mcp/server.mjs.

Status reports duplicate CLI goal hooks

Run the installer again. It normalizes direct goal-context.sh entries, keeps a composite hook if one already carries the goal context, and leaves unrelated hooks in place. Restart Copilot CLI afterward because hook configuration changes load when the CLI starts.

VS Code Chat tools do not appear

Reload VS Code and select the Goal System custom agent. If the direct VS Code goal tools are still unavailable, use goalctl with the sessionId and cwd from hook context, then run Copilot Goal System: Show Status.

A stop is blocked

An open goal still exists. Follow the continuation directive: call goal_system_status, continue the next concrete remaining item, checkpoint persisted state with evidence, or call goal_system_finish when completion is proven. Use goal_system_close only for a real blocker or explicit cancellation.

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.19+ or 22.12+ and rerun ./install.sh.

​Requirements

​Preferred setup

​VS Code Marketplace

​Terminal

​What gets installed

​Hook entries

​Update

​Marketplace publish

​Uninstall

​Troubleshooting

​/goal only says the skill loaded

​Goal state does not resume after compaction

​Drift warnings keep repeating

​MCP tools do not appear

​Status reports duplicate CLI goal hooks

​VS Code Chat tools do not appear

​A stop is blocked

​npm install fails