# How to Use Instruction Mode (#) to Add Custom Instructions in Claudian

> Learn to use Claudian's Instruction Mode by pressing # in chat to add custom system prompts. Claude will follow your instructions in all conversations within the tab.

- Repository: [YishenTu/claudian](https://github.com/YishenTu/claudian)
- Tags: how-to-guide
- Published: 2026-03-17

---

**Press `#` in an empty chat input to activate Instruction Mode, type your custom system prompt, and press Enter to persist instructions that Claude will follow across all conversations in that tab.**

The YishenTu/claudian repository provides an Obsidian plugin that integrates Claude Code into your note-taking workflow. This guide explains how to **use instruction mode to add custom instructions** that persist across your conversations, leveraging the `InstructionModeManager` class implemented in the source code.

## Understanding Instruction Mode

Instruction Mode transforms the chat input into a direct pipeline for editing the **custom system prompt** sent to Claude Code. When activated by pressing `#` on an empty input, the feature applies the CSS class `claudian-input-instruction-mode` to the input field, changes the placeholder text to "# Save in custom system prompt", and routes submitted text to the plugin's settings storage.

## Activating and Using Instruction Mode

### Triggering the Mode

Press the `#` key when the chat input box is empty. The `InstructionModeManager.handleTriggerKey` method detects this keystroke (lines 34-41 of [`src/features/chat/ui/InstructionModeManager.ts`](https://github.com/YishenTu/claudian/blob/main/src/features/chat/ui/InstructionModeManager.ts)) and invokes `enterMode()` to switch the UI context.

### Entering and Submitting Instructions

While in Instruction Mode, type your desired instruction into the input field. The manager tracks this as `rawInstruction` internally. To save:

- Press **Enter** (without holding Shift) to submit. The `handleKeydown` method validates the non-empty instruction, prevents the default event, and executes the `onSubmit` callback (lines 84-97). This callback routes to `InputController.handleInstructionSubmit`, which stores the text in the plugin's `customSystemPrompt` setting.
- Press **Escape** to cancel. The `cancel()` method clears the textarea, exits the mode, and invokes `resetInputHeight` if configured (lines 99-104).

### Automatic Exit Behavior

If you clear the input completely while in Instruction Mode, the `handleInputChange` method detects the empty string and automatically calls `exitMode()` to restore the normal chat interface (lines 45-52).

## Technical Architecture

Each chat tab instantiates its own `InstructionModeManager` during initialization in [`src/features/chat/tabs/Tab.ts`](https://github.com/YishenTu/claudian/blob/main/src/features/chat/tabs/Tab.ts):

```typescript
tab.ui.instructionModeManager = new InstructionModeManagerClass(
  dom.inputEl,
  {
    onSubmit: async (rawInstruction) => {
      await tab.controllers.inputController?.handleInstructionSubmit(rawInstruction);
    },
    getInputWrapper: () => dom.inputWrapper,
  }
);

```

The manager handles the complete lifecycle:

- **Initialization**: Sets up event listeners for keyboard and input changes.
- **Entry**: `enterMode()` applies the CSS class `claudian-input-instruction-mode` and updates the placeholder (lines 64-70).
- **Submission**: Validates and forwards instructions to the controller.
- **Cleanup**: The `destroy()` method removes CSS classes and restores the original placeholder when the tab closes (lines 149-158).

## Programmatic Control

Developers can trigger Instruction Mode programmatically using the manager's public methods:

```typescript
import { InstructionModeManager } from '@/features/chat/ui/InstructionModeManager';

const manager = tab.ui.instructionModeManager!;

// Activate mode (simulates pressing '#')
manager.handleTriggerKey({
  key: '#',
  preventDefault: () => {},
  shiftKey: false,
  isComposing: false,
} as KeyboardEvent);

// Populate instruction
tab.dom.inputEl.value = 'Always format responses as markdown tables.';
manager.handleInputChange();

// Submit instruction
manager.handleKeydown({
  key: 'Enter',
  shiftKey: false,
  preventDefault: () => {},
  isComposing: false,
} as KeyboardEvent);

```

After submission, the custom system prompt updates immediately, and the UI returns to normal chat mode.

## Summary

- Press `#` in an empty chat input to activate **Instruction Mode** and directly modify the custom system prompt stored in `customSystemPrompt`.
- The `InstructionModeManager` class in [`src/features/chat/ui/InstructionModeManager.ts`](https://github.com/YishenTu/claudian/blob/main/src/features/chat/ui/InstructionModeManager.ts) orchestrates UI changes, input validation, and persistence.
- Submit instructions with **Enter** or cancel with **Escape**; clearing the input also exits the mode automatically.
- Each tab maintains an isolated manager instance, ensuring context-specific instructions across multiple conversations.
- Reference the test suite in [`tests/unit/features/chat/ui/InstructionModeManager.test.ts`](https://github.com/YishenTu/claudian/blob/main/tests/unit/features/chat/ui/InstructionModeManager.test.ts) for implementation details.

## Frequently Asked Questions

### What happens if I press # while text is already in the input?

The mode only activates when the input is completely empty. If characters are present, the `#` key inserts normally without triggering `handleTriggerKey` or switching to instruction mode.

### Where are the custom instructions persisted?

Submitted instructions are stored in the plugin's settings under the `customSystemPrompt` key via `InputController.handleInstructionSubmit`, making them available across Obsidian sessions.

### Can I update existing instructions using this mode?

Yes. Entering Instruction Mode again and submitting new text will overwrite the previous `customSystemPrompt` value with your latest instruction, immediately affecting subsequent Claude interactions.

### How do I visually identify when Instruction Mode is active?

The input field displays the placeholder "# Save in custom system prompt" and receives the CSS class `claudian-input-instruction-mode`, which typically renders with distinct styling (such as a gray background) to differentiate it from normal chat input.