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

> Discover how context-mode overcomes Cursor IDEs missing SessionStart hook by using static .mdc routing rules and injecting session context via postToolUse and stop hooks.

- Repository: [Mert Köseoğlu/context-mode](https://github.com/mksglu/context-mode)
- Tags: how-to-guide
- Published: 2026-04-24

---

**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`](https://github.com/mksglu/context-mode/blob/main/src/adapters/cursor/index.ts), the `CursorAdapter` class explicitly marks this limitation in its capability map:

```ts
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:

```bash
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`](https://github.com/mksglu/context-mode/blob/main/configs/cursor/hooks.json):

```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`](https://github.com/mksglu/context-mode/blob/main/tests/hooks/cursor-hooks.test.ts), the framework validates the JSON payload structure:

```ts
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`](https://github.com/mksglu/context-mode/blob/main/src/adapters/cursor/index.ts), which defines the `CursorAdapter` class and its capabilities. Platform-specific documentation exists in [`docs/platform-support.md`](https://github.com/mksglu/context-mode/blob/main/docs/platform-support.md), while the static routing rules are located at `configs/cursor/context-mode.mdc` in the repository.