feat: add VS Code/Copilot integration for tool-agnostic sessions (fixes #7)

.gitignore

@@ -52,6 +52,11 @@ dist/
 .context/journal-site/
 .context/journal-obsidian/
 
+# VS Code extension build artifacts
+editors/vscode/node_modules/
+editors/vscode/dist/
+editors/vscode/*.vsix
+
 # Some ideas are best kept hidden.
 ideas
 .context/.scratchpad.key

.golangci.yml

@@ -26,6 +26,10 @@ linters:
       # Test files use literal strings for clarity
       - linters: [goconst]
         path: "_test\\.go"
+      # Test files construct paths from test constants, not user input
+      - linters: [gosec]
+        text: "G304"
+        path: "_test\\.go"
 
 run:
   timeout: 5m

docs/cli-reference.md

@@ -839,9 +839,15 @@ ctx watch --dry-run
 Generate AI tool integration configuration.
 
 ```bash
-ctx hook <tool>
+ctx hook <tool> [flags]
 ```
 
+**Flags**:
+
+| Flag      | Short | Description                                                            |
+|-----------|-------|------------------------------------------------------------------------|
+| `--write` | `-w`  | Write the generated config to disk (e.g. `.github/copilot-instructions.md`) |
+
 **Supported tools**:
 
 | Tool          | Description                                  |
@@ -859,8 +865,12 @@ ctx hook <tool>
 **Example**:
 
 ```bash
+# Print hook instructions to stdout
 ctx hook cursor
 ctx hook aider
+
+# Generate and write .github/copilot-instructions.md
+ctx hook copilot --write
 ```
 
 ---

docs/first-session.md

@@ -114,7 +114,15 @@ it will fill in as you capture lessons during development.
 ## Step 4: Start an AI Session
 
 With **Claude Code** (and the ctx plugin), context loads automatically — just
-start a session and it's there. For other tools, generate a context packet:
+start a session and it's there.
+
+With **VS Code Copilot Chat** (and the
+[ctx extension](integrations.md#vs-code-chat-extension-ctx)), type
+`@ctx /agent` in chat to load your context packet, or `@ctx /status`
+to check your project context. Run `ctx hook copilot --write` once
+to generate `.github/copilot-instructions.md` for automatic context loading.
+
+For other tools, generate a context packet:
 
 ```bash
 ctx agent --budget 8000
@@ -179,6 +187,9 @@ asking you to re-explain.
 Claude Code integration (hooks + skills) is provided by the
 **ctx plugin** — see [Integrations](integrations.md#claude-code-full-integration).
 
+VS Code Copilot Chat integration is provided by the
+**ctx extension** — see [Integrations](integrations.md#vs-code-chat-extension-ctx).
+
 See [Context Files](context-files.md) for detailed documentation of each file.
 
 ## What to `.gitignore`

docs/getting-started.md

@@ -185,7 +185,15 @@ Shows context summary: files present, token estimate, and recent activity.
 ### 3. Start Using with AI
 
 With Claude Code (and the ctx plugin installed), context loads automatically
-via hooks. For other tools, paste the output of:
+via hooks.
+
+With **VS Code Copilot Chat**, install the
+[ctx extension](integrations.md#vs-code-chat-extension-ctx) and use
+`@ctx /status`, `@ctx /agent`, and other slash commands directly in chat.
+Run `ctx hook copilot --write` to generate `.github/copilot-instructions.md`
+for automatic context loading.
+
+For other tools, paste the output of:
 
 ```bash
 ctx agent --budget 8000

docs/integrations.md

@@ -340,20 +340,106 @@ ctx watch --log /tmp/aider.log
 
 ## GitHub Copilot
 
-Copilot reads open files for context. Keep context files open or reference 
-them in comments.
+GitHub Copilot integrates with `ctx` at three levels: an automated
+instructions file, a VS Code Chat extension, and manual patterns.
 
 ### Setup
 
 ```bash
-# Generate Copilot tips
-ctx hook copilot
-
 # Initialize context
-ctx init --minimal
+ctx init
+
+# Generate .github/copilot-instructions.md
+ctx hook copilot --write
+```
+
+The `--write` flag creates `.github/copilot-instructions.md`, which
+Copilot reads automatically at the start of every session. This file
+contains your project's constitution rules, current tasks, conventions,
+and architecture — giving Copilot persistent context without manual
+copy-paste.
+
+Re-run `ctx hook copilot --write` after updating your `.context/` files
+to regenerate the instructions.
+
+### VS Code Chat Extension (`@ctx`)
+
+The **ctx VS Code extension** adds a `@ctx` chat participant to
+GitHub Copilot Chat, giving you direct access to all context commands
+from within the editor.
+
+#### Installation
+
+1. Build from source (requires Node.js 18+):
+
+```bash
+cd editors/vscode
+npm install
+npm run build
+npx @vscode/vsce package
+```
+
+2. Install the `.vsix` file:
+
+```bash
+code --install-extension ctx-context-0.7.0.vsix
 ```
 
-### Usage Patterns
+3. Reload VS Code. Type `@ctx` in Copilot Chat to verify.
+
+#### Slash Commands
+
+| Command | Description |
+|---------|-------------|
+| `@ctx /init` | Initialize `.context/` directory with template files |
+| `@ctx /status` | Show context summary with token estimate |
+| `@ctx /agent` | Print AI-ready context packet |
+| `@ctx /drift` | Detect stale or invalid context |
+| `@ctx /recall` | Browse and search AI session history |
+| `@ctx /hook` | Generate AI tool integration configs |
+| `@ctx /add` | Add a task, decision, or learning |
+| `@ctx /load` | Output assembled context Markdown |
+| `@ctx /compact` | Archive completed tasks and clean up |
+| `@ctx /sync` | Reconcile context with codebase |
+
+#### Usage Examples
+
+```text
+@ctx /init
+@ctx /status
+@ctx /add task Implement user authentication
+@ctx /drift
+@ctx /hook copilot
+@ctx /recall
+```
+
+Typing `@ctx` without a command shows help with all available commands.
+The extension also supports natural language — asking `@ctx` about
+"status" or "drift" routes to the correct command automatically.
+
+#### Configuration
+
+| Setting | Default | Description |
+|---------|---------|-------------|
+| `ctx.executablePath` | `ctx` | Path to the ctx binary. Set this if `ctx` is not in your `PATH`. |
+
+#### Follow-Up Suggestions
+
+After each command, the extension suggests relevant next steps. For
+example, after `/init` it suggests `/status` and `/hook`; after
+`/drift` it suggests `/sync`.
+
+### Session Persistence
+
+`ctx init` creates a `.context/sessions/` directory for storing
+session data from non-Claude tools. The Markdown session parser scans
+this directory during `ctx recall`, enabling session history for
+Copilot and other tools.
+
+### Manual Patterns
+
+These patterns work without the extension, using Copilot's built-in
+file awareness:
 
 **Pattern 1: Keep context files open**
 

editors/vscode/.vscodeignore

@@ -0,0 +1,9 @@
+.vscode-test/
+node_modules/
+src/
+tsconfig.json
+vitest.config.ts
+package-lock.json
+**/*.map
+**/*.ts
+!dist/**

editors/vscode/README.md

@@ -0,0 +1,44 @@
+# ctx — VS Code Chat Extension
+
+A VS Code Chat Participant that brings [ctx](https://ctx.ist) — persistent project context for AI coding sessions — directly into GitHub Copilot Chat.
+
+## Usage
+
+Type `@ctx` in the VS Code Chat view, then use slash commands:
+
+| Command | Description |
+|---------|-------------|
+| `@ctx /init` | Initialize a `.context/` directory with template files |
+| `@ctx /status` | Show context summary with token estimate |
+| `@ctx /agent` | Print AI-ready context packet |
+| `@ctx /drift` | Detect stale or invalid context |
+| `@ctx /recall` | Browse and search AI session history |
+| `@ctx /hook` | Generate AI tool integration configs |
+| `@ctx /add` | Add a task, decision, or learning |
+| `@ctx /load` | Output assembled context Markdown |
+| `@ctx /compact` | Archive completed tasks and clean up |
+| `@ctx /sync` | Reconcile context with codebase |
+
+## Prerequisites
+
+- [ctx](https://ctx.ist) CLI installed and available on PATH (or configure `ctx.executablePath`)
+- VS Code 1.93+ with GitHub Copilot Chat
+
+## Configuration
+
+| Setting | Default | Description |
+|---------|---------|-------------|
+| `ctx.executablePath` | `ctx` | Path to the ctx executable |
+
+## Development
+
+```bash
+cd editors/vscode
+npm install
+npm run watch   # Watch mode
+npm run build   # Production build
+```
+
+## License
+
+Apache-2.0