Installation

Contox has three client-side components. Install whichever ones match your workflow -- you can use one, two, or all three.

CLI installation

The CLI is the universal interface that works with any AI coding tool. It handles authentication, project initialization, scanning, memory loading, and session saving.

Install via npm

npm install -g contox-cli

Verify installation

contox --version

You should see the version number printed. If you get a "command not found" error, ensure your global npm bin directory is in your system PATH.

Authenticate

After installation, store your API key to authenticate all future commands:

contox login -k <your-api-key>
contox whoami  # Verify credentials

Available commands

After installation, you have access to the full command set:

# Project setup
contox init                    # Initialize project

# Core workflow
contox memory                  # Load project memory
contox save "summary"          # Save session work
contox scan                    # Scan codebase

# Operations
contox status                  # Show project status
contox oncall                  # Operational summary
contox context "task"          # Build focused context pack

See the CLI reference for all 17 commands.

MCP Server installation

The MCP (Model Context Protocol) server provides deep integration with Claude Code and other MCP-compatible tools. It exposes Contox tools directly in the AI's tool palette, enabling automatic memory loading, saving, scanning, and more.

Install via npm

npm install -g @contox/mcp-server

Verify installation

contox-mcp --version

Configure for Claude Code

Claude Code can be configured at the project level via a .mcp.json file in your project root, or globally via Claude Desktop's configuration.

Project-level configuration (.mcp.json):

{
  "mcpServers": {
    "contox": {
      "command": "contox-mcp",
      "env": {
        "CONTOX_API_KEY": "your-api-key",
        "CONTOX_TEAM_ID": "your-team-id",
        "CONTOX_PROJECT_ID": "your-project-id",
        "CONTOX_HMAC_SECRET": "your-hmac-secret"
      }
    }
  }
}

Global configuration (claude_desktop_config.json):

On macOS, this file is located at ~/Library/Application Support/Claude/claude_desktop_config.json. On Windows, it is at %APPDATA%\Claude\claude_desktop_config.json.

{
  "mcpServers": {
    "contox": {
      "command": "contox-mcp",
      "env": {
        "CONTOX_API_KEY": "your-api-key",
        "CONTOX_TEAM_ID": "your-team-id"
      }
    }
  }
}

Environment variables

The MCP server accepts the following environment variables:

Available MCP tools

Once configured, Claude Code gains access to 21 Contox tools including:

• contox_get_memory -- Load project brain at session start
• contox_save_session -- Save session work at session end
• contox_scan -- Scan codebase and push sub-contexts
• contox_search -- Search across project memory
• contox_context_pack -- Build focused context for a specific task
• contox_git_digest -- Read git commits for enrichment
• contox_hygiene -- Run memory cleanup analysis

See the MCP reference for the full tool list.

VS Code Extension

The VS Code extension provides automatic session capture directly in your editor -- no manual commands needed.

Install from Marketplace

1. Open VS Code
2. Go to the Extensions panel (Ctrl+Shift+X / Cmd+Shift+X)
3. Search for Contox
4. Click Install on the contox.contox-vscode extension

Alternatively, install from the command line:

code --install-extension contox.contox-vscode

Connect to your project

After installing, connect the extension to your Contox project:

1. Open the Command Palette (Ctrl+Shift+P / Cmd+Shift+P)
2. Run Contox: Setup to launch the connection wizard
3. Enter your API key and select your project

Extension features

The VS Code extension provides:

• Automatic session tracking -- Sessions are created and managed automatically
• Git change monitoring -- Git commits are captured as session events
• Session lifecycle management -- Auto-creates new sessions when the dashboard closes the active one
• Context tree sidebar -- Browse your project's brain hierarchy directly in VS Code

See the VS Code reference for all features and settings.

Dashboard setup page

The dashboard includes a dedicated Setup & Integrations page that provides:

• CLI install commands -- Copy-paste ready commands for your operating system
• VS Code connection -- One-click deep link to connect the extension
• IDE integration guides -- Quick setup for Cursor, Copilot, Windsurf, and other tools
• API key access -- Quick link to create or view your API keys

This page is accessible from the sidebar under Setup or via the onboarding wizard after sign-up.

Troubleshooting

CLI: "command not found" after install

Ensure your npm global bin directory is in your PATH:

npm config get prefix

The bin subdirectory of that prefix should be in your PATH. For example, if the prefix is /usr/local, then /usr/local/bin should be in your PATH.

MCP Server: Claude Code does not show Contox tools

1. Verify the MCP server is installed: contox-mcp --version
2. Check that your claude_desktop_config.json or .mcp.json is valid JSON
3. Ensure all required environment variables are set
4. Restart Claude Code after configuration changes

MCP Server: Authentication errors

1. Verify your API key is valid: contox whoami
2. Check that CONTOX_API_KEY in your MCP config matches the key stored in ~/.contoxrc
3. Ensure your team ID and project ID are correct
4. Verify the key has not been deleted in Settings > API Keys

Next steps

With your tools installed, continue to Authentication to understand how API keys, HMAC signing, and security work in Contox.