# How to Implement Learning Mode for Interactive Developer Education in Claude Code

> Implement developer education in Claude Code with Learning Mode. This plugin injects context, explains trade-offs, and offers insights after code contributions. Learn more.

- Repository: [Anthropic/claude-code](https://github.com/anthropics/claude-code)
- Tags: how-to-guide
- Published: 2026-04-02

---

**Claude Code's Learning Mode is implemented as a plugin that registers a SessionStart hook to inject educational context, prompting the model to identify decision points, explain trade-offs, and provide concise insights after user code contributions.**

The `anthropics/claude-code` repository includes an experimental Learning Mode designed to transform passive AI assistance into interactive developer education. This feature combines the unshipped *Learning* output style with the existing *Explanatory* style to create a hands-on, "learn-by-doing" experience. By implementing learning mode for interactive developer education in Claude Code, you enable the AI to pause at critical architectural decisions, request specific code contributions, and deliver contextual educational insights.

## What Is Learning Mode in Claude Code?

Learning Mode operates as a plugin that intercepts session initialization via the **SessionStart** hook. When activated, it augments Claude's system prompt with instructions to:

- **Identify decision points** where developers can contribute 5–10 lines of meaningful code
- **Explain trade-offs** and design considerations before requesting input
- **Provide educational insights** formatted as "★ Insight" blocks after user submissions

This approach mimics pair programming with a senior developer who explains the "why" behind every implementation choice.

## Architecture and Source Code Structure

The Learning Mode implementation resides in `plugins/learning-output-style/` and consists of four interconnected components:

### Plugin Metadata ([`plugin.json`](https://github.com/anthropics/claude-code/blob/main/plugin.json))

The file at [`plugins/learning-output-style/.claude-plugin/plugin.json`](https://github.com/anthropics/claude-code/blob/main/plugins/learning-output-style/.claude-plugin/plugin.json) declares the plugin identity and version:

```json
{
  "name": "learning-output-style",
  "version": "1.0.0",
  "description": "Interactive learning mode that requests meaningful code contributions at decision points (mimics the unshipped Learning output style)",
  "author": { "name": "Boris Cherny", "email": "boris@anthropic.com" }
}

```

This metadata tells Claude Code how to treat the directory as a valid plugin and load its resources.

### Hook Registration ([`hooks.json`](https://github.com/anthropics/claude-code/blob/main/hooks.json))

Located at [`plugins/learning-output-style/hooks/hooks.json`](https://github.com/anthropics/claude-code/blob/main/plugins/learning-output-style/hooks/hooks.json), this file binds the SessionStart event to a shell command handler:

```json
{
  "description": "Learning mode hook that adds interactive learning instructions",
  "hooks": {
    "SessionStart": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "${CLAUDE_PLUGIN_ROOT}/hooks-handlers/session-start.sh"
          }
        ]
      }
    ]
  }
}

```

The `${CLAUDE_PLUGIN_ROOT}` variable resolves to the plugin's installation directory at runtime.

### Context Payload ([`session-start.sh`](https://github.com/anthropics/claude-code/blob/main/session-start.sh))

The handler at [`plugins/learning-output-style/hooks-handlers/session-start.sh`](https://github.com/anthropics/claude-code/blob/main/plugins/learning-output-style/hooks-handlers/session-start.sh) emits a JSON payload containing the learning instructions:

```bash
cat << 'EOF'
{
  "hookSpecificOutput": {
    "hookEventName": "SessionStart",
    "additionalContext": "You are in 'learning' output style mode, which combines interactive learning with educational explanations..."
  }
}
EOF

```

The `additionalContext` field contains the full instruction set that directs Claude to adopt learning behaviors, including the specific formatting for insight blocks and constraints on contribution size (5–10 lines).

### Documentation ([`README.md`](https://github.com/anthropics/claude-code/blob/main/README.md))

The [`plugins/learning-output-style/README.md`](https://github.com/anthropics/claude-code/blob/main/plugins/learning-output-style/README.md) provides user-facing documentation explaining the workflow, expected interaction patterns, and the types of code Claude will refuse to write (boilerplate, obvious implementations) in favor of educational opportunities.

## How to Enable Learning Mode

Activate the plugin using Claude Code's built-in plugin management system:

1. **Install Claude Code globally** (if not already present):

   ```bash
   npm install -g @anthropic-ai/claude-code
   ```

2. **Launch Claude Code** in your project directory:

   ```bash
   claude
   ```

3. **Install the Learning plugin** using the slash command:

   ```

   /plugin install learning-output-style
   ```

Alternatively, manually add the plugin to [`.claude/settings.json`](https://github.com/anthropics/claude-code/blob/main/.claude/settings.json) for persistent activation across sessions. Once installed, the SessionStart hook runs automatically for every Claude session—no additional configuration is required.

## Understanding the Hook Implementation

The Learning Mode hook leverages Claude Code's plugin architecture to modify session behavior at initialization time. When [`session-start.sh`](https://github.com/anthropics/claude-code/blob/main/session-start.sh) executes, it streams a JSON object to stdout containing the `hookSpecificOutput` key. Claude Code's plugin engine captures this output and merges the `additionalContext` into the system prompt.

This injection mechanism ensures that:

- **Educational constraints are active immediately** upon session start
- **The model knows to search for decision points** rather than implementing complete solutions
- **Insight formatting** ("★ Insight" headers with separator lines) is applied consistently

The shell script uses a heredoc (`cat << 'EOF'`) to preserve literal string formatting and avoid shell variable interpolation in the instruction text.

## Interactive Workflow Example

When Learning Mode is active, Claude follows a structured three-phase interaction pattern:

### Phase 1: Decision Point Identification

Claude pauses implementation to highlight an architectural choice:

```

Claude: I've set up the authentication middleware. The session timeout behavior is a security vs. UX trade-off – should sessions auto-extend on activity, or have a hard timeout?
In `auth/middleware.ts`, implement the `handleSessionTimeout()` function to define the timeout behavior.

```

### Phase 2: User Contribution

The developer writes the requested 5–10 lines:

```typescript
// auth/middleware.ts
export function handleSessionTimeout(req: Request, res: Response, next: NextFunction) {
  const lastActivity = req.session.lastActivity ?? Date.now();
  const now = Date.now();
  const elapsed = now - lastActivity;

  // Hard timeout after 30 minutes of inactivity
  if (elapsed > 30 * 60 * 1000) {
    req.session.destroy(() => res.status(401).send('Session expired'));
    return;
  }

  // Auto-extend for activity within the window
  req.session.lastActivity = now;
  next();
}

```

### Phase 3: Educational Insight

Claude responds with a formatted insight block:

```

★ Insight ─────────────────────────────────────
• Hard timeouts improve security by limiting attack windows.
• Auto-extension enhances UX but may keep sessions alive longer.
• Consider configurable timeout thresholds for flexible policies.
────────────────────────────────────────────────

```

This cycle repeats at each significant decision point until the task is complete, ensuring the developer understands the rationale behind every implementation choice.

## Summary

- **Learning Mode** is implemented as a plugin in `anthropics/claude-code` that uses the SessionStart hook to inject educational context.
- The architecture consists of [`plugin.json`](https://github.com/anthropics/claude-code/blob/main/plugin.json) for metadata, [`hooks.json`](https://github.com/anthropics/claude-code/blob/main/hooks.json) for event registration, and [`session-start.sh`](https://github.com/anthropics/claude-code/blob/main/session-start.sh) for context emission.
- Enable the feature via `/plugin install learning-output-style` or manual configuration in [`.claude/settings.json`](https://github.com/anthropics/claude-code/blob/main/.claude/settings.json).
- Once active, Claude identifies decision points, requests specific 5–10 line contributions, and delivers "★ Insight" educational blocks.
- The implementation combines the unshipped *Learning* style with the *Explanatory* style for interactive "learn-by-doing" developer education.

## Frequently Asked Questions

### How does the SessionStart hook modify Claude's behavior?

The SessionStart hook executes [`session-start.sh`](https://github.com/anthropics/claude-code/blob/main/session-start.sh) at the beginning of every Claude Code session. This script outputs a JSON payload containing `additionalContext` that augments the system prompt with instructions to adopt learning behaviors, including identifying decision points and formatting educational insights. According to the `anthropics/claude-code` source code, this hook runs before any user interaction occurs, ensuring the educational constraints are active from the first message.

### Can I customize the learning instructions or contribution size?

Yes. Modify the `additionalContext` string in [`plugins/learning-output-style/hooks-handlers/session-start.sh`](https://github.com/anthropics/claude-code/blob/main/plugins/learning-output-style/hooks-handlers/session-start.sh) to adjust the contribution size constraints (currently set to 5–10 lines) or modify the educational focus. After editing the shell script, reinstall the plugin using `/plugin reinstall learning-output-style` to load the updated context payload. The plugin architecture supports local modifications without requiring repository changes.

### What types of code will Claude refuse to write in Learning Mode?

As documented in [`plugins/learning-output-style/README.md`](https://github.com/anthropics/claude-code/blob/main/plugins/learning-output-style/README.md), Claude will skip boilerplate, obvious implementations, and repetitive code in favor of meaningful architectural decisions. The model specifically targets "decision points" where trade-offs exist between different implementation strategies, ensuring the developer writes code that requires genuine engineering judgment rather than mechanical typing.

### Is Learning Mode available in the standard Claude Code distribution?

Learning Mode is implemented as an experimental plugin in the repository and may not be enabled by default in all Claude Code distributions. Install it manually using the `/plugin install` command or check your version with `claude --version` to ensure you have access to the plugin system (available in recent builds). The feature mimics an unshipped *Learning* output style, indicating it may evolve in future releases.