Installing Hopsule for VS Code

Introduction

Hopsule for VS Code serves as the essential bridge between your team's organizational judgment and the active development environment. By integrating the decision and memory layer directly into your IDE, this extension ensures that every line of code respects the accepted decisions and context preserved within your team's memory, transforming enforcement from a system of control into a practice of remembrance.

This article provides an exhaustive guide to installing, configuring, and mastering Hopsule for VS Code. Whether you are using the standard Visual Studio Code or the AI-native Cursor editor, these instructions will help you establish a seamless connection to the Hopsule Dashboard and begin leveraging your team's collective authority within your local workflow.

Prerequisites

Before initiating the installation of Hopsule for VS Code, ensure that the following requirements are met to facilitate a successful integration:

• Active Hopsule Account: You must have an established account and be a member of at least one organization within the Hopsule Dashboard.

• Hopsule Dashboard Access: Ensure you can log in to the Hopsule Dashboard to generate the necessary Personal Access Tokens (PAT) for authentication.

• Supported IDE: A current installation of Visual Studio Code (version 1.80 or higher) or the Cursor editor.

• Internet Connectivity: A stable connection is required for the initial synchronization of Decisions, Memories, and Context Packs, though the extension is designed for local processing of code logic.

• Project Context: At least one active Context Pack (Capsule) should be configured in your Hopsule Dashboard project to see enforcement in action.

Installation and Setup

The setup process for Hopsule for VS Code is designed to be straightforward, prioritizing security and data sovereignty from the first step. Follow these detailed procedures to activate the extension.

Step 1: Installing the Extension

1. Open Visual Studio Code or Cursor.

2. Navigate to the Extensions view by clicking on the Extensions icon in the Activity Bar on the side of the IDE or by pressing Ctrl+Shift+X (Windows/Linux) or Cmd+Shift+X (macOS).

3. In the search bar, type Hopsule.

4. Locate the official Hopsule for VS Code extension and click the Install button.

5. Once the installation is complete, you will see the Hopsule "H" icon appear in your Activity Bar.

Step 2: Generating an Authentication Token

Hopsule uses secure tokens to link your IDE to your organizational memory without requiring constant password re-entry. To generate a token:

1. Log in to the Hopsule Dashboard via your web browser.

2. Navigate to the Settings section using the primary navigation menu.

3. Select the Personal Access Tokens tab.

4. Click the Generate New Token button.

5. Provide a descriptive name for the token (e.g., "Work Laptop VS Code").

6. Set an expiration period according to your organization's security governance policies.

7. Click Generate and immediately copy the token. Note: For security reasons, this token will never be displayed again.

Step 3: Authenticating in the IDE

1. Return to your IDE and open the Command Palette by pressing Ctrl+Shift+P or Cmd+Shift+P.

2. Type Hopsule: Login and press Enter.

3. Paste the Personal Access Token you copied from the Hopsule Dashboard into the input field and press Enter.

4. A notification will appear in the bottom-right corner confirming "Hopsule: Successfully authenticated."

5. The Hopsule icon in the Activity Bar will now show an "Active" status, indicating that your local environment is synchronized with your team's memory system.

Exploring the Hopsule Interface

Once authenticated, Hopsule for VS Code provides several specialized views to help you navigate your team's decisions and context without leaving your code.

The Hopsule Sidebar

Clicking the Hopsule icon in the Activity Bar opens the primary sidebar, which contains three critical tree views:

• Decisions Tree: Displays all Accepted decisions relevant to your current project. You can expand each decision to view its full text, tags, and version history.

• Context Packs (Capsules): Shows the active capsules currently influencing your workspace. You can see which memories are bundled within each capsule and their lifecycle status (Draft, Active, or Frozen).

• Conflicts & Contradictions: A real-time list of every instance where your current code contradicts an accepted decision. Clicking a conflict will take you directly to the file and line number where the enforcement warning was triggered.

Inline Enforcement and Warnings

The core power of Hopsule for VS Code lies in its ability to surface organizational judgment exactly where it is needed. When you open a source file, the extension performs the following actions:

1. Context Identification: It identifies which Context Packs apply to the specific file and directory based on the project structure defined in the Hopsule Dashboard.

2. Local Analysis: The extension analyzes the file content locally. Crucially: No source code is ever transmitted to Hopsule servers. The analysis happens entirely on your machine.

3. Decision Matching: It compares the code logic and patterns against the Accepted decisions in your capsules.

4. Visual Indicators: If a contradiction is detected, Hopsule highlights the code with a subtle warning underline. Hovering over the highlighted code will reveal a "Hopsule Enforcement" tooltip.

The Hopper Assistant in VS Code

Hopper, the advisory AI assistant, is accessible directly within the IDE. You can invoke Hopper to explain the reasoning behind a specific enforcement warning. By right-clicking on a highlighted conflict and selecting Ask Hopper, the assistant will provide context from the linked Memories to explain why the decision was made and suggest how to bring the code into alignment with organizational governance.

Decision Enforcement Workflow

Governance is not about rigid control; it is about remembering why certain paths were chosen. Hopsule for VS Code facilitates this through a structured workflow for handling contradictions.

Viewing Decision Details

When you encounter an enforcement warning, you can click the View Decision link in the tooltip. This opens a read-only panel within the IDE displaying the full decision record from the Hopsule Dashboard, including the original reasoning, the date of acceptance, and the authority who approved it. This ensures you have the full context before making changes.

Acknowledging and Overriding

There are rare cases where a decision must be intentionally bypassed for a specific technical reason. Hopsule allows for "Intentional Overrides" to ensure that these deviations are documented rather than forgotten.

1. Click the Quick Fix lightbulb next to the enforcement warning.

2. Select Hopsule: Acknowledge and Override.

3. You will be prompted to provide a brief justification for the override.

4. This justification is appended as a new Memory entry linked to the decision, ensuring full traceability for future audits or team reviews.

5. The warning will then be suppressed for that specific code block.

Configuration and Settings

You can fine-tune the behavior of Hopsule for VS Code to match your team's workflow. To access these settings, go to File > Preferences > Settings (or Code > Settings on macOS) and search for "Hopsule".

Sync Frequency

By default, the extension synchronizes with the Hopsule Dashboard every 15 minutes. You can adjust this interval to be more frequent (e.g., 5 minutes) or less frequent (e.g., 60 minutes). Note that you can always trigger a manual sync by using the Hopsule: Sync Now command in the Command Palette.

Enforcement Sensitivity

This setting controls how strictly the extension flags potential contradictions.

• Strict: Flags any code that might potentially conflict with a decision.

• Balanced (Default): Flags clear contradictions while minimizing false positives.

• Advisory: Only shows highlights for the most critical governance decisions.

Local Processing and Privacy

Hopsule for VS Code is designed with a "Privacy First" architecture. All code analysis is performed locally using the Hopsule engine. The extension only communicates with the Hopsule API to fetch decision metadata and memory entries. No source code, variable names, or proprietary logic is ever uploaded to Hopsule's infrastructure.

Tips and Best Practices

To maximize the value of Hopsule for VS Code, consider the following strategies:

• Use Solo Mode for Personal Governance: Even if you are not part of a large team, use Hopsule to preserve your own architectural decisions. This prevents "context drift" in long-term personal projects.

• Leverage the Knowledge Graph: Use the Knowledge Graph (also known as the Brain) in the Hopsule Dashboard to visualize how your decisions are linked before you start coding. This mental map makes the IDE warnings much more intuitive.

• Keep Decisions Atomic: When drafting decisions in the Dashboard, keep them focused. Atomic decisions are easier for the Hopsule IDE extension to detect and enforce accurately.

• Review Memories Frequently: When Hopper suggests a change in the IDE, take a moment to read the linked Memories. Understanding the history of a decision is the best way to prevent future technical debt.

• Freeze Capsules for Stability: For legacy projects, use "Frozen" Context Packs. This ensures that the IDE extension enforces a specific point-in-time set of decisions, preventing modern standards from causing unnecessary noise in older codebases.

Troubleshooting

If you encounter issues while using Hopsule for VS Code, refer to the following table for common resolutions.

Related Articles

• Creating and Managing Context Packs: Learn how to bundle decisions and memories into portable capsules for your team.

• The Hopsule CLI: Discover how to manage your team's memory system directly from the terminal and within CI/CD pipelines.

• Decision Lifecycles: A guide to moving decisions from Draft to Accepted and eventually to Deprecated status.