The VS Code Copilot Chat adapter brings persisted goal mode into VS Code through a custom agent, lifecycle hooks, and a local MCP server. This adapter is preview because VS Code agent hooks and agent plugins are Preview surfaces. The Copilot CLI adapter remains the stable strict mode.

​
Requirements

RequirementNotes
VS Code with Copilot ChatAgent mode must be available.
Node.js >= 20Runs the hook runner and MCP server.
MCP accessOrganizations can disable MCP.
Hook accessOrganizations can disable agent hooks.

​
Install

From VS Code Marketplace, run: 
Copilot Goal System: Install Recommended Setup
From a cloned repository, run: 
./install.sh --target vscode-chat
Install both adapters: 
./install.sh --target all
After install, reload VS Code or run: 
MCP: Reset Cached Tools
Then select the Goal System custom agent in Copilot Chat. After Marketplace extension updates, VS Code compares the bundled runtime version with the local files in ~/.copilot/extensions/goal-system/. If local files are stale, the status bar changes to Goal Update and VS Code prompts you to update them. Updating local files replaces the installed runtime snapshot, so stale files from older releases do not keep running.

​
Installed files

PathPurpose
~/.copilot/extensions/goal-system/Shared package, core, adapters, tests, docs, and dependencies.
~/.copilot/agents/goal-system.agent.mdVS Code custom agent instructions.
~/.copilot/hooks/goal-system-vscode.jsonVS Code hook config with PascalCase lifecycle events.
VS Code profile mcp.jsonAdds the goalSystem stdio MCP server.
~/.copilot/session-state/goal-system/Shared persisted goal state.
The installer writes backups before changing an existing MCP config, hook config, or custom agent file.

​
Enforcement

The VS Code Chat adapter uses official VS Code hook events:
HookBehavior
SessionStartInjects the current sessionId, cwd, and active goal context.
UserPromptSubmitCreates a persisted draft goal for explicit /goal activation, injects active-goal context, and loads one unambiguous same-directory goal on explicit continuation.
PreToolUseWarns and then denies non-goal tools after repeated goal-state drift.
PostToolUseRecords non-goal tool history into the persisted goal.
PreCompactWrites a compact snapshot before conversation compaction.
SubagentStartGives subagents a boundary message without exposing goal state.
SubagentStopLets subagents finish without taking goal ownership.
StopBlocks premature completion while an active goal remains open.
Goal state remains isolated by sessionId and cwd. Multiple same-directory sessions do not silently merge. If the same goal has been resumed into another session, same-directory continuation treats those duplicate records as one goal and picks the newest copy. Renamed, merged, duplicate, superseded, and clearer-worded discovered issues must be recorded as evidence-backed issueResolutions. They do not disappear from completion checks just because the wording changed.

​
MCP Tools

The local MCP server exposes: 
goal_system_status
goal_system_open
goal_system_update
goal_system_close
All tools require the sessionId and cwd that the hook injects into the chat context. This keeps VS Code Chat sessions isolated even when several sessions share one workspace.

​
Limits

  • VS Code hooks are Preview and can change.
  • Organizations can disable hooks or MCP.
  • The adapter cannot force goal behavior if you do not select the Goal System agent and Copilot ignores available MCP tools.
  • Hook output depends on VS Code honoring the documented lifecycle events.
With those surfaces available, VS Code Chat gets the same core persistence, drift control, subagent boundary, and proof-based completion rules as the CLI adapter.

​
Troubleshooting

​
Goal tools do not appear

Run: 
MCP: Reset Cached Tools
Then reload VS Code. If tools still do not appear, run: 
MCP: List Servers
Confirm the goalSystem server is present and starts without errors.

​
Hooks do not run

Open the GitHub Copilot Chat Hooks output channel in VS Code. If no goal hook runs, check:
  • ~/.copilot/hooks/goal-system-vscode.json
  • VS Code setting chat.hookFilesLocations
  • organization policy for agent hooks

​
Stop is blocked

An active goal is still open. The stop hook returns a hard continuation directive: reload goal_system_status, continue the next concrete remaining item, update persisted state with evidence, and call goal_system_close only as complete, blocked, or cancelled with exact evidence.