Setup

There are two ways to connect the Contox VS Code extension to your project: the dashboard deep link (recommended) or the manual setup wizard.

Option 1: Deep link from dashboard (recommended)

The fastest way to configure the extension:

1. Open your project on the Contox dashboard
2. Click the Connect VS Code button
3. VS Code opens and auto-configures everything

The deep link URL follows this format:

vscode://contox.contox-vscode/setup?token=xxx&teamId=xxx&projectId=xxx&hmacSecret=xxx

When the extension handles this URI, it:

1. Stores your API key in VS Code's SecretStorage
2. Stores the HMAC secret for capture event signing
3. Creates .contox.json in your workspace root
4. Writes ~/.contoxrc for CLI authentication
5. Starts the session watcher and git watcher
6. Syncs the context tree sidebar
7. Loads the brain document to .contox/memory.md
8. Injects memory into detected AI rule files

After the deep link completes, you see a notification confirming the connection.

Option 2: Setup wizard

The setup wizard is a 5-step webview panel that guides you through the entire configuration.

Open it from the Command Palette: Contox: Setup Wizard (contox.setup)

Step 1: Login

Enter your API key from the Contox dashboard (found at Settings > API Keys). The extension validates the key and stores it in VS Code's SecretStorage.

If you are already logged in from a previous session, this step is skipped automatically.

Step 2: Select organization

Choose the organization (team) you want to connect this workspace to. The wizard loads your teams from the API.

Step 3: Select project

Pick an existing project or note that you need to create one on the dashboard first. The wizard shows each project's name and context count.

When you select a project, the extension:

• Creates .contox.json with the team ID, project ID, and project name
• Fetches and stores the HMAC secret for auto-capture
• Syncs the context tree sidebar

Step 4: Configure AI tools

Select which AI coding tools you use:

You can select multiple tools. If a rule file already exists and already contains Contox instructions, it is not duplicated.

Step 5: First scan

Optionally run contox scan to index your codebase. This creates approximately 15-20 structured sub-contexts covering your project's routes, components, hooks, libraries, dependencies, and documentation.

You can skip this step and run the scan later via the CLI.

Deep link URI reference

The extension registers a URI handler at vscode://contox.contox-vscode/. Three paths are supported:

The /setup path requires at least token. If teamId and projectId are provided, the workspace is auto-configured. If only teamId is provided, a project picker is shown. If only token is provided, the setup wizard opens.

Manual setup (without wizard)

You can also configure the extension manually:

1. Run Contox: Login and enter your API key
2. Run Contox: Initialize Project to create .contox.json
3. Run Contox: Sync Contexts to populate the sidebar

What gets created

After setup completes, your workspace will contain:

your-project/
  .contox.json          # Project config
  .contox/
    memory.md           # Brain document
  .mcp.json             # Claude MCP config (if selected)
  .cursorrules          # Cursor rules (if selected)
  .windsurfrules        # Windsurf rules (if selected)
  .github/
    copilot-instructions.md  # Copilot instructions (if selected)

And in your home directory:

~/.contoxrc             # CLI auth config

Next steps

• Auto Capture -- How the git watcher captures your development activity
• Session Management -- Session polling and pipeline tracking