How Context-Mode Handles the Missing SessionStart Hook in the Cursor IDE

Context-mode works around Cursor IDE's missing SessionStart hook by deploying static .mdc routing rules and injecting session context through supported hooks like postToolUse and stop.

The context-mode library (mksglu/context-mode) provides a unified hook framework for AI coding assistants across multiple platforms. While Claude Code and Gemini CLI support native session initialization, Cursor IDE's validator explicitly rejects the sessionStart hook, forcing the adapter to implement alternative initialization strategies that maintain functional parity.

Why Cursor IDE Blocks the SessionStart Hook

Cursor's validator rejects the sessionStart hook despite it being documented in the platform specifications. According to the platform-support documentation, sessionStart is "documented but currently rejected by Cursor's validator."

In src/adapters/cursor/index.ts, the CursorAdapter class explicitly marks this limitation in its capability map:

export class CursorAdapter implements HookAdapter {
  readonly capabilities: PlatformCapabilities = {
    preToolUse: true,
    postToolUse: true,
    preCompact: false,
    sessionStart: false,          // ← Cursor lacks this hook
    canModifyArgs: true,
    canInjectSessionContext: true,
  };
}

This declaration prevents the framework from attempting to register a hook that would fail validation at runtime.

Static Routing Rules: The .mdc File Workaround

Since Cursor cannot execute code at session start, context-mode substitutes static routing instructions. The library provides a .mdc configuration file that contains the same initialization logic that would normally execute in a sessionStart hook.

As noted in the README, "the .cursor/rules/context-mode.mdc file provides routing instructions at session start since Cursor's sessionStart hook is currently rejected."

Install the routing rules by copying the configuration file into your project:

mkdir -p .cursor/rules
cp node_modules/context-mode/configs/cursor/context-mode.mdc .cursor/rules/context-mode.mdc

Cursor reads this file at the beginning of every conversation, effectively providing the guidance that a runtime hook would have supplied.

Hook-Based Context Injection Through postToolUse and stop

While Cursor rejects sessionStart, it still accepts additional_context in responses from other valid hooks. Context-mode leverages the postToolUse and stop hooks to inject session-level data even without native session initialization.

The platform-support documentation notes that additional_context is "accepted but not surfaced" to the model due to a known upstream bug. Despite this display limitation, the data remains available for downstream processing.

Configure the available hooks in configs/cursor/hooks.json:

{
  "version": 1,
  "hooks": {
    "preToolUse": [{ "command": "context-mode hook cursor pretooluse" }],
    "postToolUse": [{ "command": "context-mode hook cursor posttooluse" }],
    "stop": [{ "command": "context-mode hook cursor stop" }]
  }
}

These hooks format responses to include required session data, ensuring context availability across the conversation lifecycle.

Implementation Details and Code Examples

The test suite verifies that session context generation works correctly despite the missing hook. In tests/hooks/cursor-hooks.test.ts, the framework validates the JSON payload structure:

const result = runHook("sessionstart.mjs", { 
  source: "startup", 
  conversation_id: "cursor-hook-start-1", 
  cwd: tempDir 
}, cursorEnv());

expect(JSON.parse(result.stdout).additional_context).toContain("context-mode");

This ensures that even though Cursor cannot trigger the hook natively, the context-mode library maintains API compatibility across platforms.

Summary

• Cursor IDE explicitly rejects the sessionStart hook at the validator level, requiring alternative initialization methods.
• Static .mdc rules files substitute for dynamic session initialization by providing routing instructions when conversations begin.
• Supported hooks (postToolUse and stop) accept additional_context parameters to inject session data despite the missing native hook.
• The CursorAdapter explicitly declares sessionStart: false in its capabilities map to prevent validation errors.

Frequently Asked Questions

Why doesn't Cursor IDE support the SessionStart hook?

Cursor's validator explicitly rejects sessionStart even though it appears in the platform documentation. According to the platform-support documentation in mksglu/context-mode, the hook is "documented but currently rejected by Cursor's validator," making it unavailable for runtime session initialization.

How does the .mdc file replace the SessionStart hook?

The .mdc file contains static routing instructions that Cursor reads at the beginning of every conversation. While it cannot execute dynamic code like a true hook, it provides the same configuration context by loading rules from .cursor/rules/context-mode.mdc when the IDE initializes the chat session.

Can context-mode still inject session context without the SessionStart hook?

Yes. Cursor accepts additional_context in responses from postToolUse and stop hooks. Context-mode formats these responses to include session-level data, ensuring the required context is available for downstream processing even though Cursor does not surface it to the model due to a known upstream bug.

Where is the Cursor support implemented in the source code?

The Cursor-specific adapter logic resides in src/adapters/cursor/index.ts, which defines the CursorAdapter class and its capabilities. Platform-specific documentation exists in docs/platform-support.md, while the static routing rules are located at configs/cursor/context-mode.mdc in the repository.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}