Hopsule for VS Code: Installation and Setup

Introduction to Hopsule for VS Code

Hopsule for VS Code is the primary enforcement layer of the Hopsule ecosystem. While the Hopsule Dashboard serves as the central authority for defining governance and Hopper assists in drafting organizational judgment, the IDE extension is where those decisions meet the reality of production code. It is designed to ensure that the collective memory of your engineering organization is never more than a keystroke away, transforming passive documentation into active, enforceable constraints.

By integrating directly into your development environment—whether you use VS Code or Cursor—Hopsule provides real-time awareness of the decisions, memories, and Context Packs that govern your specific project. This eliminates the cognitive load of searching for historical reasoning or architectural mandates. Instead, Hopsule surfaces the right context at the right time, ensuring that every line of code aligns with the established authority of the team. Enforcement, in the Hopsule philosophy, is not about control; it is about remembrance.

Installation Procedures

The installation of Hopsule for VS Code is a streamlined process intended to get your team into a state of context-awareness with minimal friction. The extension is compatible with both the standard Visual Studio Code distribution and the Cursor AI code editor, ensuring that AI-forward teams can maintain decision integrity regardless of their preferred toolset.

Installing via the Extensions Marketplace

1. Open your IDE (VS Code or Cursor) and navigate to the Extensions view by clicking on the square icon in the Activity Bar on the side of the editor or by pressing Ctrl+Shift+X (Windows/Linux) or Cmd+Shift+X (macOS).

2. In the search bar, type Hopsule. Look for the official extension published by the Hopsule team.

3. Click the Install button. Once the installation is complete, you will see the Hopsule icon (the Hopper logo) appear in your Activity Bar.

4. Upon installation, a notification will appear in the bottom right corner of the editor, inviting you to begin the first-time setup wizard.

Installing via the Command Line

For developers who prefer a terminal-centric workflow or for organizations automating developer environment setups, the extension can be installed using the code CLI utility. Run the following command in your terminal:

code --install-extension hopsule.hopsule-vscode

code --install-extension hopsule.hopsule-vscode

code --install-extension hopsule.hopsule-vscode

code --install-extension hopsule.hopsule-vscode

If you are using Cursor, replace code with cursor in the command above. After running the command, restart your editor to ensure all governance features are fully initialized.

Initial Authentication and Account Linkage

Once the extension is installed, it must be linked to your Hopsule account to synchronize your team's decisions and memories. This connection establishes a secure bridge between the central Hopsule Dashboard and your local development environment.

1. Click on the Hopsule icon in the Activity Bar to open the sidebar.

2. Click the Sign In button. This will open your default web browser and direct you to the Hopsule authentication portal.

3. After successfully authenticating, the browser will prompt you to "Open VS Code" (or Cursor). Confirm this prompt to pass the secure authentication token back to the IDE.

4. If the automatic redirect fails, you can manually generate an Access Token from the Hopsule Dashboard under User Settings > Security and paste it into the input box provided in the extension sidebar.

Important: Hopsule uses end-to-end encryption for all synchronized data. Your authentication token is stored securely in your system's native keychain (such as macOS Keychain or Windows Credential Manager) and is never exposed in plain text within your workspace configuration.

The First-Time Setup Wizard

After successful authentication, Hopsule for VS Code launches a setup wizard to configure your project's context. This process ensures that the extension knows which Context Packs and Capsules are relevant to the codebase you are currently editing.

The wizard will guide you through selecting an Organization and a Project. If your project already contains a .hopsule configuration file (often generated by the Hopsule CLI), the extension will automatically detect these settings and ask you to confirm them. If no configuration exists, the extension will help you create one, allowing you to link specific Context Packs—such as "Global Architecture Decisions" or "Security Compliance Memories"—to your current workspace.

Tip: If you are working in a monorepo, you can configure multiple projects within a single workspace. Hopsule will intelligently switch context as you navigate between different directories, ensuring the correct decisions are enforced for each sub-project.

Core Features and User Interface

Hopsule for VS Code is designed to be unobtrusive yet authoritative. It provides several surfaces where decisions and memories are visualized and enforced.

The Hopsule Sidebar

The sidebar is your primary interface for browsing the organizational memory. It contains several expandable sections:

• Active Decisions: A searchable tree view of all decisions currently in the Accepted state. Clicking a decision reveals its full reasoning, history, and the Memories linked to it.

• Context Packs: A list of the Capsules currently active in your project. You can toggle the visibility of specific packs to focus on relevant constraints.

• Knowledge Graph (Brain): A localized version of the Knowledge Graph that visualizes how decisions in your current project relate to one another and to broader organizational mandates.

• Conflict Monitor: A real-time list of any code sections that currently contradict established decisions.

Inline Decision Enforcement

The most powerful feature of the extension is inline enforcement. When you write code that violates an Accepted decision, Hopsule highlights the code with a diagnostic warning (similar to a linter error). Hovering over the highlighted code will reveal a tooltip containing the title of the violated decision and a brief explanation of the conflict. You can click View Decision to see the full context and reasoning in the sidebar.

The Status Bar Indicator

In the bottom status bar of your IDE, the Hopsule indicator provides a quick glance at your current governance state. It displays the number of active decisions in the current file and the status of the connection to the Hopsule API. Clicking the status bar indicator quickly opens the Hopsule Dashboard in your browser for deeper management tasks.

Privacy and Data Sovereignty

At Hopsule, we understand that your source code is your most valuable intellectual property. Our IDE extension is built with a "Privacy First" architecture. Unlike many AI-powered tools that require sending your code to a remote server for analysis, Hopsule for VS Code performs LOCAL PROCESSING ONLY.

The extension downloads the text of your team's decisions and memories and performs the enforcement logic entirely on your local machine. Your source code is never sent to Hopsule servers, and it is never used to train any models. The only data transmitted to our servers are telemetry related to decision state changes (e.g., when a decision is marked as Deprecated) and standard authentication requests. This ensures that even the most security-conscious organizations can use Hopsule to preserve their organizational judgment without compromising their data sovereignty.

Important: For Hopsule Enterprise customers using the self-hosted option, the extension can be configured to point exclusively to your internal Hopsule instance, ensuring that no data ever leaves your corporate network.

Configuration and Settings

Hopsule for VS Code offers extensive configuration options to tailor the enforcement experience to your team's workflow. These settings can be accessed via the standard VS Code Settings editor (Ctrl+,) by searching for "Hopsule".

Updating the Extension

Hopsule is a living system, and we frequently release updates to the IDE extension to improve the Knowledge Graph visualization, enhance Hopper's advisory capabilities, and add support for new Context Pack features. By default, VS Code and Cursor will update the extension automatically. However, you can manually check for updates by navigating to the Extensions view, clicking the gear icon next to Hopsule, and selecting Check for Updates.

When a major update is installed, Hopsule may present a "What's New" page highlighting improvements to the preservation and enforcement engine. We recommend reviewing these updates to ensure your team is utilizing the latest advancements in organizational memory management.

Troubleshooting Common Issues

While Hopsule is designed for high reliability, you may occasionally encounter issues related to network connectivity or local configuration.

Authentication Failures

If the extension fails to sign in, ensure that your browser is not blocking the redirect back to the IDE. If you are using a strictly firewalled environment, you may need to manually whitelist the Hopsule authentication domains. Alternatively, use the Access Token method described in the Authentication section of this document.

Decisions Not Appearing

If you have Accepted decisions in the Hopsule Dashboard that are not appearing in your IDE, check the following:

• Ensure the correct Project is selected in the Hopsule sidebar.

• Verify that the Context Packs containing those decisions are marked as Active in your project settings.

• Trigger a manual synchronization by clicking the Refresh icon at the top of the Hopsule sidebar.

Performance Impact

Hopsule is optimized for minimal resource usage. However, in extremely large workspaces with thousands of active decisions, you may experience a slight delay in diagnostic reporting. If this occurs, consider narrowing the scope of your Context Packs or increasing the hopsule.sync.interval in your settings.

Tip: If you encounter a persistent issue, you can generate a diagnostic log by running the Hopsule: Export Logs command from the Command Palette (Ctrl+Shift+P). These logs are essential for our support team to help resolve complex environment-specific problems.

Conclusion and Next Steps

With Hopsule for VS Code installed and configured, your development environment is now a participant in your organization's collective memory. Every decision made in the Hopsule Dashboard and every memory preserved in a Capsule is now actively working to guide your engineering efforts. To further enhance your team's context-awareness, we recommend exploring the Hopsule CLI for terminal integration and the Hopsule MCP for connecting external AI agents to your decision layer. Remember: an organization that remembers is an organization that scales.