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

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) 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:

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:

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 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 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.

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