How to Use Custom System Prompts and Instruction Mode in Claudian

You can customize Claude's behavior in Claudian by appending static instructions via the settings panel or dynamically adding temporary directives through Instruction Mode triggered by typing # in the chat.

Claudian is an Obsidian plugin that integrates Claude Code into your note-taking workflow. The plugin allows you to modify Claude's underlying system prompt—the hidden instructions that shape every response—using either persistent custom settings or on-the-fly adjustments. Mastering custom system prompts and Instruction Mode lets you tailor the AI's personality, output format, and operational constraints to match your specific research or writing needs.

How System Prompts Work in Claudian

The Base Prompt Architecture

Every query to Claude begins with a system prompt constructed by the buildSystemPrompt() function in src/core/prompts/mainAgent.ts. This function assembles a composite instruction set that includes your vault path, username, media handling rules, and export permissions. Crucially, it checks for a customPrompt value and appends it under a dedicated header.

export function buildSystemPrompt(settings: SystemPromptSettings = {}): string {
  const allowExternalAccess = settings.allowExternalAccess ?? false;
  let prompt = getBaseSystemPrompt(settings.vaultPath, settings.userName, allowExternalAccess);
  prompt += getImageInstructions(settings.mediaFolder || '');
  prompt += getExportInstructions(settings.allowedExportPaths || [], allowExternalAccess);
  if (settings.customPrompt?.trim()) {
    // Custom system prompt is inserted here
    prompt += '\n\n## Custom Instructions\n\n' + settings.customPrompt.trim();

  }
  return prompt;
}

Source: mainAgent.ts L48-L61

The QueryOptionsBuilder class in src/core/agent/QueryOptionsBuilder.ts (lines 144-169) invokes this function on every request, passing ctx.settings.systemPrompt as the customPrompt parameter.

Settings Storage

The custom prompt setting is defined in src/core/types/settings.ts (lines 260-329) with a default value of an empty string. This value persists in the plugin's settings.json file and survives across Obsidian restarts.

Method 1: Static Custom Prompts

Editing via the Settings UI

For permanent behavioral changes, modify the system prompt directly in Claudian's settings panel. The UI implementation in src/features/settings/ClaudianSettings.ts (lines 170-178) provides a textarea bound to plugin.settings.systemPrompt:

new Setting(containerEl)
  .setName(t('settings.systemPrompt.name'))
  .setDesc(t('settings.systemPrompt.desc'))
  .addTextArea(text => text
    .setPlaceholder(t('settings.systemPrompt.name'))
    .setValue(this.plugin.settings.systemPrompt)
    .onChange(async (value) => {
      this.plugin.settings.systemPrompt = value;
      await this.plugin.saveSettings();
    }));

Any markdown entered here is stored verbatim and appended to the base prompt on subsequent queries.

Programmatic Updates

You can also update the system prompt from other plugins or scripts by accessing the Claudian plugin instance directly:

// Assuming you have a reference to the Claudian plugin instance
const safetyRule = `\n- Never delete files unless the user explicitly confirms.\n`;
claudian.settings.systemPrompt += safetyRule;
await claudian.saveSettings();
// Changes take effect on the next query

Method 2: Using Instruction Mode

Instruction Mode provides a chat-based interface for incrementally adding to your custom system prompt without opening the settings panel.

Triggering Instruction Mode

When you type # in an empty chat input, the InstructionModeManager in src/features/chat/ui/InstructionModeManager.ts activates. Lines 34-40 detect the trigger key and swap the textarea placeholder to "# Save in custom system prompt", while lines 82-100 manage the text capture and submission states.

Press Enter to submit your instruction or Escape to clear the mode.

Refinement and Persistence

After submission, InputController.handleInstructionSubmit() in src/features/chat/controllers/InputController.ts (lines 81-98) coordinates the refinement workflow:

1. The raw instruction is sent to InstructionRefineService, which uses a dedicated refinement prompt to polish your directive
2. A modal dialog displays the refined version for your approval
3. Upon acceptance, the system appends the instruction to your stored prompt:

const currentPrompt = plugin.settings.systemPrompt;
plugin.settings.systemPrompt = appendMarkdownSnippet(currentPrompt, finalInstruction);
await plugin.saveSettings();
new Notice('Instruction added to custom system prompt');

This workflow ensures that even hastily typed directives (#be more concise) are expanded into properly formatted instructions before persistence.

Technical Implementation Details

Prompt Assembly and Change Detection

The final system prompt is rebuilt for every query, but Claudian optimizes performance by detecting changes. In src/core/agent/QueryOptionsBuilder.ts (lines 112-115), the system generates a systemPromptKey based on the current settings. If this key differs from the previous query's key—indicating the custom prompt has changed—the plugin forces a session restart to ensure Claude receives the new instructions immediately.

When Changes Take Effect

• Static edits via the settings UI apply to the very next message you send
• Instruction Mode additions apply immediately after the refinement modal closes and the "Instruction added" notice appears
• Session restarts occur automatically when the systemPromptKey comparison detects a mismatch, ensuring no stale context persists

Summary

• Custom system prompts in Claudian are persistent instructions stored in settings.json and appended to every Claude request under the ## Custom Instructions header.

• Instruction Mode, triggered by typing # in the chat, offers a streamlined workflow for refining and appending new directives without leaving the conversation context.

• The buildSystemPrompt() function in src/core/prompts/mainAgent.ts handles the final assembly, while QueryOptionsBuilder detects changes and manages session lifecycle.

• Changes take effect immediately for subsequent queries, with automatic session restarts ensuring consistency.

Frequently Asked Questions

Where is the custom system prompt stored in Claudian?

The custom system prompt is stored in the plugin's settings.json file as the systemPrompt property, defined in src/core/types/settings.ts. You can edit this value directly through the Claudian settings panel or programmatically via the plugin API.

How does Instruction Mode differ from editing the settings directly?

Instruction Mode provides an inline, chat-based interface for adding instructions that includes an AI refinement step. When you submit an instruction via #, the InstructionRefineService rewrites your directive for clarity before appending it to the existing custom prompt. Direct settings editing bypasses this refinement layer and replaces the content immediately.

Do changes to the system prompt take effect immediately?

Yes. The plugin detects changes via a systemPromptKey comparison in src/core/agent/QueryOptionsBuilder.ts. If the custom prompt differs from the previous query, the system initiates a new Claude session to ensure the updated instructions are active for your next message.

Can Instruction Mode replace the entire system prompt?

No. Instruction Mode in Claudian is strictly additive. It appends new instructions to your existing custom prompt using the appendMarkdownSnippet() function. To replace or clear the entire custom prompt, you must use the settings UI in src/features/settings/ClaudianSettings.ts and manually delete the contents.

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